Cloudy Cloud Docs

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 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.

CommandHow the tools are addedIf the agent is missingChecked live
cloudy-cloud codexCodex -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 opencodeOne 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 piA 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-piWrites 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.

FlagMeaning
--provider instabox|self-hostedChoose where subagents run without being asked. self-hosted asks for your machine instead of an Instabox key. See Run on your own machine.
--check-onlyCheck 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.

FlagMeaning
--demoShow sample data instead of your machines. Nothing in it is real.
--port NListen 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-openOnly 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 flagMeaning
<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).
--sharePublish 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.
--unshareRemove 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.

FlagMeaning
(none)A view-only link that lasts 1 hour.
--controlThe viewer can click and type.
--ttl SECONDSLink lifetime, 60 to 86400. Not combined with --screenshot or --unshare.
--screenshot FILEWrite a PNG of the screen to a new file (an existing file or symlink is refused) and print the path.
--unshareRevoke 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.

FlagMeaning
--saveSave 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 flagDefaultMeaning
NAMErequiredLowercase letters, digits and -, up to 40 characters, starting with a letter or digit. A coordinator with the same name must not already exist.
--repo URLrequiredA https://github.com/OWNER/REPO URL.
--branch Bthe repository's default branchBranch to clone.
--task TEXTnoneA task for the coordinator to start on. Up to 100,000 bytes. Cannot be empty.
--task-file PATHnoneRead the task from a local file instead. Same limits.
--max-hours N24Hours until the server deletes the machine. At most 24, at least 60 seconds (1/60 hour). The deadline cannot be extended.
--model NAMEClaude Code's defaultModel 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 ._:[]-.
--jsonoffPrint 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.

FlagMeaning
--forceSkip 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.

ParameterTypeRequiredDefaultMeaning
promptstringyesnoneThe full task for the subagent.
descriptionstringyesnoneA short label for the task.
modelstringnothe Claude defaultA 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.
profilestringnoClaudeRuns 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.
rolestring, worker or coordinatornoworkerA 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.
machinestringnolinuxThe 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.
sizestringno4x8Machine size as VCPUSxGIB, for example 2x4, 4x8 or 8x16. Your Instabox plan decides which sizes are allowed; a size no plan lists is refused.
autofixbooleannofalseAfter 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.
basestringnothe local HEADA 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.
fallbackarray of stringsnothe profile's fallback in profiles.json, else noneProfile 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.
preflightbooleannotrueSet false to skip the one-token provider check that runs before the machine is created.
subagent_typestringnononeThe name of an agent to run, passed to Claude Code as --agent (Claude Code workers only). It may contain only letters, digits and . _ : -.
issuestringnononeA 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_portintegernononeA 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.

ParameterTypeRequiredDefaultMeaning
agent_idstringyesnoneThe id returned by cloud_agent.
messagestringyesnoneThe 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.

ParameterTypeRequiredDefaultMeaning
agent_idsarray of stringsyesnoneThe agent ids to wait for.
timeout_secondsnumberno600How 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.

ParameterTypeRequiredMeaning
agent_idstringyesThe 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.

ParameterTypeRequiredDefaultMeaning
agent_idsarray of stringsyesnoneThe 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). Live facts are from one run on 2026-11-15.

machineWhat it isPriceConsentDisplay
linuxThe standard machine (default).Your plannono
androidAndroid emulator with adb. Its desktop starts in about 1 second.Not checkednoyes
gpuNVIDIA GPU (one L4 by default). The first desktop start takes about 2 minutes.$0.765 per GPU-hour (NVIDIA L4)yesyes
omarchyOmarchy Linux with a Hyprland desktop. display and --screenshot are refused; shell works.Not checkednono
macosA Mac, for Xcode builds. Experimental, not yet run live.$0.45 to $1.25 per hour, 24-hour minimum leaseyesyes

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

VariableDefaultMeaning
INSTABOX_API_KEYnoneYour Instabox API key. Read from the environment or the config file.
CLAUDE_CODE_OAUTH_TOKENnoneThe long-lived token from claude setup-token. Cloud agents use it to sign in to Claude.
GH_TOKENnoneYour 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_KEYnoneAn 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_KEYnoneProvider 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_KEYnoneYour 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

VariableDefaultMeaning
CLOUDY_CLOUD_CONFIG~/.config/cloudy-cloud/envPath of the config file.
CLOUDY_CLOUD_ALLOW_MACHINE_KINDSnoneComma-separated machine kinds you allow although they cost much more: gpu, macos. Without it, cloud_agent refuses those kinds and starts nothing.
CLOUDY_CLOUD_PROVIDERinstaboxSandbox provider: instabox or self-hosted.
CLOUDY_CLOUD_SSH_HOSTnoneSelf-hosted: the SSH address of your machine, user@host.
CLOUDY_CLOUD_SSH_KEYnoneSelf-hosted: path to the SSH key. Optional.
CLOUDY_CLOUD_SSH_PORTthe SSH defaultSelf-hosted: the SSH port, when it is not the default.
CLOUDY_CLOUD_CONTAINER_RUNTIMEdockerSelf-hosted: docker or podman.
CLOUDY_CLOUD_CONTAINER_BINnoneSelf-hosted: absolute path of the docker or podman program on the machine. Setup finds and saves it.
CLOUDY_CLOUD_SELF_HOSTED_SLOTS2 if unset; setup suggests half the CPUs or one per 4 GB of memory, whichever is lowerSelf-hosted: how many subagents run at once.
CLOUDY_CLOUD_SELF_HOSTED_CPUS2 if unsetSelf-hosted: CPU limit per container. Setup saves a value.
CLOUDY_CLOUD_SELF_HOSTED_MEMORY4g if unsetSelf-hosted: memory limit per container. Setup saves a value.
CLOUDY_CLOUD_SELF_HOSTED_TOKEN_ON_BOXunsetSelf-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.jsonPath 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.jsonPath 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.jsonlPath of the event log that the dashboard reads. Set it in the environment before you start cloudy-cloud and the dashboard.
CLOUDY_CLOUD_WORKER_HOURS6Hours 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_MIN25The most machine starts per minute. Extra agents wait in the queue.
CLOUDY_CLOUD_MAX_INSTABOX_CALLS24The most Instabox command and file requests that run at once. Instabox's own limit is 32.
CLOUDY_CLOUD_TURN_MINUTES29The 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_RETRIES3How 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_MAXno capThe 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_ROUNDS3The most fix rounds autofix runs on a pull request (0 to 10).
CLOUDY_CLOUD_MAX_DEPTH3How 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_SESSION200How many agents one cloudy-cloud session may start. Passed down to child coordinators.
CLOUDY_CLOUD_PROXY_SECRETSemptyComma-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_PACKAGESemptySpace-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_AGENTSnoneThe 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_SECONDS60Setup only: how long to wait for the test request that checks your Claude token.
CLOUDY_CLOUD_NO_ANIMATIONunsetSetup 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_TIMEOUT1800000Claude Code's timeout for one MCP tool call, in milliseconds. The launcher sets it only if you have not.
NO_COLOR, CLICOLOR=0, TERM=dumbunsetAny 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

PathWhat it holds
~/.config/cloudy-cloud/envThe 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.jsonOptional. 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.jsonOptional. Adds or overrides model profiles, including each profile's harness. See Models and keys.
~/.config/cloudy-cloud/mcp.jsonOptional. 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.jsonlThe 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/ownerAn 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.