CAST
Docs menu

Install

CAST runs on your own machine, on Linux or macOS. On Windows, use WSL 2. Take the download for your machine, or build CAST from source.

For CAST 0.1.0

Download

What you need

CAST's interface is in English.

The Mac app

CAST.app lives in the menu bar (no Dock icon), starts the CAST server for you and shows how the town is doing: a plain icon when all is quiet, a dot while people work, and an orange badge with a count when someone waits for your approval or answer. It needs no Bun of your own. It does use the Mac's git.

Install it

  1. Download CAST-0.1.0-arm64.dmg (above), open it and drag CAST onto Applications.
  2. Open CAST from Applications. The app is signed with a Developer ID and notarized by Apple, so it opens like any app; macOS may ask once whether to open an app downloaded from the internet.
  3. Choose Open CAST in its menu. It signs this Mac's browser in with a one-time link, so there is no token to copy.

Built the dmg yourself? That copy is signed ad hoc, so another Mac asks you to confirm it once: right-click CAST → Open, or on macOS 15 and later System Settings → Privacy & Security → Open Anyway.

The menu

Open CAST, Pair a phone… (opens Settings → Pair a phone), the items waiting for you, Open at login, Restart CAST, Show logs, About CAST, Check for Updates… and Quit CAST, which stops the server, its agents and terminal shells.

If a CAST is already running on port 4860 (for example one you started from source), the app shows that one instead of starting a second, and leaves it running when you quit the app.

Where it keeps things

Every browser you open with Open CAST gets its own entry in Settings → Devices. The app itself is listed there as This Mac's menu bar.

The Linux build

The Linux build is the CAST server compiled into a single file, cast-server, with the CAST engine (cast-agent) and the web app (web/dist) next to it. Keep the three together. You don't need Bun.

tar xzf cast-0.1.0-linux-x64.tar.gz
cd cast-0.1.0-linux-x64
sha256sum -c SHA256SUMS      # optional: nothing was damaged on the way
./cast-server

On the first start CAST creates its data folder (~/.local/share/cast, or $XDG_DATA_HOME/cast), an empty workspace folder ~/CAST for new projects, and a secret pairing token. It prints where that token is, never the token itself. The town starts empty: no houses until you place one. Next: pair your browser.

Keep it running

To keep CAST running after you close the terminal, use whatever you normally use for services: a systemd --user unit, tmux, or:

nohup ./cast-server > cast.log 2>&1 &

Stop it with Ctrl+C or kill <pid>. Agents and terminal shells stop with it.

Build from source

Works on Linux and macOS, including Intel Macs.

You also need

Get CAST, build it and start it

git clone https://github.com/JirapatWov/cast-town cast
cd cast
bun install
bun run build        # builds the web app into web/dist and the CAST engine into agent/
bun run start

The CAST engine comes with CAST, in agent/: there is nothing else to install. agent/bin/cast-agent --version prints the version of the project it is based on (omp/18.13.2), and its own help keeps that name. That is expected.

CAST looks for the engine in this order: CAST_AGENT_BIN (a path to a cast-agent), the cast-agent next to a compiled CAST (the Mac app and the Linux build), then agent/bin/cast-agent in the CAST folder.

The first start works as described for the Linux build, with bun run start in place of ./cast-server. On macOS the data folder is ~/Library/Application Support/CAST.

Pair your browser

CAST only lets in browsers that were paired once with a secret link. The link is swapped for a session cookie for that browser, and the address bar shows the clean address. Bookmark http://127.0.0.1:4860.

echo "http://127.0.0.1:4860/?token=$(cat ~/.local/share/cast/token)"                  # Linux
echo "http://127.0.0.1:4860/?token=$(cat ~/Library/Application\ Support/CAST/token)"   # macOS

The pairing link works like a password. Don't share it. Once one browser is paired, pair phones and other devices from Settings → Pair a phone, which makes a link that works once and expires after 10 minutes (Phones and other devices).

Then connect an AI account and place your first project. The welcome steps in CAST lead you through both.

Updating

git pull
bun install
bun run build
bun run start

CAST's data files are only ever extended, so an update keeps your town, jobs and chats. If the engine is not the version the new CAST is tested with, the app shows a banner, and Help → Agent shows the running version.

Uninstalling

Stop CAST (Mac app: Quit CAST in its menu), then delete:

  1. CAST.app, the Linux build's folder, or the CAST folder you cloned;
  2. the data folder (Where CAST keeps things). This removes your town, chats, pairing and added cities;
  3. in each project, if you want them gone: the .rlt/ folder, the .rlt/ line in .git/info/exclude, CAST's refs, job branches (git branch --list 'rlt/*', delete the ones you don't need) and leftover worktrees (git worktree prune). CAST's refs go with:
git for-each-ref --format='%(refname)' refs/rlt | xargs -r -n1 git update-ref -d
  1. the workspace folder ~/CAST, if you don't want the projects CAST created there;
  2. ~/.omp, the CAST engine's folder with your AI sign-ins, if nothing else uses it.