docsget startedquickstart

Quickstart

From a clean machine to your first agent. Clone, run, then author from the server dashboard or from Claude Code.

Cast runs on your own machine — a Node process that orchestrates Claude agents in isolated containers. Setup is honest about what it needs (a container runtime is not optional) but doesn't ask you anything twice.

Prerequisites

  • macOS (preferred), Linux, or Windows via WSL2
  • Node.js 20+
  • A container runtime: Apple Container (macOS 26+) or Docker. Required. Without it, agents can't run.

1. Clone and run

bash
git clone https://github.com/yaodub/cast.git
cd cast
npm i -g pnpm
pnpm start

pnpm start does the rest: installs dependencies, builds the dashboard and server bundle, builds the agent container image (~2 min on first run), then starts the server. Your browser opens to the dashboard at http://localhost:5051/admin/.

💡 TIP
Subsequent runs skip the build steps. To update Cast, git pull && pnpm start — the script detects what changed and rebuilds only what's needed (usually under a minute).
⚠ HEADS UP
If pnpm start reports "container runtime not running," start the daemon: container system start on Apple Container, or launch Docker Desktop.

2. Author your first agent

Cast has two authoring modes. They write the same agent files on disk — switch between them anytime. The in-browser consoles are an early preview we're still sharpening; Claude Code is mature terminal tooling. Either way the agent you ship is the same, and if a console stalls, every agent is plain files you can edit by hand or hand to Claude Code. Pick whichever fits how you work:

All in the browser. On first launch the dashboard pops a credential modal. Two options:

  • Anthropic API key — create one at console.anthropic.com/settings/keys, paste, save. Billed per token to your Anthropic account.
  • Claude OAuth token — if you have a Claude.ai plan and the Claude Code CLI installed, run claude setup-token in your terminal and paste the result. Usage draws from your Claude plan.

Save verifies the credential against Claude before accepting. The server hot-reloads — no restart.

With Claude wired up and no agents on the server, the dashboard automatically docks Design at the bottom of the screen. Describe the agent you want:

You ask Design
I want an agent that reads my morning emails and surfaces the ones worth replying to today. Keep it terse, no commentary on the obvious ones.

Design scaffolds the agent — picks an alias, writes its identity, sets up channels and props, registers it on the server. From there Configure wires it to your install (model, secrets, transports), Review promotes it from draft to live, and you open its web chat URL, let yourself in, and talk. Full walkthrough: Your first agent.

What's next