Command and tool reference
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 setupnow. 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.comorigin, 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.
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.
| 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. |
--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.
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.
| 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 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. |
--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.
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. |
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.
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_MINtimes a minute. Agents waiting for a machine show the statusqueued. - Instabox deletes every machine the tool creates after
CLOUDY_CLOUD_WORKER_HOURShours, even ifcloudy-cloudhas died.
Kinds of machines
The machine argument of cloud_agent picks the machine. Prices are Instabox's (pricing). 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. |
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. |
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. |
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. |
~/.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. |
~/.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.