# Command and tool reference

> Every cloudy-cloud command, MCP tool, option and environment variable.

Source: https://cloudycloud.tech/docs/reference.html

This page lists every `cloudy-cloud` command and flag, the six tools your session uses to run cloud agents, and the environment variables and files that change how they behave.

These commands and tools apply to every main session: Claude Code (`cloudy-cloud`), Codex (`cloudy-cloud codex`), opencode (`cloudy-cloud opencode`), pi (`cloudy-cloud pi`) and free-pi (`cloudy-cloud free-pi`). The `cloud_agent` `profile` argument picks the worker agent: Claude Code, pi, oh-my-pi, Codex or opencode. An opencode main session names the tools `cloud_cloud_agent`, `cloud_cloud_agent_wait` and so on.

## Command line

These commands run on your computer. `cloudy-cloud` checks the first argument. If it is `codex`, `opencode`, `pi`, `free-pi`, `dashboard`, `open`, `shell`, `display`, `coordinator`, `setup` or `--setup`, it runs that command. `mcp ls`, `mcp add NAME`, `mcp add NAME --allow-literal` and `mcp rm NAME` run cloudy-cloud mcp; any other `mcp` arguments go to Claude Code. Any other arguments start a Claude Code session.

### cloudy-cloud (Claude Code as the main session)

```
cloudy-cloud [claude arguments]
```

The package installs the same command under two names, `cloudy-cloud` and `cloudycloud`; use either. Without a global install, `npx cloudycloud` runs the same command. Plain `claude` is not affected.

Starts a normal Claude Code session in the current folder. In that session the built-in `Agent` and `Workflow` tools are denied, and Claude starts subagents with the cloud tools described below. Run it from inside a git repository that has a `github.com` origin, because each cloud agent pushes its work to a branch there.

Every argument is passed to `claude` after the flags that `cloudy-cloud` adds itself (`--mcp-config`, `--settings` and `--append-system-prompt`). There are no `cloudy-cloud` flags of its own for a session.

Before it starts Claude, the command checks three things:

- It needs an Instabox API key (from the environment or the config file) and a Claude token or Anthropic API key in the config file. If one is missing, it tells you. In a terminal it offers to run `cloudy-cloud setup` now. Outside a terminal it exits with status 1.
- If the folder is not a git repository, it prints a warning that subagents cannot start.
- If the repository has no `github.com` origin, it prints a warning that subagents cannot push their work.

Example:

```
cloudy-cloud --model opus
```

It also sets `MCP_TOOL_TIMEOUT` to 1800000 (30 minutes) unless you already set it.

### cloudy-cloud codex, opencode, pi and free-pi

```
cloudy-cloud codex [codex arguments]
cloudy-cloud opencode [opencode arguments]
cloudy-cloud pi [pi arguments]
cloudy-cloud free-pi [free-pi-cli arguments]
```

Each command starts another coding agent as your main session, with the same cloud tools. Every argument after the subcommand goes to that agent. They are subcommands, not a flag, because Claude Code already has its own `--agent` option. None of them needs a Claude token to start, and setup does not ask for one unless you choose claude. They check only that the Instabox key (or the self-hosted settings) is saved, and run from inside a git repository with a `github.com` origin like `cloudy-cloud`. Workers run Claude Code unless `cloud_agent` gets a `profile`, so when no Claude token is saved, the command prints the profile to pass (for example `codex`) and tells the agent to pass it. To install an agent first, use the command in the third column.

| Command | How the tools are added | If the agent is missing | Checked live |
|---|---|---|---|
| `cloudy-cloud codex` | Codex `-c mcp_servers.cloud.*` overrides and `developer_instructions`. `~/.codex/config.toml` is not edited. The tools keep their names. | Prints `npm install -g @openai/codex`. Then sign in with `codex login`. | Yes. With codex-cli 0.166.0, `cloudy-cloud codex exec` listed the six cloud tools. |
| `cloudy-cloud opencode` | One `OPENCODE_CONFIG_CONTENT` value for this session. Your `opencode.json` is not edited. opencode's own `task` tool is denied. The tools are named `cloud_cloud_agent` and so on. | Prints `npm install -g opencode-ai`. Then sign in the way you normally do. | Yes, by the opencode build. |
| `cloudy-cloud pi` | A per-session pi extension that registers `node src/server.mjs` as an MCP server over stdio (the handlers do not run inside pi), and an appended system prompt. | Runs the pinned `@earendil-works/pi-coding-agent@1.5.0` with `npx`. To install it yourself: `npm install -g @earendil-works/pi-coding-agent`. | The MCP connection only. No model turn was run. |
| `cloudy-cloud free-pi` | Writes a `cloudy-cloud` entry (a stdio server, `node src/server.mjs`, with a 1,800 s timeout) into `~/.free-pi/agent/mcp.json` on every start. Your own `cloud` entry is not touched. A `cloudy-cloud` entry that cloudy-cloud did not write is not replaced: remove it with `free-pi-cli mcp remove cloudy-cloud`. | Runs the pinned `free-pi-cli@0.6.23` with `npx`. To install it yourself: `npm install -g free-pi-cli`. | `mcp list` only. |

