Documentation
Cloudy is a research agent on cloud GPUs. Give it a goal and your code, and it plans experiments, runs them and reports back with the code and the numbers. Use it from the dashboard, the CLI, or your coding agent.
Install and sign in
Run these once on each machine you use Cloudy from.
| Command | What it does |
|---|---|
curl -fsSL https://cloudy.so/install.sh | sh | Installs or updates the CLI. Needs Python 3.12+ with uv, pipx or pip. On Windows, run it in WSL. |
cloudy login | Opens your browser to approve this terminal. Over SSH, add --no-browser and paste the one-time code from the approval page. |
cloudy whoami | Shows the account and team this terminal is signed in to. |
cloudy org use ORG_ID | Picks the team to work in when you belong to more than one. cloudy org lists them. |
cloudy billing | Shows your team’s credit balance. Running chats save their work and stop when it falls under $1. |
cloudy billing add 25 | Opens checkout to add $25 of credits, shared by the whole team. Team owners only. |
cloudy accounts connect claude_code | Optional: runs the model on your Claude plan instead of credits. Paste the token from claude setup-token when asked. |
cloudy accounts connect codex | Optional: runs the model on your ChatGPT plan through Codex. Add --from-file ~/.codex/auth.json. |
Run research
A chat is a conversation with Cloudy, with its own machine and saved files.
| Command | What it does |
|---|---|
cloudy new [FOLDER] | Creates a chat and attaches the folder if you give one. --goal TEXT saves a first message for start to send. |
cloudy upload JOB_ID [PATH] | Attaches a folder or one file. Secret files and anything .gitignore or .cloudyignore matches stay on your machine. Up to 8 MiB a file and 64 MiB in all. |
cloudy start JOB_ID -m TEXT | Sends a message, turning the chat’s machine on if it’s off. --yes accepts the charges and --wait returns Cloudy’s reply; otherwise it opens the chat. Also cloudy send. |
cloudy connect JOB_ID | Opens the chat in your terminal: its history, live updates and a prompt to reply. |
cloudy jobs | Lists your chats. --status running shows only those that are on. Also cloudy ls. |
cloudy settings JOB_ID | Shows or changes the mode, hardware limit and autoresearch time, such as --mode research --minutes 120. |
cloudy agent JOB_ID | Shows or changes the account, model and effort the chat runs on, with --provider, --model and --effort. |
cloudy guide JOB_ID TEXT | Steers autoresearch while it runs. --force interrupts the current step; --queue lists waiting messages, which --edit and --delete change. |
cloudy pause JOB_ID | Pauses autoresearch and goes back to chatting on the same machine. |
cloudy interrupt JOB_ID | Stops Cloudy’s current reply. The machine stays on. |
cloudy stop JOB_ID | Turns the machine off, saving files and the conversation. Your next message turns it back on. |
cloudy cancel JOB_ID | Stops at once, without saving a checkpoint. |
cloudy rename JOB_ID TITLE | Renames a chat. |
cloudy delete JOB_ID | Deletes a chat and stops its machine. --yes skips the question. |
Follow along
See what Cloudy is doing without opening the chat.
| Command | What it does |
|---|---|
cloudy wait JOB_ID | Waits up to 90 seconds for Cloudy to reply or the machine to turn off. Exit code 2 means it’s still working: run it again. |
cloudy status JOB_ID | Status, mode and agent, with the saved plan, state and report. |
cloudy progress JOB_ID | The research brief: plan, current step, experiments and history. |
cloudy activity JOB_ID | Milestones Cloudy has reached. |
cloudy logs JOB_ID | Streams Cloudy’s output live. --page prints one page and exits; --after and --before page through. |
cloudy usage JOB_ID | What the chat has cost so far, for models, compute, search and storage. |
cloudy resources JOB_ID | The compute and storage the chat used. |
cloudy audit JOB_ID | The chat’s lifecycle and tool log. |
Files and machines
Saved files stay with the chat. Its machine is on only while the chat runs.
| Command | What it does |
|---|---|
cloudy files ls [JOB_ID/PATH] | Lists saved files. Start the path with the chat’s ID, or pass --job. |
cloudy files cat JOB_ID/PATH | Prints a saved file under 100 MB. |
cloudy files download JOB_ID[/PATH] [DEST] | Downloads a file, a folder or all of a chat’s files. |
cloudy boxes [JOB_ID] | Lists running machines for a chat, or for the whole team. |
cloudy exec JOB_ID -- COMMAND | Runs one command on the chat’s machine with your secrets set. 30-second limit, 64 KiB of output. |
cloudy ssh JOB_ID | Opens a terminal on the machine through Cloudy, for up to 15 minutes. Ctrl+] leaves. Also cloudy shell. |
cloudy job JOB_ID ls [PATH] | Browses the running machine’s /workspace, or prints the start of a file. |
cloudy job JOB_ID metrics | CPU, memory, GPU and disk use on the machine. |
Team and settings
Teams share credits, secrets and connected plans.
| Command | What it does |
|---|---|
cloudy org | Lists your teams; * marks the current one. |
cloudy org show | The team’s members and pending invites. |
cloudy org create NAME | Creates a team. |
cloudy org invite EMAIL | Invites someone to the team. |
cloudy secrets | Lists environment variables set for commands on your machines. |
cloudy secrets set NAME | Saves one, such as HF_TOKEN. The value comes from a hidden prompt, stdin or --from-file, never the command line. --job JOB_ID keeps it to one chat. |
cloudy secrets delete NAME | Deletes one. |
cloudy accounts | Connected Claude and ChatGPT plans, and the models each offers. |
cloudy accounts disconnect PROVIDER | Disconnects claude_code or codex. |
cloudy billing job JOB_ID | One chat’s charges. |
cloudy config | Shows the API endpoint and CLI version. --api-url sets where login connects. |
cloudy logout | Revokes this terminal’s token and removes it. |
cloudy api METHOD PATH | Calls any Cloudy API endpoint as you, such as cloudy api GET /jobs. |
Options
Flags that several commands share. cloudy COMMAND --help lists the rest.
| Flag | What it does |
|---|---|
--json | Prints JSON. Every command takes it, and none asks a question when given its flags, so coding agents can drive Cloudy. |
--yes | Accepts the charges for start, or confirms delete. |
--mode MODE | On new, start and settings: chat talks and runs code, ask answers without changing anything, plan proposes before running, and research works on its own toward the goal. |
--hardware LIMIT | The most hardware Cloudy may use: cpu, any, a GPU count such as 4, or types such as h100:4 or h100,b200:8. Types are b300, b200, h200, h100 and a100-80gb. |
--minutes N | How long autoresearch may run, on start and settings. |
--timeout SECONDS | How long wait and start --wait wait. 90 by default. |
--box BOX_ID | Which machine exec, ssh and job use when several are running. |
--org ORG_ID | Runs org, secrets, accounts and billing for another team. |
Inside a chat
In cloudy connect, type to talk to Cloudy. A message turns the machine on if it’s off.
| Type | What it does |
|---|---|
/mode MODE [MINUTES] | Switches between chat, ask, plan and research on the same machine. |
/pause | Pauses autoresearch and keeps chatting. |
/interrupt | Stops Cloudy’s current reply. |
/stop | Turns the machine off, saving files and the conversation. |
/hardware LIMIT | Sets the most hardware Cloudy may use. |
/upload [FOLDER] | Attaches files. A running machine gets them before the next reply. |
/plan | Shows the saved research plan. |
/status | Shows the chat’s status. |
/queue | Lists queued and accepted guidance. |
/force ID | Interrupts work for a queued message. |
/retry | Resends your last guidance that didn’t save. |
/reconnect | Reloads the conversation and live updates. |
/cancel | Stops at once, without saving a checkpoint. |
/files ls|cat|download PATH | Lists, prints or downloads saved files. |
/boxes | Lists the chat’s machines. |
/ssh [BOX_ID] | Opens a terminal on a machine. |
/exit | Leaves the chat, which keeps running. Ctrl+C does the same. |
Keep API keys and .env files out of uploads; save them with cloudy secrets set. Questions? Talk to us