Models and keys
Cloudy Cloud uses your own keys. By default each subagent runs Claude Code. You can run a subagent on another agent or model by naming a profile.
This page covers every worker agent: Claude Code (the default), pi, oh-my-pi (omp), Codex and opencode. Each section says which credential that agent needs. The main session, which you start with cloudy-cloud, cloudy-cloud codex, cloudy-cloud opencode, cloudy-cloud pi or cloudy-cloud free-pi, is covered in Getting started.
Bring your own keys
Each user supplies their own credentials, because Anthropic's terms require each end user to use their own.
You pay your providers directly. Cloudy Cloud does not resell model access, and this page gives no prices.
Claude credentials
Applies to: workers that run Claude Code (no profile, or glm, deepseek, particle, openrouter) and the Claude Code main session. Workers on pi, omp, Codex or opencode profiles do not use it. Setup asks for it only if you choose claude or want Claude workers. See Getting started.
Claude Code subagents need one Claude credential. The setup step (cloudy-cloud setup) asks for it when you choose claude (or want Claude workers); it does not ask if you run only Codex, opencode or pi. Two kinds work:
- A token from
claude setup-token(starts withsk-ant-oat01-). This uses your Claude subscription. At the Claude step, press Enter and setup runsclaude setup-tokenfor you, or paste a token you made yourself. Setup checks the token with one small Claude request. It is saved asCLAUDE_CODE_OAUTH_TOKEN. - An Anthropic API key (
ANTHROPIC_API_KEY). Setup does not ask for it. Add the lineANTHROPIC_API_KEY=...to the env file yourself (see below). Usage is billed per use.
If both are saved, subagents use the token and not the API key.
Setup saves all keys to ~/.config/cloudy-cloud/env. Setup creates the folder with mode 700 and writes the file so that only your user account can read it. The file is plain text with one NAME=value line per key. To use another location, set CLOUDY_CLOUD_CONFIG.
Default model and choosing another
With no profile, a subagent runs Claude Code. To pick a Claude model, pass the optional model argument of cloud_agent, for example haiku.
To run a subagent on another agent or a non-Claude model, pass the profile argument of cloud_agent. Do not use model for non-Claude models, except as noted for openrouter, codex-openrouter and opencode-openrouter. You can ask in plain language, for example "use a glm subagent for this". Follow-up messages to that subagent reuse its profile.
What has been verified
This table is the one status list. Other pages link here. "Verified live" means it ran on a real machine and the result was checked. "Partly verified" means only the named check was done. "Not verified on a real machine" means tests with a fake sandbox only. The same terms apply to your own machine, where no Codex, opencode, pi or omp worker has run.
| Agent | As main session | As worker |
|---|---|---|
| Claude Code | Verified live | Verified live |
| pi | Partly verified: MCP connection only, no model turn | Verified live |
| oh-my-pi | Not a main session | Verified live (follow-ups by unit tests only) |
| Codex | Partly verified: it listed the six cloud tools (codex-cli 0.166.0) | Not verified on a real machine |
| opencode | Verified live | Not verified on a real machine |
| free-pi | Partly verified: mcp list only | Cannot be a worker |
Worker agents at a glance
| Agent on the machine | Profiles | Credential it needs | Started as | Status |
|---|---|---|---|---|
| Claude Code (default) | none, or glm, deepseek, particle, openrouter | Claude token or API key; for the four profiles, the provider key instead | claude -p ... --output-format stream-json | Verified live, including GLM and DeepSeek through Particle.ai |
| pi | pi-glm, pi-deepseek, pi-particle | PARTICLE_API_KEY | pi --mode json --provider worker --model ... --session ID | Verified live (pi-glm) |
| oh-my-pi | omp-glm, omp-deepseek, omp-particle | PARTICLE_API_KEY | omp -p --mode json --model worker/MODEL [--session ID] ... | Verified live (omp-glm) |
| Codex | codex, codex-chatgpt, codex-openrouter | OPENAI_API_KEY, your ChatGPT login file, or OPENROUTER_API_KEY | CODEX_HOME=~/codex-home codex exec [resume ID] --json --dangerously-bypass-approvals-and-sandbox -c developer_instructions=... - | Not verified on a real machine |
| opencode | opencode-glm, opencode-deepseek, opencode-particle, opencode-openrouter | PARTICLE_API_KEY or OPENROUTER_API_KEY | opencode run --format json --model worker/MODEL [--session ses_...] | Not verified on a real machine |
free-pi can be a main session but not a worker: free-pi-cli has no headless mode, and its terms forbid scripted use.
Built-in profiles
| Profile | Provider | Model id | Key needed | Notes |
|---|---|---|---|---|
glm | Particle.ai | z-ai/glm-5.3-flash | PARTICLE_API_KEY | Runs Claude Code on the model. |
deepseek | Particle.ai | deepseek-ai/deepseek-v41-flash-1017 | PARTICLE_API_KEY | Runs Claude Code on the model. |
particle | Particle.ai | particle-ai/particle-1 | PARTICLE_API_KEY | Runs Claude Code on the model. |
pi-glm | Particle.ai | z-ai/glm-5.3-flash | PARTICLE_API_KEY | Runs the pi coding agent, not Claude Code. |
pi-deepseek | Particle.ai | deepseek-ai/deepseek-v41-flash-1017 | PARTICLE_API_KEY | Runs the pi coding agent. |
pi-particle | Particle.ai | particle-ai/particle-1 | PARTICLE_API_KEY | Runs the pi coding agent. |
omp-glm | Particle.ai | z-ai/glm-5.3-flash | PARTICLE_API_KEY | Runs the oh-my-pi (omp) coding agent, not Claude Code. |
omp-deepseek | Particle.ai | deepseek-ai/deepseek-v41-flash-1017 | PARTICLE_API_KEY | Runs the oh-my-pi coding agent. |
omp-particle | Particle.ai | particle-ai/particle-1 | PARTICLE_API_KEY | Runs the oh-my-pi coding agent. |
codex | OpenAI | Codex's own default | OPENAI_API_KEY | Runs the Codex CLI. See The codex profiles. |
codex-chatgpt | OpenAI, through your ChatGPT plan | Codex's own default | The login file ~/.config/cloudy-cloud/codex-auth.json | Runs the Codex CLI. |
codex-openrouter | OpenRouter | None built in. You pass one. | OPENROUTER_API_KEY | Runs the Codex CLI. |
opencode-glm | Particle.ai | z-ai/glm-5.3-flash | PARTICLE_API_KEY | Runs opencode. See The opencode profiles. |
opencode-deepseek | Particle.ai | deepseek-ai/deepseek-v41-flash-1017 | PARTICLE_API_KEY | Runs opencode. |
opencode-particle | Particle.ai | particle-ai/particle-1 | PARTICLE_API_KEY | Runs opencode. |
opencode-openrouter | OpenRouter | None built in. You pass one. | OPENROUTER_API_KEY | Runs opencode. |
openrouter | OpenRouter | None built in. You pass one. | OPENROUTER_API_KEY | Runs Claude Code. See OpenRouter. |
A profile worker receives only its own provider key. It never receives your Claude credential. The one exception to "a key" is codex-chatgpt, which receives your ChatGPT login file. If the key for a profile is missing, cloud_agent fails at once and names the key. Coordinators always run Claude Code, so a coordinator cannot use a pi, omp, Codex or opencode profile.
The pi profiles
The pi-* profiles run the pi coding agent in the worker instead of Claude Code. They use none of your Claude allowance. Results from pi workers have no cost line. They get the MCP servers from cloudy-cloud mcp add, except sse servers, because pi has no SSE transport. See MCP servers for subagents.
The omp profiles
The omp-* profiles run oh-my-pi (the omp command) in the worker instead of Claude Code. oh-my-pi is a fork of pi rewritten as a coding-first agent. It adds LSP support, persistent Python and Bun kernels, subagents and many providers. The profiles use the same three Particle.ai models as the pi profiles, and none of your Claude allowance.
Each omp worker installs the pinned oh-my-pi release v18.18.7 with the official installer, which checks the binary's SHA-256. The binary is about 243 MB and is downloaded on every omp worker, so an omp worker starts slower than a pi or Claude worker. In one live check the whole omp worker setup (clone, first push, omp install and config) took about 20 seconds from machine creation to running, against 11 seconds for a pi worker started at the same time (one run each). Results from omp workers have no cost line. A follow-up resumes the same omp session. omp workers get the servers from cloudy-cloud mcp add, including sse servers.
The codex profiles
The codex, codex-chatgpt and codex-openrouter profiles run the Codex CLI in the worker. Cloudy Cloud installs the pinned @openai/codex@0.166.0 under ~/.local and runs codex exec --json with CODEX_HOME=~/codex-home. Follow-up messages use codex exec resume ID. Servers from cloudy-cloud mcp add go into ~/codex-home/config.toml, except sse servers and entries that Codex cannot read a secret from. Skipped servers are named in the reply.
Codex only speaks the Responses API, and Particle.ai does not offer it, so there is no codex-glm. Set up the credential for the profile you use:
codex(OpenAI API key). Create a key at platform.openai.com/api-keys.cloudy-cloud setupasks for it when you choose codex, and stores it as an Instabox secret. To do it by hand on Instabox, store it as a proxy secret limited to OpenAI, then add the name toCLOUDY_CLOUD_PROXY_SECRETSin~/.config/cloudy-cloud/env:
On a self-hosted machine, add the lineprintf %s "$OPENAI_API_KEY" | npx --yes instabox@latest secrets set OPENAI_API_KEY --host api.openai.comOPENAI_API_KEY=...to the env file.codex-chatgpt(ChatGPT plan). On your computer runcodex loginand choose "Sign in with ChatGPT". Then copy the login file where Cloudy Cloud reads it:
Setinstall -m 600 ~/.codex/auth.json ~/.config/cloudy-cloud/codex-auth.jsonCLOUDY_CLOUD_CODEX_AUTHto use another path. The file must have mode 600. This is the one real credential that Cloudy Cloud sends to a machine as a file, even on Instabox, because a ChatGPT login cannot be a proxy secret. Its tokens are scrubbed from replies, and the machine may refresh them. Do not passmodelunless your plan supports it: with no model, Codex uses the default model of your plan.codex-openrouter. UsesOPENROUTER_API_KEY, set up as in OpenRouter. Pass the OpenRouter model id inmodel.
Not verified on a real machine (see the status table). Resume and the ChatGPT-login error message were also recorded locally with codex exec.
The opencode profiles
The opencode-* profiles run opencode in the worker. Cloudy Cloud installs the pinned opencode-ai@1.18.31 with npm under ~/.local and runs opencode run --format json --model worker/MODEL. A follow-up passes --session ses_.... The configuration is ~/opencode-agent/opencode.json (mode 600). It holds key names such as {env:PARTICLE_API_KEY}, never key values, and the servers from cloudy-cloud mcp add. Keys: opencode-glm, opencode-deepseek and opencode-particle use PARTICLE_API_KEY, and opencode-openrouter uses OPENROUTER_API_KEY and needs model. Both are set up with cloudy-cloud setup (see OpenRouter for the second).
No profile uses opencode's own login, because that would copy a login to the machine.
Not verified on a real machine (see the status table).
OpenRouter
To use OpenRouter:
- Create a key at openrouter.ai/keys.
- Run
cloudy-cloud setupand paste it at the OpenRouter step. It is saved asOPENROUTER_API_KEY. - Start a subagent with
profile: "openrouter"(Claude Code),"codex-openrouter"(Codex) or"opencode-openrouter"(opencode), and pass the OpenRouter model id inmodel. These are the cases wheremodelgoes with a non-Claude model, because the profiles have no built-in model.
If you pass no model, the call fails with "needs a model". To avoid passing it every time, set a model for openrouter in profiles.json (below).
Signing in with OpenRouter is not available: you paste an API key. A ChatGPT sign-in works only through the codex-chatgpt profile (see above).
Your own profiles
Create ~/.config/cloudy-cloud/profiles.json (or point CLOUDY_CLOUD_PROFILES at another file) to override a built-in profile or add one:
{
"openrouter": {
"format": "anthropic",
"baseUrl": "https://openrouter.ai/api",
"model": "MODEL-ID",
"keyName": "OPENROUTER_API_KEY"
}
}
format is anthropic or openai. keyName must be a key in your env file whose name ends in _API_KEY. An optional "harness" is "claude" (the default), "pi", "omp", "codex" or "opencode". It picks the agent that runs on the machine. The codex and opencode harnesses need "format": "openai", and codex needs a provider that offers the Responses API. A codex profile can use "auth": "chatgpt" instead of keyName. Replace MODEL-ID with a model id from your provider.
Two more optional fields on any profile:
"fallback": a list of profile names. When the profile has no key, or the provider refuses a one-token check before the machine starts, the server tries these profiles in order. The result says which profile ran. Afallbackargument oncloud_agentoverrides it, and"preflight": falseon the call skips the check."maxConcurrent": a positive whole number, the most agents this profile runs at once. Extra agents wait in the queue.CLOUDY_CLOUD_PROFILE_MAXsets the same cap for every profile that has nomaxConcurrent.
{ "my-openrouter": { "format": "anthropic", "baseUrl": "https://openrouter.ai/api", "model": "MODEL-ID", "keyName": "OPENROUTER_API_KEY", "fallback": ["glm"], "maxConcurrent": 6 } }
Adding or changing keys later
- Run
cloudy-cloud setupagain. It shows each saved key masked and asks before replacing it. The Particle.ai and OpenRouter steps are optional: press Enter to skip. Setup asks forOPENAI_API_KEYwhen you choose codex, and does not set up the Codex login file: see The codex profiles. - Or edit
~/.config/cloudy-cloud/envdirectly. Keep the file private. To remove all saved keys, delete it. - Restart
cloudy-cloudafterwards. It reads keys once at start, so a running session keeps the old ones.
A provider key is stored on each worker machine that uses that profile. A prompt-injected worker could read it. Use keys you can revoke.