The Codex, opencode and pi hosts cannot receive MCP task results, so the session starts agents and then calls `cloud_agent_wait`. free-pi is a main session only. It cannot be a worker.

### cloudy-cloud --help and --version

```
cloudy-cloud --help
cloudy-cloud --version
```

`--help` (also `-h` or `help`, when it is the only argument) prints Cloudy Cloud's own commands, then points to `claude --help` for Claude Code's options. `--version` prints the Cloudy Cloud version. With any other arguments, everything goes to Claude Code, for example `cloudy-cloud -p "<prompt>" --allowedTools "Bash(git fetch *)"`; see [Run without the interactive UI](https://cloudycloud.tech/docs/#no-interactive-ui).

### cloudy-cloud setup

```
cloudy-cloud setup [--check-only] [--provider instabox|self-hosted]
```

Runs the bundled `install.sh`, whatever folder you are in. `cloudy-cloud --setup` does the same, and `npx -y cloudycloud setup` runs it without installing anything first (`-y` skips npm's "Ok to proceed?" question). Setup checks your tools, offers to install the `cloudy-cloud` command (`npm install -g cloudycloud`, or a link when you run it from a git clone), copies the Cloudy Cloud skills into `~/.claude/skills`, asks which agents you run locally (claude, codex, opencode, pi, free-pi; Enter accepts the ones it finds on your PATH), and asks for your Instabox key and your GitHub token, plus a Claude token only if you chose claude or want Claude workers and an OpenAI key if you chose codex. Then it offers optional steps for model provider keys and cloud coordinators. If an older `cloudy-cloud` global command blocks the install, setup offers to replace it (`npm rm -g cloudy-cloud`, then `npm install -g cloudycloud`). Run it again to change a key. It needs a terminal because it asks for keys. See [Getting started](https://cloudycloud.tech/docs/).

| Flag | Meaning |
|---|---|
| `--provider instabox\|self-hosted` | Choose where subagents run without being asked. `self-hosted` asks for your machine instead of an Instabox key. See [Run on your own machine](https://cloudycloud.tech/docs/self-hosted.html). |
| `--check-only` | Check that `git`, Node.js, `npm`, `curl` and `claude` are installed, then exit. Does not need a terminal and changes nothing. |

Example:

```
cloudy-cloud setup --check-only
```

### cloudy-cloud doctor

```
cloudy-cloud doctor
```

Checks the machine that subagents run on when `CLOUDY_CLOUD_PROVIDER` is `self-hosted`: SSH, sleep settings on a Mac, the container runtime, disk, the worker image, slots, leftover containers and saved settings. Prints `ok`, `warn` or `fail` per check with a fix, and exits 1 if any check fails. With another provider it prints a one-line note. See [Run on your own machine](https://cloudycloud.tech/docs/self-hosted.html#doctor).

### cloudy-cloud dashboard

```
cloudy-cloud dashboard [--demo] [--port N] [--no-open]
```

Starts a read-only web page on `127.0.0.1` that shows your cloud agents, coordinators and the messages between your session and them. It prints a link that contains a random token for this run, and opens it in your browser. Press Ctrl+C to stop it. There is no `--help` option. See [Dashboard and app previews](https://cloudycloud.tech/docs/dashboard.html).

| Flag | Meaning |
|---|---|
| `--demo` | Show sample data instead of your machines. Nothing in it is real. |
| `--port N` | Listen on port N, from 0 to 65535. The default is 4477. If that port is in use, the dashboard uses a free port instead. Port 0 always picks a free port. |
| `--no-open` | Only print the link. Do not open a browser. |

Example:

```
cloudy-cloud dashboard --port 5000 --no-open
```

### cloudy-cloud branches

```
cloudy-cloud branches prune [--yes] [--dry-run]
```

Run it inside your repository. It lists the `cloudy-cloud/<8 hex characters>` branches on origin (and `cloudy-cloud/issue-<n>-<id>` branches, for workers started from an issue) and compares each with origin's default branch. A branch that adds no commits to the default branch (it is empty, or already merged) is marked `prune`. A branch with commits not in the default branch is marked `keep`. It never touches a branch with another name.

It is a dry run: nothing is deleted unless you pass `--yes`. `--dry-run` forces a dry run even with `--yes`.

```
cloudy-cloud branches prune
cloudy-cloud branches prune --yes
```

### cloudy-cloud open

```
cloudy-cloud open <agent-id-or-machine> <port> [--share]
cloudy-cloud open <agent-id-or-machine> <port> --unshare
```

Reaches an app, such as a dev server, that runs on a cloud agent's machine. The first argument is an agent id (the `<id>` in the branch `cloudy-cloud/<id>`, shown by `cloud_agent_list`), a machine name or a machine id (a coordinator's machine is named `coord-NAME`). It may use only letters, digits, dots, dashes and underscores. The machine must be running. The command needs your Instabox key.

With no flag, it opens a private tunnel from `http://127.0.0.1:<port>` on your computer to that port on the machine. It runs until you press Ctrl-C. Start the app in the background on the machine (for example `nohup npm run dev > /tmp/dev.log 2>&1 &`), because the foreground processes of a turn end with the turn. The tunnel and any shared link stop when the machine is deleted.

| Argument or flag | Meaning |
|---|---|
| `<port>` | A port from 1 to 65535 on the machine. Write `LOCAL:REMOTE` to use a different port on your computer (not allowed with `--share` or `--unshare`). |
| `--share` | Publish a private link, with a token in the URL, instead of a tunnel. Anyone who has the link can open the app until the machine is deleted or you unshare it. It never publishes publicly. |
| `--unshare` | Remove the link for that port. Cannot be combined with `--share`. |

Example:

```
cloudy-cloud open 3f9a1c2e 5173
```

### cloudy-cloud shell

```
cloudy-cloud shell <agent-id-or-machine> [-- command [args...]]
```

Opens an interactive login shell on a cloud machine. With `-- command` it runs that command, streams its output and exits with the command's exit code. Each argument after `--` reaches the machine unchanged. Do not put secrets in the command. The first argument works as in open, and the machine must be running. Without a command it needs a terminal.

```
cloudy-cloud shell 3f9a1c2e -- uname -a
```

### cloudy-cloud display

```
cloudy-cloud display <agent-id-or-machine> [--control] [--ttl SECONDS]
cloudy-cloud display <agent-id-or-machine> --screenshot FILE
cloudy-cloud display <agent-id-or-machine> --unshare
```

Prints a link to the desktop of an `android`, `gpu` or `macos` machine. Only the link goes to standard output. Anyone with the link can see the screen, so do not paste it into a PR, an issue or a report. An `omarchy` machine has no display. The first desktop start on a `gpu` machine takes about 2 minutes.

| Flag | Meaning |
|---|---|
| (none) | A view-only link that lasts 1 hour. |
| `--control` | The viewer can click and type. |
| `--ttl SECONDS` | Link lifetime, 60 to 86400. Not combined with `--screenshot` or `--unshare`. |
| `--screenshot FILE` | Write a PNG of the screen to a new file (an existing file or symlink is refused) and print the path. |
| `--unshare` | Revoke every display link for the machine, including viewers already connected. |

### cloudy-cloud coordinator

```
cloudy-cloud coordinator image [--save]
cloudy-cloud coordinator start NAME --repo URL [--branch B] [--task TEXT | --task-file PATH] [--max-hours N] [--model NAME] [--json]
cloudy-cloud coordinator attach NAME
cloudy-cloud coordinator ls
cloudy-cloud coordinator status NAME [--json]
cloudy-cloud coordinator stop NAME
cloudy-cloud coordinator finish [--force]
```

Manages cloud coordinators: long-lived Claude Code sessions that run on their own Instabox machines and start workers there. All subcommands except `finish` need your Instabox key. With any other first argument, or none, the command prints this usage line. See [Coordinators and fleets](https://cloudycloud.tech/docs/fleets.html) for when to use them.

#### coordinator image

Builds the machine image that coordinators start from. It is a one-time step. On a terminal, it creates an image machine (or reuses one you already started), installs cloudy-cloud on it, opens the Claude sign-in (`claude auth login`), and when you finish in the browser it saves a snapshot, stores its id as `CLOUDY_CLOUD_COORDINATOR_SNAPSHOT` in the config file, and deletes the image machine. Without a terminal it prints the manual steps instead (`cloudy-cloud shell NAME`, `claude auth login`, `exit`, then `--save`). `--save` checks that Claude is signed in on the machine, then saves and deletes it. The server deletes an unsaved image machine after 2 hours. Only one image machine can exist at a time.

| Flag | Meaning |
|---|---|
| `--save` | Save the signed-in image machine as a snapshot and delete the machine. |

#### coordinator start

Starts a coordinator named NAME on a new machine from the saved image. It sends this copy of cloudy-cloud (the checkout, or the npm package's files), writes the coordinator's key file (mode 600), clones your repository to `~/repo`, and starts Claude Code in a `tmux` session called `claude`, with Remote Control under the name NAME. The coordinator never pauses. The server deletes its machine after `--max-hours`. You can reach it from claude.ai/code or the Claude app (pick the session named NAME) or from a terminal with `coordinator attach`. The coordinator's Claude runs with permission checks off, like a worker, and the machine is set up so the bypass-mode confirmation and the folder-trust dialog never appear. If one still waits on a prompt, `coordinator ls` and `coordinator status` show it, and you attach and answer it. The first time, attach once and accept any Remote Control prompt.

| Argument or flag | Default | Meaning |
|---|---|---|
| `NAME` | required | Lowercase letters, digits and `-`, up to 40 characters, starting with a letter or digit. A coordinator with the same name must not already exist. |
| `--repo URL` | required | A `https://github.com/OWNER/REPO` URL. |
| `--branch B` | the repository's default branch | Branch to clone. |
| `--task TEXT` | none | A task for the coordinator to start on. Up to 100,000 bytes. Cannot be empty. |
| `--task-file PATH` | none | Read the task from a local file instead. Same limits. |
| `--max-hours N` | 24 | Hours until the server deletes the machine. At most 24, at least 60 seconds (1/60 hour). The deadline cannot be extended. |
| `--model NAME` | Claude Code's default | Model for the coordinator's Claude Code session, such as `opus` or `claude-opus-5-5`. Rejected before any machine is created if it has characters other than letters, digits and `._:[]-`. |
| `--json` | off | Print one line of JSON with `name`, `machine`, `remoteControlName`, `attach` and `started` (`true`) instead of the usual text. |

About 5 seconds after starting the session, the command reads its screen. If it shows a spend or usage limit or a login problem, the command deletes the machine and fails with that line. If it waits on a trust, MCP approval or Remote Control prompt, the machine stays and the output (and `waiting` in `--json`) says to run `coordinator attach NAME` and accept it. The session runs with `--strict-mcp-config` and has `cloudy-cloud` on `PATH`. If neither `--task` nor `--task-file` is given, the coordinator starts without a task. The command fails with a message if no coordinator image has been saved. A coordinator always runs Claude Code.

Example:

```
cloudy-cloud coordinator start docs-fleet --repo https://github.com/OWNER/REPO --task-file task.md --max-hours 8
```

#### coordinator attach

Prints the command that opens the coordinator's `tmux` session over SSH. It does not run the command. Copy it into your terminal. It has the form `npx --yes instabox@latest ssh <machine> -- tmux attach -t claude`.

```
cloudy-cloud coordinator attach docs-fleet
```

#### coordinator ls

Lists your coordinators in a table with the columns NAME, STATE, STARTED (CREATED when the output is not a terminal), MACHINE and DELETES, plus a WAITING (SCREEN in a terminal) column when a screen needs a look. It reads each running coordinator's screen once: `waiting on a prompt: <line>` means a prompt needs an answer, `screen not read` means the screen could not be read. It prints `No coordinators.` when there are none.

```
cloudy-cloud coordinator ls
```

When the output is piped, it prints tab-separated NAME, STATE, CREATED, MACHINE, DELETES and WAITING.

#### coordinator status

Read-only. Prints the coordinator's state, the prompt line it is waiting on (if any, with keys removed) and the attach command. It reads the screen once. `--json` prints `name`, `machine`, `state`, `screenRead`, `waiting` (only when set) and `attach`.

```
cloudy-cloud coordinator status NAME [--json]
```

Example:

```
cloudy-cloud coordinator status docs-fleet
```

#### coordinator stop

Deletes the coordinator's machine now. Its workers are deleted by the coordinator's cleanup process, or at their own deadline (6 hours by default). Anything the coordinator did not push to GitHub is lost.

```
cloudy-cloud coordinator stop docs-fleet
```

#### coordinator finish

Runs on the coordinator machine, started by the coordinator itself when its work is done. It checks that the working tree in `~/repo` is clean, that the current branch and every `fleet/*` branch are pushed to their upstream, and that none of the coordinator's workers are still running. If all checks pass, it deletes its own machine. If a check fails, it lists the problems and deletes nothing. It refuses to run on a machine that is not a coordinator.

| Flag | Meaning |
|---|---|
| `--force` | Skip the git and worker checks and delete the machine anyway. |

> Warning: `--force` can delete work that has not been pushed. Use it only when you accept losing that work.

### cloudy-cloud mcp

```
cloudy-cloud mcp add NAME [--allow-literal]
cloudy-cloud mcp ls
cloudy-cloud mcp rm NAME
```

Chooses which of your Claude Code MCP servers cloud subagents get. `add` copies one server from your Claude Code settings (local, project or user scope) to `~/.config/cloudy-cloud/mcp.json`, replaces a secret value with `${MCP_<NAME>_TOKEN}` and prints the `npx --yes instabox@latest secrets set ... --host ...` command that stores the value once in Instabox. `ls` lists the saved servers and the secrets they need. `rm` removes one. Only `https` servers on public hosts and `npx` or `uvx` servers are accepted; a refused server prints `Not added: REASON` and exits with status 1. `--allow-literal` asks you to confirm and then copies the real token to the machines instead of using an Instabox secret. All of this is described in [MCP servers for subagents](https://cloudycloud.tech/docs/mcp.html).

## Tools the session uses (MCP)

`cloudy-cloud` adds an MCP server named `cloud` to the session. Claude sees its tools as `mcp__cloud__cloud_agent` and so on. The session is configured to allow these six tools without asking and to deny the built-in `Agent` and `Workflow` tools. You normally ask for subagents in plain language and Claude calls the tools. This section is for when you want to know exactly what each tool takes.

In a terminal Claude Code session that supports MCP tasks, `cloud_agent` and `cloud_agent_message` run as background tasks. Their progress shows in `/tasks` and the result arrives on its own with the agent id, so Claude does not need `cloud_agent_wait`. In other clients these two tools return an agent id at once and Claude calls `cloud_agent_wait`. The server also answers the task methods `tasks/get` and `tasks/cancel`.

### cloud_agent

Starts a subagent in a remote sandbox on the committed and tracked files of the current repository. It does not include untracked files. The repository needs a `github.com` origin. The call returns at once while the sandbox starts and the task runs. The agent pushes its work to the origin branch `cloudy-cloud/<id>`. Nothing is copied into your local repository. The agent stays open for follow-ups until it is stopped or has been idle for 60 minutes.

Each turn is limited to 29 minutes by default. `CLOUDY_CLOUD_TURN_MINUTES` changes the limit (see Settings), and the prompt tells the agent when its turn ends. If a turn fails or hits the limit after the agent has started, the agent stays open with its session: call `cloud_agent_message` to continue it. A worker that commits nothing pushes no branch; the result says `No changes, no branch pushed.` and autofix does not start.

| Parameter | Type | Required | Default | Meaning |
|---|---|---|---|---|
| `prompt` | string | yes | none | The full task for the subagent. |
| `description` | string | yes | none | A short label for the task. |
| `model` | string | no | the Claude default | A Claude model name, such as `haiku`. For a non-Claude model, use `profile` instead. It is needed with a profile only for `openrouter`, `codex-openrouter` and `opencode-openrouter`, which have no built-in model. It may contain only letters, digits and `. _ : -`. When `profile` is also set, `/` is allowed too. |
| `profile` | string | no | Claude | Runs the worker on another agent or model. Built in: `glm`, `deepseek`, `particle` and `openrouter` (Claude Code on another model); `pi-glm`, `pi-deepseek` and `pi-particle` (pi); `omp-glm`, `omp-deepseek` and `omp-particle` (oh-my-pi); `codex`, `codex-chatgpt` and `codex-openrouter` (Codex); `opencode-glm`, `opencode-deepseek`, `opencode-particle` and `opencode-openrouter` (opencode). You can add names in `profiles.json`, where each entry's `harness` (`claude`, `pi`, `omp`, `codex` or `opencode`) says which agent runs the worker. An unknown name, or a profile whose key is missing, makes the call fail at once. See [Models and keys](https://cloudycloud.tech/docs/models.html). |
| `role` | string, `worker` or `coordinator` | no | `worker` | A worker does the task. A coordinator also gets cloudy-cloud installed and can start its own cloud agents, limited by `CLOUDY_CLOUD_MAX_DEPTH` (default 3). A coordinator always runs Claude Code, so it cannot use a pi, omp, Codex or opencode profile. |
| `machine` | string | no | `linux` | The kind of machine: `linux`, `android`, `omarchy`, `gpu`, `gpu:TYPE`, `gpu:TYPE:COUNT` (COUNT 1 to 8), `macos` or `macos:MODEL`. `gpu` and `macos` cost much more (GPU: from $0.765 per GPU-hour; Mac: $0.45 to $1.25 per hour with a 24-hour minimum) and are refused until `CLOUDY_CLOUD_ALLOW_MACHINE_KINDS` in `~/.config/cloudy-cloud/env` names them (for example `gpu,macos`). Only on Instabox. |
| `size` | string | no | `4x8` | Machine size as VCPUSxGIB, for example `2x4`, `4x8` or `8x16`. Your Instabox plan decides which sizes are allowed; a size no plan lists is refused. |
| `autofix` | boolean | no | `false` | After the worker pushes, the server opens a pull request for its branch and keeps the worker fixing failed checks, review comments and merge conflicts, for at most `CLOUDY_CLOUD_AUTOFIX_ROUNDS` rounds, before the task ends. The result says whether the pull request is clean. Not for coordinators. |
| `base` | string | no | the local `HEAD` | A branch name or a commit hash of 7 to 40 hex characters. The worker starts from it instead of your local `HEAD`; the server fetches it from origin if needed. Uncommitted edits are ignored when `base` is set. |
| `fallback` | array of strings | no | the profile's `fallback` in `profiles.json`, else none | Profile names to try, in order, when the chosen profile has no key or the provider refuses the one-token check before the machine starts. It overrides the profile's own `fallback`. The result says which profile ran. |
| `preflight` | boolean | no | `true` | Set `false` to skip the one-token provider check that runs before the machine is created. |
| `subagent_type` | string | no | none | The name of an agent to run, passed to Claude Code as `--agent` (Claude Code workers only). It may contain only letters, digits and `. _ : -`. |
| `issue` | string | no | none | A GitHub issue in this repo's origin: a number like `"12"`, or a URL like `https://github.com/<owner>/<repo>/issues/<n>`. The title and body are fetched on your computer with `gh` and quoted into the prompt as untrusted text. The branch is `cloudy-cloud/issue-<n>-<id>`, and an autofix pull request body says `Fixes #<n>`, so merging it closes the issue. Workers only; needs `gh` signed in. |
| `preview_port` | integer | no | none | A port from 1 to 65535 (a digit string also works) where the worker's app is already running on its machine. After a turn that pushed, a share link is published, the same as `cloudy-cloud open <id> <port> --share`, and the result shows `Preview: <url>`. The link is never posted to a pull request. Anyone with the link can open the app until the machine is deleted. Needs a provider that supports published links (Instabox); if publishing fails, the turn still succeeds and the result gives the manual command. |

When `~/.config/cloudy-cloud/mcp.json` holds at least one valid server, a Claude Code subagent (not a pi, omp, Codex or opencode worker) starts with `--mcp-config` for that file and `--strict-mcp-config`, so a repo's own `.mcp.json` is not loaded on the machine. pi, omp, Codex and opencode workers get the same servers in their own config files. The reply ends with an `MCP servers:` line. See [MCP servers for subagents](https://cloudycloud.tech/docs/mcp.html).

The call is refused if the session has already started `CLOUDY_CLOUD_MAX_AGENTS_PER_SESSION` agents (default 200), or if the folder is not a git repository with at least one commit and a `github.com` origin.

### cloud_agent_message

Sends a follow-up message to an open agent that is idle, and continues the same conversation. It returns at once. As an MCP task the reply arrives on its own. Otherwise Claude calls `cloud_agent_wait`. It is rejected if the agent is busy or gone.

| Parameter | Type | Required | Default | Meaning |
|---|---|---|---|---|
| `agent_id` | string | yes | none | The id returned by `cloud_agent`. |
| `message` | string | yes | none | The follow-up text. |

### cloud_agent_wait

Waits until every listed agent finishes its current turn, or until the timeout passes. For each agent it returns the status (`starting`, `running`, `idle`, `failed` or `stopped`) and its latest result. Each result is returned once. Later calls mark it as already reported. The tool is read-only.

| Parameter | Type | Required | Default | Meaning |
|---|---|---|---|---|
| `agent_ids` | array of strings | yes | none | The agent ids to wait for. |
| `timeout_seconds` | number | no | 600 | How long to wait. Values above 1500 are limited to 1500. |

### cloud_agent_result

Returns an agent's latest result again, as often as asked, even after `cloud_agent_wait` or a task notification delivered it. If the agent has no result yet it says `no result yet, status running`. If the agent is not open it returns an error with a next step. The tool is read-only.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `agent_id` | string | yes | The agent id. |

### cloud_agent_list

Lists every agent with its id, description, status, idle minutes and progress (tool uses, tokens, elapsed time and current step). The tool is read-only. With `all: true` it instead lists every machine on the provider labelled `purpose=cloudy-cloud` (other sessions and coordinators included), grouped by its `parent` label. Each worker machine carries the labels `role`, `profile` (`claude` for the default), `parent`, `agent` and a short redacted `description`.

### cloud_agent_stop

Stops agents and deletes their sandboxes. It is safe to repeat, and safe to call with ids that do not exist. Stop agents when they are finished, because they stay open until stopped or idle for 60 minutes.

| Parameter | Type | Required | Default | Meaning |
|---|---|---|---|---|
| `agent_ids` | array of strings | yes | none | The agent ids to stop. |

### Limits that apply to the tools

- An agent that is idle for 60 minutes is stopped. Every agent is stopped when the session ends.
- A single task is stopped after 29 minutes.
- Machines start at most `CLOUDY_CLOUD_STARTS_PER_MIN` times a minute. Agents waiting for a machine show the status `queued`.
- Instabox deletes every machine the tool creates after `CLOUDY_CLOUD_WORKER_HOURS` hours, even if `cloudy-cloud` has died.

## Kinds of machines

The `machine` argument of cloud_agent picks the machine. Prices are Instabox's ([pricing](https://instabox.sh/docs/account/pricing.md)). Live facts are from one run on 2026-11-15.

| machine | What it is | Price | Consent | Display |
|---|---|---|---|---|
| `linux` | The standard machine (default). | Your plan | no | no |
| `android` | Android emulator with `adb`. Its desktop starts in about 1 second. | Not checked | no | yes |
| `gpu` | NVIDIA GPU (one L4 by default). The first desktop start takes about 2 minutes. | $0.765 per GPU-hour (NVIDIA L4) | yes | yes |
| `omarchy` | Omarchy Linux with a Hyprland desktop. `display` and `--screenshot` are refused; `shell` works. | Not checked | no | no |
| `macos` | A Mac, for Xcode builds. Experimental, not yet run live. | $0.45 to $1.25 per hour, 24-hour minimum lease | yes | yes |

See cloudy-cloud shell and cloudy-cloud display to look at a machine.

## Environment variables and files

Environment variables win over values in the config file. An empty value counts as unset.

### Keys

| Variable | Default | Meaning |
|---|---|---|
| `INSTABOX_API_KEY` | none | Your Instabox API key. Read from the environment or the config file. |
| `CLAUDE_CODE_OAUTH_TOKEN` | none | The long-lived token from `claude setup-token`. Cloud agents use it to sign in to Claude. |
| `GH_TOKEN` | none | Your GitHub token. On a self-hosted machine it is read from the config file and placed in each worker container if you allowed that. See [Run on your own machine](https://cloudycloud.tech/docs/self-hosted.html#github-token). |
| `ANTHROPIC_API_KEY` | none | An Anthropic API key, used by cloud agents when there is no Claude token. It is billed separately. |
| `PARTICLE_API_KEY`, `OPENROUTER_API_KEY`, and any other name ending in `_API_KEY` | none | Provider keys for model profiles. A profile's `keyName` must name one of these. A worker that uses a profile receives that profile's key. |
| `OPENAI_API_KEY` | none | Your OpenAI API key, for the `codex` profile. Setup asks for it when you choose codex. See [The codex profiles](https://cloudycloud.tech/docs/models.html#codex-profiles). |

> Note: The launcher only checks the config file for the Claude token, not the environment, so save it there with `cloudy-cloud setup`. The Instabox key can come from either place.

### Settings

| Variable | Default | Meaning |
|---|---|---|
| `CLOUDY_CLOUD_CONFIG` | `~/.config/cloudy-cloud/env` | Path of the config file. |
| `CLOUDY_CLOUD_ALLOW_MACHINE_KINDS` | none | Comma-separated machine kinds you allow although they cost much more: `gpu`, `macos`. Without it, `cloud_agent` refuses those kinds and starts nothing. |
| `CLOUDY_CLOUD_PROVIDER` | `instabox` | Sandbox provider: `instabox` or `self-hosted`. |
| `CLOUDY_CLOUD_SSH_HOST` | none | Self-hosted: the SSH address of your machine, `user@host`. |
| `CLOUDY_CLOUD_SSH_KEY` | none | Self-hosted: path to the SSH key. Optional. |
| `CLOUDY_CLOUD_SSH_PORT` | the SSH default | Self-hosted: the SSH port, when it is not the default. |
| `CLOUDY_CLOUD_CONTAINER_RUNTIME` | `docker` | Self-hosted: `docker` or `podman`. |
| `CLOUDY_CLOUD_CONTAINER_BIN` | none | Self-hosted: absolute path of the `docker` or `podman` program on the machine. Setup finds and saves it. |
| `CLOUDY_CLOUD_SELF_HOSTED_SLOTS` | 2 if unset; setup suggests half the CPUs or one per 4 GB of memory, whichever is lower | Self-hosted: how many subagents run at once. |
| `CLOUDY_CLOUD_SELF_HOSTED_CPUS` | 2 if unset | Self-hosted: CPU limit per container. Setup saves a value. |
| `CLOUDY_CLOUD_SELF_HOSTED_MEMORY` | 4g if unset | Self-hosted: memory limit per container. Setup saves a value. |
| `CLOUDY_CLOUD_SELF_HOSTED_TOKEN_ON_BOX` | unset | Self-hosted: `yes` means you allowed the GitHub token inside worker containers on your machine. Without it, workers do not start. |
| `CLOUDY_CLOUD_PROFILES` | `~/.config/cloudy-cloud/profiles.json` | Path of the file that adds or overrides model profiles. Each entry can set `harness` to choose the agent (`claude`, `pi`, `omp`, `codex` or `opencode`), `fallback` (profile names to try in order) and `maxConcurrent` (a positive whole number). |
| `CLOUDY_CLOUD_MCP` | `~/.config/cloudy-cloud/mcp.json` | Path of the file that lists the MCP servers cloud subagents get. If the file is missing, no servers are sent. |
| `CLOUDY_CLOUD_EVENTS` | `~/.config/cloudy-cloud/events.jsonl` | Path of the event log that the dashboard reads. Set it in the environment before you start `cloudy-cloud` and the dashboard. |
| `CLOUDY_CLOUD_WORKER_HOURS` | 6 | Hours until the server deletes a worker or nested coordinator machine. At most 24. A value that is not a positive number uses 6. |
| `CLOUDY_CLOUD_STARTS_PER_MIN` | 25 | The most machine starts per minute. Extra agents wait in the queue. |
| `CLOUDY_CLOUD_MAX_INSTABOX_CALLS` | 24 | The most Instabox command and file requests that run at once. Instabox's own limit is 32. |
| `CLOUDY_CLOUD_TURN_MINUTES` | 29 | The most minutes one agent turn may run. A whole number from 5 to the provider's machine lifetime in minutes minus 30; any other value is refused with the allowed range. The server sets `CLOUDY_CLOUD_TURN_DEADLINE` (the turn's end time) inside the worker command. You do not set it. |
| `CLOUDY_CLOUD_PROVIDER_RETRIES` | 3 | How many times a pi, omp, Codex or opencode turn is retried after a transient provider error (model not found, 429, 5xx or a connection error). Errors such as 400, 401 and 403 are not retried. |
| `CLOUDY_CLOUD_PROFILE_MAX` | no cap | The default most agents one profile may run at once. A profile's `maxConcurrent` in `profiles.json` overrides it. Agents over the cap wait in the queue and say why in `cloud_agent_list`. The count covers this server's own agents only. |
| `CLOUDY_CLOUD_AUTOFIX_ROUNDS` | 3 | The most fix rounds `autofix` runs on a pull request (0 to 10). |
| `CLOUDY_CLOUD_MAX_DEPTH` | 3 | How many levels of coordinators can exist below your session. Starting a coordinator past this is refused. Workers do not add depth. Passed down to child coordinators. |
| `CLOUDY_CLOUD_MAX_AGENTS_PER_SESSION` | 200 | How many agents one cloudy-cloud session may start. Passed down to child coordinators. |
| `CLOUDY_CLOUD_PROXY_SECRETS` | empty | Comma-separated names of Instabox secrets that hold your Claude token and provider keys, for example `CLAUDE_CODE_OAUTH_TOKEN,PARTICLE_API_KEY,OPENROUTER_API_KEY`. A worker that needs a listed key gets the secret by name, so no key value reaches its environment. A key not listed is still copied to the machine, and the agent reply says so. Has no effect on providers without proxy secrets. |
| `CLOUDY_CLOUD_APT_PACKAGES` | empty | Space-separated Debian package names (for example `ffmpeg postgresql-client`) that each worker installs with `sudo -n apt-get install` after its repo is set up. A name with other characters is refused when the agent starts. |
| `CLOUDY_CLOUD_AGENTS` | none | The agents you chose in setup, comma-separated (`claude`, `codex`, `opencode`, `pi`, `free-pi`). `setup --check-only` reads it; when it is not set, claude is assumed. |
| `CLOUDY_CLOUD_CHECK_SECONDS` | 60 | Setup only: how long to wait for the test request that checks your Claude token. |
| `CLOUDY_CLOUD_NO_ANIMATION` | unset | Setup only: set to `1` to skip the animated banner. The banner is also skipped when `CI` is set or there is no terminal. |
| `MCP_TOOL_TIMEOUT` | 1800000 | Claude Code's timeout for one MCP tool call, in milliseconds. The launcher sets it only if you have not. |
| `NO_COLOR`, `CLICOLOR=0`, `TERM=dumb` | unset | Any of these turns off colour and the animated setup display. Output is plain text with the same messages. |

> Note: You can set `CLOUDY_CLOUD_STARTS_PER_MIN`, `CLOUDY_CLOUD_MAX_INSTABOX_CALLS`, `CLOUDY_CLOUD_WORKER_HOURS`, `CLOUDY_CLOUD_TURN_MINUTES`, `CLOUDY_CLOUD_MAX_DEPTH`, `CLOUDY_CLOUD_MAX_AGENTS_PER_SESSION`, `CLOUDY_CLOUD_PROXY_SECRETS` and `CLOUDY_CLOUD_APT_PACKAGES` in the config file as well as in the environment.

### Files

| Path | What it holds |
|---|---|
| `~/.config/cloudy-cloud/env` | The config file. One `NAME=value` per line, mode 600. `cloudy-cloud setup` writes it. Only the settings and keys listed above are read from it, plus `CLOUDY_CLOUD_COORDINATOR_SNAPSHOT`, which `coordinator image --save` writes. Change the location with `CLOUDY_CLOUD_CONFIG`. |
| `~/.config/cloudy-cloud/codex-auth.json` | Optional. A copy of `~/.codex/auth.json` (mode 600) for the `codex-chatgpt` profile. Create it with `install -m 600 ~/.codex/auth.json ~/.config/cloudy-cloud/codex-auth.json`. Set `CLOUDY_CLOUD_CODEX_AUTH` to use another path. |
| `~/.config/cloudy-cloud/profiles.json` | Optional. Adds or overrides model profiles, including each profile's `harness`. See [Models and keys](https://cloudycloud.tech/docs/models.html). |
| `~/.config/cloudy-cloud/mcp.json` | Optional. The MCP servers that cloud subagents get, in Claude Code's `mcpServers` format, mode 600. `cloudy-cloud mcp add` writes it. Secret values are stored as `${MCP_<NAME>_TOKEN}` references unless you used `--allow-literal`. See [MCP servers for subagents](https://cloudycloud.tech/docs/mcp.html). |
| `~/.config/cloudy-cloud/events.jsonl` | The event log. The MCP server appends one JSON line per agent event (agent, message, machine, status, progress, reply). The file has mode 600 inside a folder with mode 700. It holds your prompts and replies, so it stays on your computer. Key-shaped text is redacted before writing, and each text is cut at 20,000 characters. It is never rotated: delete it to clear the history. The dashboard reads the newest 16 MB. |
| `~/.config/cloudy-cloud/owner` | An id the MCP server writes next to the config file, so `coordinator finish` can tell which running machines are its workers. You do not need to edit it. |

If you used the tool under its old name, claude-cloud, the first run copies `~/.config/claude-cloud` to `~/.config/cloudy-cloud` and renames the `CLAUDE_CLOUD_` keys in the config file. The old folder is left in place.
