docsadvancedruntime options

Runtime options

Every environment variable the Cast server reads, with defaults and effects.

Source-of-truth for the schema: packages/cast/src/env.ts. Most defaults are fine for personal use — reach for these when you want a different data location, port-pinning, or multi-instance setup.

Data location

Field	Type	Default	Effect
CAST_AGENTS_DIR	path	required	Directory holding agent instance folders. The wrapper scripts default it to `~/.cast/agents/`.
CAST_CONFIG_DIR	path	required	Server-level config and SQLite databases (`routes.json`, `firewall.json`, `gateway.db`, `host.db`). The wrapper scripts default it to `~/.cast/config/`.

Both default to subdirectories of ~/.cast/ — deliberately outside the Cast source repo so updates and clones never touch user data. The wrapper scripts (pnpm start, pnpm dev) resolve these defaults and create the directories if missing; the server itself requires the env vars to be set explicitly (no defaults in env.ts).

💡 TIP

Two Cast clones share ~/.cast/ by default — same model as ~/.claude/, ~/.npm/. If you want isolation per clone, set CAST_AGENTS_DIR and CAST_CONFIG_DIR explicitly in each clone's shell.

Container runtime

Field	Type	Default	Effect
CAST_RUNTIME	enum	auto	`auto` prefers Apple Container on macOS and Docker elsewhere (including Linux and Windows/WSL2); force a choice with `docker` or `apple-container`.
CONTAINER_IMAGE	string	cast-agent:latest	Agent container image tag. Release builds also tag `cast-agent:<version>`.

Port

Cast runs as two processes: the API server and the web UI in front of it. Each has its own port. 5051 — the web UI — is the address you open; CAST_PORT sits behind it. (PORT is read by the web-UI process, not the server, but it's listed here since it's the port you actually visit.)

Field	Type	Default	Effect
PORT	int	5051	The web UI's port — what you open in a browser. It proxies API and WebSocket traffic to `CAST_PORT`, so this is the only port a user needs.
CAST_PORT	int	5050	Port for the Cast API server and its WebSocket — the target the web UI proxies to. Set `0` to let the OS pick a free port (printed in the startup banner).

Limits and timeouts

Field	Type	Default	Effect
MAX_CONCURRENT_CONTAINERS	int	3	Global cap on simultaneous agent containers (minimum 1).
CONTAINER_TIMEOUT	ms	1800000	Max wall-clock time for a single container run (30 min).
CONTAINER_MAX_OUTPUT_SIZE	bytes	10485760	Cap on a single container run's captured output (10 MB).
IDLE_TIMEOUT	ms	1800000	How long a container stays alive after responding, waiting for follow-up messages (30 min).
MAX_ATTACHMENT_MB	int	10	Per-message attachment size limit, in MB.

Offline mode

Field	Type	Default	Effect
CAST_DISABLE_UPDATE_CHECK	bool	false	Skip the update check against `api.getcast.dev`.
CAST_DISABLE_MODEL_REFRESH	bool	false	Skip the model-catalog refresh; fall back to the embedded snapshot.

Secrets (.env-only)

These are read from .env in the working directory only — never from process.env. Keeps credentials off shell history and out of inherited environments.

Field	Type	Default	Effect
AUTH_MODE	enum	—	`api-key` or `setup-token` — selects which credential below is used.
ANTHROPIC_API_KEY	string	—	Anthropic API key, for `api-key` mode.
CLAUDE_CODE_OAUTH_TOKEN	string	—	OAuth token from `claude setup-token`, for `setup-token` mode.

Running multiple instances

Cast is a single Node process. To run more than one (per-user, per-project, per-environment), point each at a distinct data dir and port:

bash

CAST_AGENTS_DIR=~/cast-work/agents \
CAST_CONFIG_DIR=~/cast-work/config \
CAST_PORT=3002 \
pnpm start

CAST_AGENTS_DIR=~/cast-personal/agents \
CAST_CONFIG_DIR=~/cast-personal/config \
CAST_PORT=3003 \
pnpm start

Each instance gets its own agent folders, gateway DB, and config files. Credentials in .env are shared because .env lives in the source repo — separate clones or distinct .env files if you want credential isolation too.