Skip to main content
Run a swarm of Claude Code agents in StateSet sandboxes, toward one goal, from a terminal you can leave: Ghostty as the terminal, Herdr as the workspace that keeps your panes and lists your agents, and Claude Code as the agent you talk to. You write a goal. A planner agent splits it into tasks. A coordinator starts one sandbox per task, a reviewer agent checks each result, and accepted work is merged onto one branch on your machine. Sandboxes hold no GitHub credentials: work comes back as patches, and nothing is pushed or merged for you.
Every command on this page was checked against the tools’ own help and the Sandbox source (CLI 3.4.0, MCP server 0.5.0, Herdr 0.9.3). The sequence as a whole has not yet been run end to end on a clean machine.

What runs where

The work happens in the sandboxes, so a swarm costs the workstation almost nothing. Closing Ghostty does not stop it: Herdr’s session and the sandboxes go on.

Before you start

  • A StateSet Sandbox account, an API key and a card on file. Without a card, creating a sandbox answers 402 PAYMENT_METHOD_REQUIRED.
  • Node.js 20.19 or later in the 20 line, or 22.12 or later, and git.
  • Ghostty, Herdr and Claude Code, installed from their own sites.
  • A git repository for the swarm to work on, with the base branch committed. Uncommitted work is not uploaded.
  • Model access for the agents in the sandboxes: a provider key or a Claude subscription token stored as an organization secret. Model charges are separate from sandbox compute.

1. Install

The planner and the coordinator are not in the npm package. They run from a checkout of the Sandbox repository, with the SDK and the CLI built:

2. Open Ghostty and start Herdr

Open Ghostty and run:
Make three panes: one for Claude Code, one for the swarm, one to watch it.
herdr tab create --label swarm --cwd PATH makes a tab where a split is too narrow, for example on a phone.

3. Start Claude Code and give it the swarm tools

In the first pane, in your repository:
Claude Code now has the sandbox tools, among them swarm_list, swarm_get, swarm_create and swarm_cancel. swarm_create stores a plan and swarm_cancel marks a swarm cancelled at the service; neither starts or stops a sandbox. Herdr lists this session as an agent, with its state.

4. Write the goal

A goal is a short text file: what to build, where in the repository, and how you will know it is done. Ask Claude Code to draft it with you, then read it. The goal is the one thing the planner sees.

5. Plan it

In the second pane, in the checkout:
One planner agent, in one sandbox, writes plan.json: tasks with an id, an objective and depends_on. It starts none of them and never replaces an existing plan. Read the plan before you run it, and edit it if a task is wrong.

6. Run it

The run stays in the foreground and prints a table as tasks move. It exits 0 only if every task was accepted. Run the same command again on the same state directory and it resumes.

7. Watch it

In the third pane:
Or ask Claude Code in the first pane: “List the running swarms and show the tasks of the newest one.” It answers through swarm_list and swarm_get. The dashboard shows the same record at /dashboard/swarms. herdr agent list shows every agent Herdr knows and which are waiting for you.

8. Take the result

Accepted work is on the branch swarm/run-1 in your repository, named after the state directory. Nothing was pushed.
Read the table before the diff. Only one outcome means the work was judged good:

Leaving it running

  • Closing the window. Herdr’s session is persistent: open Ghostty again, run herdr, and the panes are where you left them.
  • A backlog of goals. swarm-dispatch.mjs takes goal files from a directory one after another, under a daily budget and a budget per goal. It never pushes or merges.

What goes wrong on the first day

  • 429 when several sandboxes start at once. Keep the default --max-parallel and --launch-gap; do not start swarms in a loop.
  • An agent killed during an install. A sandbox that is not given a size has 2Gi. Set "sandbox": { "memory": "4Gi", "cpus": "2" } in the plan (8Gi for a large monorepo).
  • Tests that fail only in the sandbox. Sandboxes set NODE_ENV=production. Tell the agent to run npm ci --include=dev, and to run a React test suite as NODE_ENV=test npm test until the project’s own test set-up does that.
  • The model refuses every agent. An exhausted model account stops the work; nothing is wrong with the goal. Add --preflight and --wait-for-model so the run checks the model first and waits when it is refused.
  • Work lost with a sandbox. Work an agent had not finished is lost if its sandbox ends first. Give tasks a size that fits, and resume with the same run command.
Last modified on November 13, 2026