Cloudy Cloud Docs

FAQ

Short answers about what Cloudy Cloud does, what it needs, what it keeps and how to remove it.

Questions

What is a subagent?

When your coding agent (Claude Code, Codex, opencode, pi or free-pi) hands a piece of work to a helper agent, that helper is a subagent. Cloudy Cloud runs each helper on its own cloud machine instead of on your laptop.

How do I start Cloudy Cloud?

Run cloudy-cloud instead of claude, from inside a git repo with a GitHub remote. It starts a normal Claude Code session in which every subagent runs on its own cloud machine. To use another main session, run cloudy-cloud codex, cloudy-cloud opencode, cloudy-cloud pi or cloudy-cloud free-pi. cloudycloud is the same command; if you skipped the global install, use npx cloudycloud. Set it up first with npx -y cloudycloud setup.

What do I need?

An account with a cloud sandbox provider (Instabox is supported today), a GitHub repo you can push to, Node.js 20 or later, and a credential for each agent your workers use: a Claude subscription or API key for Claude Code workers (the default), or the provider key for a profile (Particle.ai, OpenRouter or OpenAI, or a ChatGPT login for Codex). See Models and keys.

What can a subagent see?

Files tracked by git in your repo, including uncommitted edits. It can't see untracked files or your personal agent settings (for example your Claude settings). It has MCP servers only if you copy them with cloudy-cloud mcp add. Add a new file with git add if the subagent needs it.

Can subagents use my MCP servers?

Yes, the ones you choose. Run cloudy-cloud mcp add NAME for each server. Remote https servers on public hosts and npx or uvx servers work. OAuth sign-in, localhost, local paths and secrets in URLs or arguments do not, and pi workers skip sse servers. Tokens stay in Instabox. See MCP servers for subagents.

What happens to the machines?

A subagent stops after 60 idle minutes or when your session ends. Its machine is deleted after 6 hours by default, 24 at most. Only work pushed to GitHub is kept.

What is kept after a subagent stops?

Only work pushed to GitHub on branch cloudy-cloud/<id>. The machine is deleted.

Is it safe?

Your GitHub token never reaches the cloud machine. Subagents run with permission checks off, so protect your main branch. The setup guide shows how. See Security for which credentials reach the cloud machine.

Does it change plain claude?

No. Only sessions you start with cloudy-cloud use the cloud.

What does it cost?

The tool itself has no price in this repo. You pay for your Instabox plan, your Claude subscription or API usage, and any open-model provider you use. The free Instabox plan is too small for more than a few subagents at once. Results end with a token total, and a cost when Claude reports one.

Which models and agents can subagents use?

Claude Code by default. A profile can run a worker on pi, oh-my-pi, Codex or opencode instead, with open models such as GLM and DeepSeek through Particle.ai, any model on OpenRouter, or OpenAI models through Codex. Status of each agent: what has been verified. See Models and keys.

Can I use my own computer?

Yes. Run cloudy-cloud setup --provider self-hosted to send subagents to a Mac or Linux machine you own, reached over SSH (for example through Tailscale). Each subagent runs in its own Docker container there. You must allow the GitHub token on that machine. Coordinators work through Docker images but have not been run live yet. See Run on your own machine.

Can work continue with my laptop closed?

Not from a laptop session: subagents stop when the session ends. For work that must continue with the laptop closed, use a cloud coordinator.

How do I uninstall it?

Delete leftover machines first. If you installed with npx cloudycloud setup, run npm uninstall -g cloudycloud, then delete ~/.config/cloudy-cloud, ~/.claude/skills/cloud-fleet and ~/.claude/skills/cloudy-cloud-setup. The full steps, including the install-from-clone case and deleting the subagent branches on GitHub, are in Troubleshooting.

Is there a hosted version?

Not yet. A hosted version is coming. Today Cloudy Cloud is open source (MIT) and you bring your own keys: your cloud account, your Claude credentials and your GitHub token.

Is it affiliated with Anthropic?

No.

More help

For error messages and fixes, see Troubleshooting, security and FAQ. For the terms used here, see the Glossary.