Coordinators and fleets
A coordinator is a Claude Code session that starts and manages many worker agents, each on its own cloud machine. This page covers when to use one, how to run one, and how to merge many worker branches into one pull request.
A coordinator always runs Claude Code, whichever agent is your main session, and it cannot use a pi, omp, Codex or opencode profile. Its workers can run any agent through profile. A coordinator needs a Claude login even when your main session is Codex, opencode, pi or free-pi: coordinator image signs in to Claude (see below), and the coordinator's own session is Claude Code. Whether a coordinator can start codex-chatgpt workers has not been checked, and the code does not copy your ChatGPT login file (codex-auth.json) to a coordinator machine, so plan on codex-chatgpt not working from a coordinator.
Worker credentials on a coordinator. A coordinator can start a worker only if its machine holds that profile's key. On Instabox, coordinator start attaches every provider key that is stored as a proxy secret (listed in CLOUDY_CLOUD_PROXY_SECRETS), including PARTICLE_API_KEY, OPENROUTER_API_KEY and OPENAI_API_KEY, and the coordinator's ~/.config/cloudy-cloud/env holds their names. So before you start a fleet that uses codex workers, store OPENAI_API_KEY as an Instabox secret and add it to CLOUDY_CLOUD_PROXY_SECRETS on your computer, as in The codex profiles. A key that is only a plain line in your env file is not sent; coordinator start says which keys it skipped. The opencode, pi and omp profiles use PARTICLE_API_KEY or OPENROUTER_API_KEY, which setup stores as proxy secrets.
Picking a worker agent for a fleet
Keep the coordinator and any sub-coordinators on Claude Code. For the workers, set profile per task. For bulk, well-specified work (renames, adding tests, filling in similar files, doc updates), use an open-model profile: glm, deepseek or particle (Claude Code), pi-glm or pi-deepseek, or omp-glm. These are the ones verified live. Use openrouter, or codex-openrouter and opencode-openrouter, only with a model argument. Keep the default Claude profile for judgment-heavy tasks. Codex and opencode workers are not verified on a real machine (see the status table), so try one before you start many. The cloud-fleet skill is a Claude Code skill.
When to use a coordinator
For a few independent tasks, start plain cloud agents from your own session. You wait for them and review their branches yourself.
Use a cloud coordinator when all of these are true:
- The job is long or large.
- You want to leave, or close your laptop.
- The work needs only what is already on GitHub.
Do not hand a job to a cloud coordinator if it needs untracked local files, secrets or services that exist only on your laptop, or if you want to steer it step by step. Run the fleet from your own session instead.
There is also a lighter option. A cloud agent started with role: "coordinator" is a Claude subagent that can start its own cloud agents. Use this to build a tree: a coordinator, sub-coordinators for separate areas of the code, then workers. It lives only as long as your session. A cloud coordinator (below) runs on its own machine and keeps working with your laptop closed.
Cloud coordinator lifecycle
1. Make the coordinator image (once)
Remote Control needs a full Claude login. A token from claude setup-token cannot open Remote Control sessions. So you sign in once on an image machine and save it as an Instabox snapshot.
cloudy-cloud coordinator image
This creates a machine, installs cloudy-cloud on it, and opens the Claude sign-in. Finish the sign-in in your browser. The command then saves the snapshot as CLOUDY_CLOUD_COORDINATOR_SNAPSHOT in ~/.config/cloudy-cloud/env and deletes the image machine.
The server deletes the image machine after 2 hours, and the command prints the time. If the sign-in does not finish, run cloudy-cloud coordinator image again to resume on the same machine. Without a terminal (a script), the command prints the manual steps instead: cloudy-cloud shell NAME, then claude auth login, then exit, then cloudy-cloud coordinator image --save.
2. Start a coordinator
cloudy-cloud coordinator start NAME --repo https://github.com/OWNER/REPO --branch main --task-file brief.md
NAME: lowercase letters, digits and-, up to 40 characters.--repo: a github.com https URL. The coordinator clones it into~/repo.--branch B: the branch to clone. Optional.--task TEXTor--task-file PATH: the brief. Optional, up to 100 KB. Without one, the coordinator waits for you.--max-hours N: when the server deletes the machine. Default and maximum 24.--model NAME: the Claude Code model for the coordinator's session, such asopusorclaude-opus-5-5. Optional.--json: print the machine name, Remote Control name and attach command as JSON, withstarted: true.
The coordinator sees only the brief and the repo on GitHub. Commit and push everything it needs first. Give it exact acceptance commands, the files each work package owns, and a default for every question you can foresee, because nobody is there to answer.
3. Reach it
- Remote Control: open claude.ai/code or the Claude app and pick the session named
NAME. - Terminal:
cloudy-cloud coordinator attach NAMEprints an SSH command that attaches to its tmux session. Run the command it prints.
The first time, attach once and accept any trust or Remote Control prompts. To list your coordinators and their delete times, run cloudy-cloud coordinator ls.
4. Finish or stop
- The coordinator ends its own job with
~/cloudy-cloud/bin/cloudy-cloud coordinator finish. This deletes its machine only if the working tree is clean, the current branch and everyfleet/*branch are pushed, and no worker is still running. If a check fails it tells you what to fix.--forceskips the git and worker checks. - You can delete it at any time with
cloudy-cloud coordinator stop NAME. - If neither happens, the server deletes the machine at its deadline.
A coordinator is billed until it is stopped, finished or deleted. Its ~/.config/cloudy-cloud/env holds your real Instabox key, your Claude setup-token and your provider API keys, because it needs them to start workers. Anyone who can SSH into the machine can read them. Use keys you can revoke.
Getting one result from many workers
Each worker pushes a branch named cloudy-cloud/<id>. Starting 100 workers is easy. Reviewing 100 pull requests is not. The cloud-fleet skill teaches Claude these patterns:
| Situation | Pattern |
|---|---|
| Many unrelated small fixes, and reviewers want separate PRs | Flat fan-out: one PR per branch. Keep it to about 10 to 15. |
| One feature or one large job split across many workers | Trunk merging (the default) |
| Stage B needs the merged result of stage A | Waves |
| More than about 50 workers, or clearly separate areas | Trunk merging with sub-coordinators |
Trunk merging
The coordinator creates an integration branch fleet/<topic> and is the only one that merges into it.
- Create and push the trunk before starting workers. Workers copy only tracked files, so commit everything they need first.
git fetch origin git checkout -b fleet/<topic> origin/<base> git push -u origin fleet/<topic> - Start the workers. Give each a brief with its goal, the files it owns, the base branch
fleet/<topic>, the exact test command, and an instruction to push to itscloudy-cloud/<id>branch before it finishes. - As workers finish, fetch their branches and merge them one at a time, running the tests after each merge:
git fetch origin 'refs/heads/cloudy-cloud/*:refs/remotes/origin/cloudy-cloud/*' git checkout fleet/<topic> git merge --no-ff origin/cloudy-cloud/<id> -m "Merge <description> (<id>)" git push origin fleet/<topic> - On a conflict, resolve small ones yourself, or abort the merge and ask the worker to rebase. If the tests fail after a merge, do not push it. Send the worker the failing output.
- When every good branch is merged and the full tests pass, open one PR from
fleet/<topic>. - Delete merged worker branches:
git push origin --delete cloudy-cloud/<id>, or runcloudy-cloud branches prune --yesto delete every empty or mergedcloudy-cloud/<id>branch (without--yesit only lists them). Keep the branch of a failed worker until you decide what to keep.
Do not trust a worker that says it is done. Fetch its branch, read the diff and run the tests before merging. If a worker pushed nothing, retry it with a narrower brief that names what is missing.
Only push to cloudy-cloud/* and fleet/* branches. Never push to main. Protect your main branch with a GitHub ruleset, because workers run with permission checks off.
Sub-coordinators and waves
For large jobs, the top coordinator gives each area to a sub-coordinator with its own sub-trunk fleet/<topic>/<area>. Each sub-coordinator merges its workers, tests its area, and reports. The top coordinator merges the sub-trunks and opens the PR. Git cannot hold both fleet/x and fleet/x/y, so if that happens name them fleet/<topic>-<area>.
For waves, merge wave 1 into the trunk and push it before you start wave 2. Never start a dependent worker before its dependency is merged and pushed.
Keep coordinators on Claude Code, because merging and judging results needs a strong model. Open-model workers suit bulk, well-specified tasks. See Models and keys. Check their branches more carefully.
Limits and costs to watch
| Limit | Value |
|---|---|
| Cloud coordinator delete deadline | 24 hours by default and at most; set shorter with --max-hours N. It cannot be extended. A job that must run longer needs a new coordinator from a pushed branch. |
| Worker and nested coordinator delete deadline | CLOUDY_CLOUD_WORKER_HOURS, default 6, at most 24 |
| Idle agent | Stopped after 60 minutes with nothing to do |
| One task | Stopped after 29 minutes |
| Nesting depth | CLOUDY_CLOUD_MAX_DEPTH, default 3 |
| Agents per session | CLOUDY_CLOUD_MAX_AGENTS_PER_SESSION, default 200 |
| Start rate | CLOUDY_CLOUD_STARTS_PER_MIN, default 25 a minute. Extra agents show as queued. |
| Instabox calls at once | CLOUDY_CLOUD_MAX_INSTABOX_CALLS, default 24 |
Every machine in a tree counts against your Instabox machine limit and start rate. If many agents stay queued, the machine limit is full. Wait, or use fewer, larger tasks. Stop agents you no longer need with cloud_agent_stop, because idle agents cost money until they time out.
Only work pushed to GitHub survives. A worker's unpushed work is lost with its machine. When you stop a coordinator, its workers are deleted by its cleanup process or at their own deadline (6 hours by default), so stop or collect them first. Machines your laptop session started are deleted when that session ends, so push or collect their work before you exit.
To see what is running, use the dashboard.