Reference

Settings, files, fixes and limits.

For CAST 0.1.0

Configuration

Everything is optional. Set environment variables before you start CAST, or put the same settings in <data folder>/config.json. Environment variables win over the file. Older RLT_* names still work; CAST_* wins when both are set.

Variable	`config.json` key	Default	What it does
`CAST_PORT`		`4860`	HTTP and WebSocket port
`CAST_HOST`		`127.0.0.1`	Address to listen on. Read Phones and other devices before changing it
`CAST_DATA_DIR`		`~/.local/share/cast` (Linux), `~/Library/Application Support/CAST` (macOS)	CAST's own state: city, jobs, chats, token, devices
`CAST_WORKSPACE`	`workspace`	`~/CAST`	Where new projects are created
`CAST_FS_ROOTS`	`fsRoots`	your home folder	Folders the folder picker may browse (comma-separated)
`CAST_CITY_NAME`	`cityName`	the machine's host name	This city's name in the city menu
`CAST_TERMINAL`	`terminal`	on	`false` turns off the browser terminal
`CAST_ALLOWED_USERS`	`allowedUsers`	none	Tailscale logins let in without pairing (only through `tailscale serve` on this machine). Then any program on that machine can sign in as you: set it only where you trust every local account and process
`CAST_ALLOWED_ORIGINS`	`allowedOrigins`	none	Extra origins allowed to open the live connection (a reverse proxy)
`CAST_AGENT_BIN`		the bundled engine	A `cast-agent` to run instead of the bundled one
`CAST_AGENT_TIMEOUT`		`60`	Seconds CAST waits for `cast-agent --version` and `cast-agent models` (5–3600)
`CAST_AGENT_START_TIMEOUT`		`45`	Seconds before a person's engine counts as failed to start; stretched up to 4× while it reports progress
`CAST_LOGIN_TIMEOUT`		`900`	Seconds a sign-in under Models & providers waits for you before it gives up
`CAST_VIEWER_HOSTS`		none	Extra hosts that pages in the file viewer may load from (space or comma list, such as `https://cdn.example.com *.example.org`)
`CAST_WEB_DIST`		`web/dist` (compiled CAST: `web/dist` next to it)	The built web app to serve
`PI_CODING_AGENT_DIR`		`~/.omp/agent`	The CAST engine's own folder (sign-ins, settings)
`ANTHROPIC_API_KEY` and others			Provider keys, see Connect an AI account
	`ompEnv`	none	Extra environment for every engine CAST starts, as `{ "NAME": "value" }`. Models & providers writes `GOOGLE_CLOUD_PROJECT` and pasted API keys here; the server's own environment wins. Changes made in the app apply without a restart
`CAST_KEY_CHECK`		on	`0` saves a pasted API key without asking its vendor first (machines without internet access to Anthropic, OpenAI or Google)
`CAST_SERVICE_WORKER`		on	`off` serves a worker that removes itself and CAST's caches from every browser
`CAST_PUSH`		on	`off`: no notifications at all; Settings says so
`CAST_PUSH_CONTACT`		the address the device subscribed from	The contact sent to push services (`mailto:[email protected]` or an `https:` URL). Set it if the test notification reports `BadJwtToken`

An example config.json:

{
  "workspace": "/home/you/Projects",
  "fsRoots": ["/home/you/Projects", "/home/you/Writing"],
  "cityName": "Workstation",
  "allowedOrigins": [],
  "allowedUsers": [],
  "terminal": true
}

Settings for development and debugging are in CONTRIBUTING.md.

Where CAST keeps things

