Use CAST

Your first project

1. Connect an AI account. Until one is connected, nobody can work.
2. Click a For sale lot in the town and pick a project folder, or create a new project from a template. New projects go to ~/CAST.
3. Click the new house to walk in. The chat with its lead opens: say what you want done.

Getting around

In the town, drag to orbit, right-drag to pan and scroll to zoom. Click a house to walk in, and the front door to walk out.

• Help: the ? button in the top bar (on a phone, in the ⋯ menu), or press ? anywhere. It has the town's words, every keyboard shortcut, the engine's status and a diagnostics block for bug reports.
• The Board: everything in 3D can also be done from the 2D panels and the command palette (Ctrl+K, ⌘K on a Mac). The Board (the Town view switch in the top bar, or `) lists every house instead of the 3D town: quicker on slow computers and easiest with a keyboard or screen reader. CAST remembers the choice, and a Board start never loads the 3D town.
• Links: /#/house/<project> opens a house, /#/house/<project>/<job> one of its jobs.

Chatting

Click a person to chat with them. Entering a house opens the chat with its lead: the Assistant, Developer, Writer or Researcher, depending on the job. You can attach images, stop a reply, and start a new chat or reopen an older one from the bar above the chat. Every chat survives a server restart, and the model remembers a chat you reopen.

Permission modes

The chip under the message box sets how often people ask before they act. Alt+M in the message box cycles the first three.

When a person waits for you, they raise a hand, the house gets an amber beacon, and an approval card shows up. With the card focused, A approves and D denies. Approvals wait until you answer.

Jobs, rooms and floors

A job is a separate line of work in the same folder, with its own people, chats and team: say, one job writes the novel and another builds a website for it. Each job has a room. Every house starts with one job, Main, in room 1A.

• The job bar at the top of the side panel (or J) switches jobs.
• + New job asks for a name, a kind (General, Code, Write or Research), a lead model, an optional team and brief, and a free room.
• In a git project a new job can work in its own copy of the files (a git worktree on its own branch), so jobs don't step on each other. Bring the copy's changes into the house when you are happy with them.
• The job's ⋯ menu renames, edits, moves or deletes it. Its files and chat history stay on disk.
• Floors: the elevator buttons on the left switch floors (PageUp / PageDown). + adds a floor with four more rooms, up to five floors.

Teams (workflows)

A workflow is a team: each step is a different person and can be a different model, and review steps can send work back.

• The lead can bring in helpers and whole teams on its own. How much it asks first is the job's work style: Show me the plan first (a plan card in the chat shows who does what on which model, and waits for Run), Just go, or Only when I ask.
• Start one yourself in the Workflow tab: choose one of the house's workflows (or design one with the lead), type the task and press Run.
• Stop run aborts it, and Revert files puts the folder back to the checkpoint taken before the run. Your branches, HEAD and staged changes are never touched.
• A lead starts at most 5 teams on its own for one of your messages. That is a guard against endless loops, not a cost limit, and your next message starts the count over. A house can allow more or fewer: the house's ⋯ menu → Team runs per message… (1–50, or Use default).

Each house has its own workflows

A new house has none until you or the lead make one. The lead puts a team together for each task; Keep this team on such a run saves it, and Create with the Assistant (or whoever leads the job) in the Workflow tab designs one with the lead in chat. A saved workflow belongs to the house it was made in: only that house lists it, runs it and can make it a job's team.

To share one, open it in the Workflow tab and press Put in the library (the book button by the Team heading). Every house's Workflow tab lists the Library under its own workflows, and Import copies one into that house. From then on it is that house's own: changing it there changes nothing else. Removing a house removes its workflows; the library keeps what was put in it.

Goals

Set a goal… in a lead's chat gives it an objective, and optionally a token budget. It keeps working turn after turn until the goal is done or the budget runs out. Pause, resume or drop it from the bar at the top of the chat.

Changes, files and the terminal

• Changes: the Changes tab and the living-room TV show the project's git diff.
• Files: Browse files opens the file viewer, which also shows .html files as live, sandboxed pages.
• Terminal: Ctrl+` (or Terminal in the bottom bar, or click a computer on a desk) opens a real login shell on this machine, docked at the bottom, as the user CAST runs as. The first time, the browser asks you to confirm and names that user and machine. The dock keeps a user@host chip, red for root. In a house it starts in the project folder.

Settings and graphics

• Settings (the gear in the top bar; on a phone, in the ⋯ menu), for this device: the theme (System, Dark or Light), the town view (Board or 3D), single-key shortcuts (switch them off if you use voice control, dictation or a screen reader; they start off on touch devices), screen reader support for the terminal, and solid (non-see-through) panels. Text follows your browser's font-size setting. For the machine: paired devices, pairing a phone, the terminal and your data.
• You: you are in the town too. Your avatar walks over when you open a chat, sits at a desk when you open the terminal and takes the stairs when you switch floors. Pick your look in the graphics menu (top bar) under You.
• Graphics: the top bar has the quality (Low, Medium, High, Ultra; picked automatically and remembered) and the time of day (Auto follows your clock, or pin Day, Golden hour or Night). Use Low or Medium on laptops and phones. ?q=low in the address forces a preset for one visit, and ?2d / ?3d picks the view for one visit.
• The 3D view draws at full rate only while something moves; idle animations run at 30 fps and a background window at 15 fps. When frames stay below 30 fps at full resolution, CAST lowers the preset one step and says so in a toast you can click to undo. It never raises the preset by itself.
• Driving (optional, never needed): D in the town, then W A S D or the arrow keys, Space to brake, E to enter the house you parked at, Esc to leave the car.

Keyboard

Help (?) lists every shortcut.

More than one machine

Each machine running CAST is a city with its own houses, agents and AI accounts. Pick one CAST as your home (the one your browsers are paired with) and add the others to it:

1. Install and start CAST on the other machine, and make it reachable from the home machine: Tailscale, your LAN, or an SSH tunnel (below).
2. On the home CAST, open the city menu (top left, before the house name) and choose Add a city….
3. Enter the other machine's address (for example https://workstation.your-tailnet.ts.net or http://192.168.1.20:4860) and paste its pairing link or token (Pair your browser).

Switch cities from the same menu. Your browser only ever talks to the home CAST, which forwards each city's pages and connections to that machine, so phones and other devices need no extra pairing.

• AI accounts are not shared. Each city's agents run on that machine, with the accounts signed in there. Models & providers always shows the accounts of the city you are looking at.
• The home CAST keeps a session for each added city in cities.json, never the pairing token. Anyone who can use the home CAST can use the added cities through it, and an added city's pages run inside the home CAST, so a city can act on the home machine too. Only add machines you control.
• The other machine needs a CAST version with city support. If it is older, CAST tells you to update it first.

Phones and other devices

CAST works on phones and tablets: the side panel becomes a bottom sheet, and Help and the dialogs fit small screens. On the Board a phone gets more: a chat is a whole page, the board lists Waiting for you first, the house you are in comes first, and a job whose people answered while its chat was closed says New reply. Use Low quality on phones.

Every device must be paired once. Ways to reach CAST from another device, best first:

• Tailscale (recommended): tailscale serve --bg --https=8443 http://127.0.0.1:4860 makes CAST available over HTTPS to your tailnet only, at https://<machine>.<your-tailnet>.ts.net:8443. Never use tailscale funnel: that is the public internet.
• SSH tunnel: ssh -L 4860:127.0.0.1:4860 you@machine, then use http://127.0.0.1:4860 on your computer.
• Your LAN: CAST_HOST=0.0.0.0 makes CAST listen on every network interface, without encryption: the pairing link and the cookie travel in clear text. Only on a network where you trust every device.

Once one browser is paired, pair the rest from Settings:

• Pair a phone shows a QR code and a link that work once and expire after 10 minutes, so the master token never leaves the machine.
• Devices lists every paired browser with when it was last seen. Revoke one to sign it out at once. New pairing link rotates the token; existing devices stay signed in unless you choose to sign them all out.
• Your data can delete all of CAST's data (city, chats, devices, token) and restart with an empty town. Your project folders stay on disk.

Install CAST on your phone

CAST installs as an app (a PWA): its own icon and window, no address bar, a badge with the number of answers you owe, and notifications when someone needs you. It needs a secure address: your tailscale serve address (https://…ts.net), or http://127.0.0.1:4860 on the computer running CAST. Settings → Pair a phone → Install CAST on this device shows the steps for the browser you are in.

iPhone and iPad (Safari, iOS 16.4 or later)

1. Pair Safari as usual: scan the QR code from Settings → Pair a phone on your computer.
2. Tap Share (□↑) → Add to Home Screen. Keep Open as Web App on.
3. Open CAST from the Home Screen. The app keeps its own sign-in, separate from Safari: in Safari, Settings → Pair a phone → Copy a link for the app, then paste it in the app. Or type the 12-character code shown under the QR code on your computer. Either works once, within 10 minutes.
4. In the app, Settings → Notifications & app → Turn on notifications for this device, allow them, and Send a test notification. iPhone shows notifications from web apps only once they are on the Home Screen.

Android, Windows, Linux, ChromeOS and Mac

• Chrome or Edge: the install button in the address bar or the browser menu (Install CAST / Add to Home screen). The installed app shares the browser's sign-in.
• Mac: Safari → File → Add to Dock, or Chrome's install button. The Mac app opens CAST in your browser; install it from there in the same way.

What you get

• Notifications (Settings → Notifications & app): someone waits for your OK, a question or a plan; a team run finished or failed; optionally, someone stopped with an error. They are encrypted end to end and say only who needs you and where, never commands, code or what was asked. CAST must reach the internet to send them.
• The icon badge counts the answers you owe.
• Offline: when the phone has no connection or the computer sleeps, the app says so and opens CAST again by itself once it answers. Nothing of your town is stored on the phone.
• Updates arrive on their own: an open page says "CAST was updated" with a Reload button. The installed app's ⋯ menu has Reload CAST.

If the installed app misbehaves, Settings → Notifications & app → Reset the app's cache (the device stays paired). In a browser, adding ?sw=off to the address does the same.