The data folder (CAST_DATA_DIR): city.json, jobs.json, workflows.json (each house's workflows and the library), token, devices.json, cities.json, push.json (the Web Push key and the devices that turned notifications on), config.json (with any API keys you pasted), engine sessions (sessions/), chat history (transcripts/), chat images (uploads/) and the jobs' own copies of files (worktrees/). It is readable only by you.
Inside your projects: a .rlt/ folder for team-run notes (hidden from git through the project's .git/info/exclude), checkpoints under refs/rlt/checkpoints/* and job copies on branches named rlt/<project>/<job>. CAST never commits to your branches, moves HEAD or touches your staged changes.
The CAST engine's folder (~/.omp/agent, or PI_CODING_AGENT_DIR): AI sign-ins and the engine's own settings.
The Mac app's log: ~/Library/Logs/CAST/server.log.

"rlt" is CAST's old internal name. It stays in file names and ids so existing installs keep working.

Troubleshooting

Start with Help → About → Copy diagnostics in the app: it lists the versions, the connection, the graphics and the browser, and leaves out addresses, logins, paths and project names.

Problem	What to do
"The agent (cast-agent) isn't built, so nobody can work yet", or people can't start	Source install: run `bun run build` in the CAST folder. Or point `CAST_AGENT_BIN` at a `cast-agent`. Then press Check again on the banner or restart CAST
A banner says the cast-agent version is untested	It only happens when `CAST_AGENT_BIN` points at another build. Unset it to use the bundled engine, or keep going: most things still work
`port 4860 is taken`, or the server won't start	Another program (or another CAST) uses the port. Stop it or set `CAST_PORT`
Nobody works, or the chat box is locked	No AI account is connected for that person's model. Connect one in Models & providers (the Connect AI button in the top bar), or pick a model whose account is connected
Chats stay locked although you signed in	Press Refresh in Models & providers. A key exported in the shell needs a CAST restart; a key pasted on a provider's card doesn't
The top bar says Check failed	CAST couldn't ask the engine which accounts work. It tries again by itself; press Refresh in Models & providers, and see Help → Agent. A slow engine gets more time with `CAST_AGENT_TIMEOUT`
The page says you need to pair, or "403"	Open the pairing link again. After the token was replaced, every device needs the new link
"Reconnecting…" never ends behind a proxy	The proxy must pass WebSockets, and its public origin must be in `CAST_ALLOWED_ORIGINS`
"another CAST server … is already using the data folder"	One server per data folder: a second one would stop the first one's agents. Stop the running one first, or start the new one with its own `CAST_DATA_DIR`
Black or empty 3D view	Your browser has WebGL 2 off or no GPU access. Turn on hardware acceleration, or use the Town board (`)
The first load is slow	A computer downloads about 12 MB before the 3D town appears, then everything comes from the browser cache. Phones start on the Town board. The first time you enter a house its furniture and people load ("Furnishing the house…")
A phone reloads the page or gets hot	Use Low quality (top bar)
The terminal opens in the wrong folder or shell	It starts your login shell (`$SHELL`) in the project folder; check your shell's start-up files
The Home Screen app asks to be paired again	It has its own sign-in, separate from Safari: paste a link from Copy a link for the app or type the short code (Install CAST on your phone)
No notifications on iPhone	They work only in the app on the Home Screen (iOS 16.4+). Check iOS Settings → Notifications → CAST, then Send a test notification. If it reports `BadJwtToken`, set `CAST_PUSH_CONTACT`
The installed app shows an old version or "CAST can't be reached" although CAST runs	Settings → Notifications & app → Reset the app's cache, or open CAST with `?sw=off`
The Mac app won't open the first time	See The Mac app → Install it

Known limits

CAST is young (version 0.1). It is developed on Linux; macOS should work but is less tested. Windows is not supported (use WSL 2).
Rendering is tuned for integrated GPUs on Medium; very old GPUs and phones need Low.
City name tags are not hidden by buildings in front of them, and the car drives through hedges and benches.
Agents that sit idle for 10 minutes are stopped (at most 10 run at once) and start again on your next message.
Changing a job's brief, kind or lead model (or adding, renaming or deleting a job) restarts the engine of the people affected on their next message: same chat, but "allow for this session" approvals are asked again.
Sessions with branches show as one linear chat. Token and cost counters start at zero after a restart.
The diff viewer shows diffs up to about 400 KB.

Getting help

Open an issue with the diagnostics and what you did, expected and saw.
Security problems go through private reporting instead: the repository's Security tab → Report a vulnerability (SECURITY.md).
How it fits together: ARCHITECTURE.md. Contributing: CONTRIBUTING.md.