Reference
CLI reference
Every cloudex command and flag in v0.2.3, from the CLI's own help, with the environment variables it reads.
This page is generated from cloudex --help for v0.2.3. Run cloudex <command> --help for the help of the CLI you have installed.
Commands that take an optional [sandbox] act on the current sandbox when you leave it out. A sandbox is named by its id, such as cx-7f3a2k, or its name.
A request that only reads or changes the deployment’s records, such as cloudex list, info, set, saves, tokens or node rm, gives up after 60 seconds without an answer and says so, since a deploy can cut a connection without closing it (node rm --force waits 3 minutes, for an online node’s machines). Starting, stopping, saving, commands and connections have no such limit.
For a sandbox on a node, cloudex ssh, the hosts that cloudex ssh-config sets up, prompt and attach go straight to the node when this computer can reach it, on its LAN or tailnet, and through the deployment otherwise; see Direct connections. cloudex node info shows a node’s direct port, and cloudex doctor checks whether it answers from here.
| Sandboxes | What it does |
|---|---|
cloudex new |
Create and start a sandbox |
cloudex fork |
Make new sandboxes that start from a copy of one’s disk |
cloudex save |
Save a sandbox’s disk under a name, to start new sandboxes from |
cloudex saves |
List named saves, or delete one |
cloudex list |
List sandboxes |
cloudex info |
Show a sandbox’s details |
cloudex use |
Make a sandbox the current one |
cloudex set |
Rename a sandbox, or change how long it may sit idle |
cloudex env |
Set a sandbox’s environment variables and files |
cloudex stop |
Save a sandbox’s disk and stop it |
cloudex resume |
Start a stopped sandbox from its saved disk |
cloudex delete |
Delete a sandbox for good |
| Connect | What it does |
|---|---|
cloudex ssh |
Open a shell in a sandbox over SSH |
cloudex ssh-config |
Print an ~/.ssh/config block so ssh, scp, rsync and editors reach <sandbox>.cloudex |
cloudex exec |
Run a command in a sandbox, or start one in the background |
cloudex commands |
List background commands, follow their output, or stop them |
cloudex cp |
Copy files and directories into or out of a sandbox |
cloudex run |
Run a command in a new sandbox with this directory’s files, then delete it |
cloudex host |
Get an HTTPS link to a port in a sandbox, on your preview domain |
cloudex desktop |
Open a sandbox’s desktop, with Chrome and a terminal, in your browser |
cloudex prompt |
Give a coding agent a task in a sandbox and watch it work |
cloudex attach |
Reattach to an agent session (the newest by default) |
cloudex agents |
Run coding agents in a sandbox without a terminal, and follow them |
cloudex dashboard |
Open the deployment’s web dashboard in your browser, signed in |
| Setup | What it does |
|---|---|
cloudex deploy |
Install or update Cloudex in your Cloudflare account |
cloudex login |
Use an existing Cloudex deployment from this computer |
cloudex node |
Run sandboxes on your own Docker hosts: add, list and remove nodes |
cloudex tokens |
Give CI, agents and other computers their own API keys, and approve sign-ins |
cloudex keys |
Give sandboxes AI provider keys without putting the keys in them |
cloudex status |
Check the connection to your Cloudex deployment |
cloudex doctor |
Check this computer and your deployment for problems |
cloudex update |
Update the CLI to the latest release, then your deployment |
cloudex version |
Print the CLI version |
cloudex feedback |
Report a bug, an idea or a question to the Cloudex maintainers |
| Other | What it does |
|---|---|
cloudex completion |
Generate the autocompletion script for the specified shell |
Global flags
These work with every command.
| Flag | Description |
|---|---|
--api-url string |
Cloudex API URL (default: the one saved by cloudex deploy or login, or $CLOUDEX_API_URL) |
--json |
print JSON (the default when stdout is not a terminal) |
-v, --version |
version for cloudex |
Environment variables
| Variable | Effect |
|---|---|
CLOUDEX_API_URL |
The deployment’s API URL, instead of the saved one. --api-url takes precedence. |
CLOUDEX_API_KEY |
The deployment’s admin key, instead of the saved one. cloudex login reads it too. |
CLOUDEX_CONFIG_DIR |
Where the CLI keeps its settings and SSH key, instead of ~/.config/cloudex |
CLOUDEX_NO_UPDATE_CHECK |
Set to any value to stop the daily check for a new release |
CLOUDEX_DIRECT |
How ssh reaches a sandbox on a node: auto (the default) tries the node itself and the deployment, and takes the first that connects; off only goes through the deployment; only only goes to the node, or fails. See Direct connections. |
CLOUDEX_DEBUG |
Set to 1 to have ssh’s proxy command print which paths it tried, how long each took, and which it chose |
CLOUDFLARE_API_TOKEN |
The Cloudflare API token for cloudex deploy, and for the containers check in cloudex doctor |
CLOUDFLARE_ACCOUNT_ID |
The Cloudflare account for cloudex deploy, when the token reaches several |
cloudex new
Create a sandbox and make it the current one. It stops (and saves its disk) after --idle without SSH, exec, preview or agent activity.
--env, --env-file and --file give it environment variables and files at every start (see cloudex env), and --repo clones a repo into its home directory.
With --from, the new sandboxes start from a copy of another’s disk, and its settings (see cloudex fork), or from a named save (see cloudex save). When a sandbox and a save share a name, the sandbox wins; --from save:<name> picks the save.
With --on, it runs on one of your nodes (see cloudex node) instead of Cloudflare, with --cpus and --memory as its machine’s limits there. A sandbox on a node keeps its disk there when it stops, and has no 6-hour limit. --on goes with --from a named save, which moves a sandbox between Cloudflare and a node. A fork of a sandbox on a node stays on that node, where --cpus and --memory set its limits.
cloudex new [flags]
| Flag | Description |
|---|---|
--count int |
with --from, how many sandboxes to start, up to 10 (default 1) |
--cpus float |
with --on, or --from a sandbox on a node: its CPUs, such as 0.5 or 4 (default the size’s: 1, or the original’s) |
--env stringArray |
NAME=VALUE: an environment variable (repeatable) |
--env-file stringArray |
read NAME=VALUE lines from this file (repeatable) |
--file stringArray |
DEST=SRC: put the local file SRC at DEST in the sandbox’s home (repeatable) |
--from string |
start from a copy of this sandbox’s disk (a fork), or from this named save |
--idle duration |
stop after this long without activity, such as 30m or 2h; 0 never stops it on a node, and waits for the 6-hour platform limit on Cloudflare (default 30m0s) |
--memory string |
with --on, or --from a sandbox on a node: its memory, such as 4G or 512M (default the size’s: 6G, at most half the node’s, or the original’s) |
--name string |
a name to use instead of the id |
--no-use |
don’t make it the current sandbox |
--on string |
run it on this node (your own Docker host; see cloudex node) instead of Cloudflare |
--repo string |
an https:// repo to clone into the home directory, with #branch to pick one |
--size string |
standard-1, standard-2 (default), standard-3 or standard-4 |
Examples:
cloudex new --name my-box
cloudex new --on box --cpus 2 --memory 4G --name n1
cloudex new --repo https://github.com/you/app --env GH_TOKEN=$(gh auth token) --env-file .env
cloudex new --from my-box --count 3 --name agent
cloudex new --from base --name task-1
cloudex new --from base --on box --name n1
cloudex fork
Make one or more sandboxes that start from a copy of a sandbox’s whole disk: files, installed packages and settings. A running sandbox is saved first, which takes a few seconds and leaves it running; a stopped one is copied from its last save. Each fork is a separate sandbox from then on, with its own id.
A fork of a sandbox on a node stays on that node: its disk is copied there, and a running sandbox pauses while that happens (cloudex node info says about how long per GiB it has written; stop it first to avoid the pause). --cpus and --memory set the forks’ limits there (default: the original’s).
With --count, the forks are named <name>-1, <name>-2 and so on when --name is given. A single fork becomes the current sandbox. With --json, prints the list of forks.
cloudex fork [sandbox] [flags]
| Flag | Description |
|---|---|
--count int |
how many forks to make, up to 10 (default 1) |
--cpus float |
for a sandbox on a node: the forks’ CPUs (default: the original’s) |
--idle duration |
stop after this long without activity, such as 30m or 2h (default: the original’s) |
--memory string |
for a sandbox on a node: the forks’ memory, such as 4G (default: the original’s) |
--name string |
a name for the fork, or the start of the names with --count |
--no-use |
don’t make the fork the current sandbox |
--size string |
standard-1 to standard-4 (default: the original’s) |
Examples:
cloudex fork
cloudex fork my-box --name try-2
cloudex fork my-box --count 5 --name agent
cloudex save
Save a running sandbox’s disk under a name. Start new sandboxes from it with cloudex new --from <name>.
A sandbox’s own save goes 30 days after it was last made or resumed from; a named save stays in your account’s R2 bucket until you delete it (cloudex saves rm). It holds every file that differs from the sandbox image, so installed packages, Docker images and your files, and the sandbox’s settings (cloudex env). SSH host keys are left out, so each new sandbox makes its own.
The sandbox keeps running. Saving under a name that’s taken replaces that save once the new one is done.
A save moves a sandbox between Cloudflare and your nodes: save it, then start a sandbox from the save with cloudex new --from <name> [--on <node>]. The new one has a new id and new preview links. A save of a sandbox on a node goes up over the node’s own line, and holds whatever that node put in it.
cloudex save [sandbox] <name> [flags]
Examples:
cloudex save base
cloudex save my-box node-22
cloudex saves
List the named saves that new sandboxes can start from (cloudex new --from <name>). Make one with cloudex save.
cloudex saves [flags]
cloudex saves [command]
| Command | Description |
|---|---|
cloudex saves rm |
Delete named saves for good |
cloudex saves rm
Delete named saves. Sandboxes already started from one keep their disks.
cloudex saves rm <name>... [flags]
Also: cloudex saves delete.
| Flag | Description |
|---|---|
-y, --yes |
don’t ask for confirmation |
cloudex list
List sandboxes.
cloudex list [flags]
Also: cloudex ls.
cloudex info
Show a sandbox’s details.
cloudex info [sandbox] [flags]
cloudex use
Make a sandbox the current one.
cloudex use <sandbox> [flags]
cloudex set
Change a sandbox’s name, or how long it may go without SSH, exec, preview or agent activity before it stops and saves its disk. A new idle time applies at once, counting from now; 0 keeps the sandbox up until the platform’s 6-hour limit on Cloudflare, and for good on a node. To change its size, stop it, then resume it with --size.
cloudex set [sandbox] [flags]
| Flag | Description |
|---|---|
--idle duration |
stop after this long without activity, such as 30m or 2h; 0 never stops it on a node, and waits for the 6-hour platform limit on Cloudflare |
--name string |
a new name |
Examples:
cloudex set --idle 2h
cloudex set my-box --name web
cloudex env
A sandbox’s settings: environment variables that every shell, ssh session, exec and agent gets, and files in its home directory. They apply at every start, and at once to a running sandbox; forks get a copy. The deployment keeps them encrypted and never shows values or file contents again. With no subcommand, lists the names, the files and the repo cloned at creation.
GH_TOKEN or GITHUB_TOKEN lets git in the sandbox clone and push private GitHub repos over HTTPS.
cloudex env [sandbox] [flags]
cloudex env [command]
| Command | Description |
|---|---|
cloudex env set |
Set environment variables, and files with --file |
cloudex env unset |
Remove environment variables, and files with --file |
Examples:
cloudex env
cloudex env set DATABASE_URL=postgres://... GH_TOKEN=$(gh auth token)
cloudex env set web --env-file .env --file .npmrc=$HOME/.npmrc
cloudex env unset web DATABASE_URL --file .npmrc
cloudex env set
Set environment variables, from NAME=VALUE arguments and --env-file, and files with --file DEST=SRC, where DEST is a path in the sandbox’s home directory and SRC a file on this computer. New shells get the change at once; a stopped sandbox gets it when it next starts.
cloudex env set [sandbox] NAME=VALUE... [flags]
| Flag | Description |
|---|---|
--env-file stringArray |
read NAME=VALUE lines from this file (repeatable) |
--file stringArray |
DEST=SRC: put the local file SRC at DEST in the sandbox’s home (repeatable) |
cloudex env unset
Remove environment variables, and with --file, files the settings put in the home directory. A first argument that could be a sandbox is taken as one when another argument follows, or --file is given. New shells get the change at once; a stopped sandbox gets it when it next starts.
cloudex env unset [sandbox] NAME... [flags]
Also: cloudex env rm.
| Flag | Description |
|---|---|
--file stringArray |
a file in the sandbox’s home to remove (repeatable) |
cloudex stop
Save a sandbox’s disk and stop it.
cloudex stop [sandbox] [flags]
cloudex resume
Start a stopped sandbox from its saved disk. A save expires after 30 days without a resume; after that, resume restores /home from the newest backup onto a fresh image instead, and anything installed outside /home needs installing again.
With --size, the sandbox runs on that size from then on. Its disk must fit the new size’s (standard-1 8 GB, standard-2 12 GB, standard-3 16 GB, standard-4 20 GB).
cloudex resume [sandbox] [flags]
| Flag | Description |
|---|---|
--from-backup |
restore /home from the newest backup onto a fresh image instead of using the save |
--size string |
run on this size from now on: standard-1, standard-2, standard-3 or standard-4 |
Examples:
cloudex resume
cloudex resume my-box --size standard-4
cloudex delete
Delete a sandbox. Its files can’t be recovered afterwards. Cloudflare removes the last saved disk from your account’s registry within 30 days. On a node, its machine is removed there; while the node is offline that’s refused, unless --force: then the sandbox goes at once, and the node removes the machine when it’s back.
cloudex delete [sandbox] [flags]
Also: cloudex rm.
| Flag | Description |
|---|---|
--force |
on a node that’s offline, delete it anyway; the node removes the machine when it’s back |
-y, --yes |
don’t ask for confirmation |
cloudex ssh
Open a shell in a sandbox. The connection runs through your Cloudex API over a WebSocket, so the sandbox needs no public address. For a sandbox on a node this computer reaches over the LAN or a tailnet, it goes straight to the node instead (the direct path), with the API as the fallback; scp, rsync, ssh-config and attach take the same path. Anything after -- goes to ssh, for example: cloudex ssh my-box -- -L 3000:localhost:3000.
cloudex ssh [sandbox] [-- ssh arguments or a command] [flags]
cloudex ssh-config
Print an ~/.ssh/config block so ssh, scp, rsync and editors reach <sandbox>.cloudex.
cloudex ssh-config [flags]
Examples:
cloudex ssh-config >> ~/.ssh/config
scp notes.txt my-box.cloudex:
rsync -a ./app/ cx-7f3a2k.cloudex:app/
cloudex exec
Run a command with bash in a sandbox, as the cloudex user in its home directory, printing its output as it comes and ending with its exit code. One argument is a shell command line; several are one command and its arguments, quoted for you. Without --, every argument is the command and the current sandbox runs it.
--timeout (at most 1h) stops the command and everything it started. Ctrl-C stops it too. For longer jobs, and servers, use --detach: the command keeps running in the sandbox, and cloudex commands shows it and its output.
Standard input isn’t sent to the command; it sees none. To send data in, use cloudex cp (a <from> of - reads standard input), or ssh with a redirect: cloudex ssh <sandbox> -- ‘cat > file’ < file. Output is text, so for a binary file use cloudex cp <sandbox>:file - instead.
With --json, prints the result as JSON once the command ends, output cut at 1 MiB per stream; with --detach, the background command.
cloudex exec [sandbox] -- <command> [flags]
| Flag | Description |
|---|---|
--cwd string |
working directory (default: the user’s home) |
-d, --detach |
start the command in the background and print its id |
--root |
run as root |
--timeout duration |
stop the command after this long, such as 30m (at most 1h; with --detach, any, and none by default) (default 10m0s) |
Examples:
cloudex exec -- npm test
cloudex exec my-box -- 'cd app && git status'
cloudex exec -- python3 -c 'print(42)'
cloudex exec -d -- npm run dev
cloudex commands
List the commands started in the background with cloudex exec --detach (or the API), newest first. Their output stays on the sandbox’s disk until you remove them with cloudex commands rm. A stop ends them; they show as lost after.
cloudex commands [sandbox] [flags]
cloudex commands [command]
| Command | Description |
|---|---|
cloudex commands kill |
Stop a background command and everything it started |
cloudex commands logs |
Print a background command’s output |
cloudex commands rm |
Remove a finished background command and its output |
Examples:
cloudex commands
cloudex commands logs -f cm-1a2b3c4d
cloudex commands kill cm-1a2b3c4d
cloudex commands kill
Stop a background command and everything it started.
cloudex commands kill [sandbox] <id> [flags]
| Flag | Description |
|---|---|
--signal string |
TERM, INT, HUP or KILL (default “TERM”) |
cloudex commands logs
Print a background command’s output: standard output and standard error together, as written. With -f, keep printing until the command ends, then exit with its exit code; Ctrl-C stops following, and the command keeps running.
cloudex commands logs [sandbox] <id> [flags]
| Flag | Description |
|---|---|
-f, --follow |
keep printing until the command ends |
cloudex cp
Copy a file or a directory between this computer and a sandbox. Name a path in a sandbox as SANDBOX:PATH, or :PATH for the current sandbox; relative paths there start in the home directory.
Like cp -r: when <to> is a directory that exists, or ends with /, what you copy goes inside it; otherwise it’s created as <to>. A file keeps its permissions, and a directory goes as a tar.gz. A <from> of - reads a file from standard input, and a <to> of - writes one to standard output. Uploads are limited to 100 MB at a time (Cloudflare’s limit); for more, use rsync over cloudex ssh-config.
A directory copied out of a sandbox leaves out .git directories, hard links, devices, symlinks that point outside it, and files the sandbox user can’t read (--root reads them). The summary on standard error counts what was left out, but not the files that couldn’t be read.
cloudex cp <from> <to> [flags]
| Flag | Description |
|---|---|
--root |
read and write in the sandbox as root |
Examples:
cloudex cp report.csv :data/
cloudex cp ./site my-box:/srv/site
cloudex cp :app/dist ./dist
cloudex cp my-box:/var/log/app.log -
cloudex run
Start a sandbox, copy this directory into it, run a command there with its output coming back as it’s printed, copy back what --out names, and delete the sandbox. Ends with the command’s exit code, for scripts and CI.
In a git repository, the files git would commit are copied: tracked ones and new ones it doesn’t ignore, but not .git. Elsewhere, everything under --dir. They go to a directory of the same name in the home directory, where the command runs. Uploads are limited to 100 MB compressed.
--from starts from a named save, or a fork of a sandbox, instead of the image: set one up with your tools and dependencies, save it (cloudex save), and each run starts from it with the latest files copied over.
The command runs in the background in the sandbox, so a dropped connection doesn’t stop it, and has no time limit unless --timeout sets one. Ctrl-C stops it and deletes the sandbox. --keep keeps the sandbox, and --keep-on-failure keeps it when the command fails or is stopped, to look around with cloudex ssh.
A directory copied back by --out leaves out .git directories, hard links, devices, symlinks that point outside it, and files the sandbox user can’t read; the summary on standard error counts what was left out, but not unreadable files.
cloudex run [flags] -- <command>
| Flag | Description |
|---|---|
--dir string |
the directory to copy into the sandbox (default “.”) |
--env stringArray |
NAME=VALUE: an environment variable (repeatable) |
--env-file stringArray |
read NAME=VALUE lines from this file (repeatable) |
--from string |
start from this named save, or a fork of this sandbox |
--idle duration |
stop the sandbox after this long without activity, if it’s kept (default 30m0s) |
--keep |
keep the sandbox after, running |
--keep-on-failure |
keep the sandbox when the command fails |
--name string |
a name for the sandbox (default: none) |
--no-upload |
don’t copy any files; run in the home directory unless --workdir says |
--on string |
run it on this node (your own Docker host; see cloudex node) instead of Cloudflare |
--out stringArray |
a file or directory to copy back after, relative to the workdir; it lands at the same place under --dir (repeatable) |
--size string |
standard-1, standard-2 (default), standard-3 or standard-4 |
--timeout duration |
stop the command after this long, such as 30m (default: no limit) |
--workdir string |
where it goes in the sandbox, and the command runs (default: the directory’s name, in the home directory) |
Examples:
cloudex run -- npm test
cloudex run --from node-base --out dist -- 'npm ci && npm run build'
cloudex run --env CI=1 --keep-on-failure -- make check
cloudex host
Print a link that serves a port in the sandbox over HTTPS on the domain you chose at deploy time. The link contains a secret token, so only people you share it with can open it. Servers that listen only on localhost work too.
The same port gives the same link until you revoke it with --revoke, which makes it stop working at once and closes connections open through it; run cloudex host again for a new one. --revoke-all does that for every link to the sandbox, the desktop’s too, including links made before v0.1.14, which --list doesn’t show.
cloudex host [sandbox] <port> [flags]
| Flag | Description |
|---|---|
--list |
list the links made since v0.1.14 that still work |
--revoke |
make the port’s link stop working |
--revoke-all |
make every link to the sandbox stop working, the desktop’s too |
Examples:
cloudex host 3000
cloudex host my-box 5173
cloudex host 3000 --revoke
cloudex host --list
cloudex desktop
Show a desktop running in the sandbox in your browser. The first time installs it, which takes a minute or two; after that it starts in seconds. Windows that programs in the sandbox open, such as an agent’s browser, appear on it.
By default the desktop is reached through a port on this computer until you press Ctrl-C; it keeps running in the sandbox after that. With --link you get an HTTPS link on your preview domain instead, which works from any browser while the sandbox runs, for anyone who has it. The sandbox stays up while a browser shows its desktop.
cloudex desktop [sandbox] [flags]
| Flag | Description |
|---|---|
--link |
print an HTTPS link on your preview domain instead of using a local port |
--no-open |
don’t open a browser |
--port int |
local port to use (default 6080, or a free one) |
--quality int |
picture quality, 0 to 9: lower uses less bandwidth on moving images (text stays sharp) (default 3) |
--size string |
screen size, WIDTHxHEIGHT (a new desktop gets 1280x720; a running one is resized only when you give this) |
--stop |
stop the desktop and the programs on it |
Examples:
cloudex desktop
cloudex desktop my-box --size 1920x1080
cloudex desktop --link
cloudex desktop --stop
cloudex prompt
Start Claude Code, Codex or OpenCode on a task in a tmux session inside the sandbox, then attach to it. Detach with Ctrl-b d; the agent keeps working and the sandbox stays up while it does. Reattach with cloudex attach.
The agent needs a key or a login: store an API key with cloudex keys set, or sign in once (cloudex ssh, then run claude, codex or opencode), which is saved with the sandbox’s disk. Agents run without their own permission prompts; the sandbox is the boundary.
cloudex prompt [sandbox] <task> [flags]
| Flag | Description |
|---|---|
--agent string |
claude, codex or opencode (default “claude”) |
-d, --detach |
start the agent without attaching |
Examples:
cloudex prompt "make the tests pass"
cloudex prompt my-box --agent codex "add a dark mode"
cloudex attach
Reattach to a session that cloudex prompt started, the newest by default. A session is named like agent-1104-153012; cloudex prompt prints its name.
cloudex attach [sandbox] [session] [flags]
cloudex agents
Agents that work without a terminal, as the SDKs start them: Claude Code, Codex or OpenCode takes a task, then any follow-up messages, one turn each. Their logs live in the sandbox, so they survive stops, resumes and forks. With no subcommand, lists a sandbox’s agents.
Commands that take an agent use the most recently active one when it’s left out. For an agent in a terminal you can attach to, use cloudex prompt.
cloudex agents [sandbox] [flags]
cloudex agents [command]
| Command | Description |
|---|---|
cloudex agents interrupt |
Stop an agent’s running turn and drop its queued messages |
cloudex agents logs |
Print what an agent did |
cloudex agents send |
Send an agent a follow-up message |
cloudex agents start |
Start an agent on a task and follow it |
Examples:
cloudex agents start "make the tests pass"
cloudex agents logs -f
cloudex agents send "now add a test for the empty case"
cloudex agents interrupt
cloudex agents interrupt
Stop the turn an agent is working on and drop any queued messages. The conversation stays: send a message to carry on.
cloudex agents interrupt [sandbox] [agent] [flags]
Also: cloudex agents stop.
cloudex agents logs
Print an agent’s log: the prompts, the agent’s messages, the commands it ran, the files it changed, and how each turn ended. With --json, the events as the API returns them, one per line, including the agent’s own JSON.
cloudex agents logs [sandbox] [agent] [flags]
| Flag | Description |
|---|---|
-f, --follow |
keep printing until the agent has nothing left to do |
cloudex agents send
Send an agent its next message. It continues the same conversation, after the running turn if there is one. --interrupt stops the running turn and drops queued messages first, to steer the agent. Then prints what it does, like start. A message of - is read from standard input.
cloudex agents send [sandbox] [agent] <message> [flags]
| Flag | Description |
|---|---|
-d, --detach |
send without following the agent |
--interrupt |
stop the running turn and drop queued messages first |
cloudex agents start
Start Claude Code, Codex or OpenCode on a task, then print what it does until it finishes. Ctrl-C stops following; the agent keeps working. A task of - is read from standard input.
The agent needs a key or a login: store an API key with cloudex keys set, or sign in once in the sandbox. Agents run without their own permission prompts; the sandbox is the boundary.
cloudex agents start [sandbox] <task> [flags]
| Flag | Description |
|---|---|
--agent string |
claude, codex or opencode (default “claude”) |
--cwd string |
directory to work in (default: the home directory) |
-d, --detach |
start the agent and print its id without following it |
--model string |
the agent’s model, such as opus, gpt-5 or, for OpenCode, provider/model (default: the agent’s own) |
cloudex dashboard
Open the dashboard, which the deployment serves at its API URL: sandboxes with their terminals, desktops, agents, commands and files, named saves, and (for admins) tokens, sign-ins and provider keys. With a sandbox, it opens on that one.
It signs the browser in with a one-time link that lasts 60 seconds. The browser gets a session of its own, with this computer’s role, which lasts 30 days from its last use and shows in cloudex tokens, where it can be revoked.
cloudex dashboard [sandbox] [flags]
| Flag | Description |
|---|---|
--no-open |
print the link instead of opening a browser |
Examples:
cloudex dashboard
cloudex dashboard my-box
cloudex dashboard --no-open
cloudex deploy
Install Cloudex in your Cloudflare account, or update it. It needs Workers Paid ($5/month) and an API token, read from $CLOUDFLARE_API_TOKEN or asked for. Create the token with this link, which pre-fills the permissions:
Preview links need a domain in the same account: --preview-domain example.dev. Running deploy again updates the API and image and keeps your sandboxes, your API key and your preview domain. On another computer, run cloudex login instead.
cloudex deploy [flags]
| Flag | Description |
|---|---|
--account-id string |
Cloudflare account id (needed when the token reaches several) |
--image string |
sandbox image to install (default “ghcr.io/lucataco/cloudex-base:v0.2.3”) |
--preview-domain string |
a domain in the account to serve preview links on (‘’ turns them off) |
--skip-check |
don’t start a test sandbox after deploying |
--yes |
replace the API key of an existing deployment without asking |
cloudex login
Point this computer at a deployment made elsewhere, without redeploying (which would replace its API key).
With no key, it asks the deployment for a token of this computer’s own and shows a code; on a computer that already uses the deployment, approve it with cloudex tokens approve <code>. A key is used instead when given: from $CLOUDEX_API_KEY, from standard input, or asked for with --key. The admin key or a token works.
cloudex login [flags]
| Flag | Description |
|---|---|
--key |
ask for a key instead of signing in with a code |
--name string |
what this computer’s token is called (default: cloudex on <host name>) |
--role string |
the role to ask for: admin, user or read (the approver decides, and admin only if they choose it) |
--url string |
the deployment’s API URL |
Examples:
cloudex login --url https://cloudex-api.example.workers.dev
cloudex login --url https://cloudex-api.example.workers.dev --key
echo "$CLOUDEX_TOKEN" | cloudex login --url https://cloudex-api.example.workers.dev
cloudex node
A node is a Linux host of your own, with Docker, that runs sandboxes for this deployment. An agent on it, cloudex-node, dials out to the deployment and stays connected. It takes one inbound port, 7022, on its LAN and tailnet addresses only, for direct ssh from those networks, and each connection needs a ticket from the deployment (the installer’s --direct off opens none). cloudex node add prints the command that installs the agent with a join token, which works once, for 30 minutes. Adding and removing nodes needs the admin key or an admin token. With no subcommand, lists the nodes.
cloudex node [flags]
cloudex node [command]
Also: cloudex nodes.
| Command | Description |
|---|---|
cloudex node add |
Add a node, and print the command that installs its agent |
cloudex node info |
Show a node: its state, its host, where it connects, and a round trip to it |
cloudex node list |
List the nodes, whether each is online, and what it has |
cloudex node rm |
Remove a node: its agent is disconnected and its key stops working |
Examples:
cloudex node add box
cloudex node list
cloudex node info box
cloudex node rm box
cloudex node add
Add a node and print the command to run on it as root, which starts the agent with a join token. The token works once, for 30 minutes; adding the same name again before the node joins gives a new one.
cloudex node add <name> [flags]
cloudex node list
List the nodes, whether each is online, and what it has.
cloudex node list [flags]
Also: cloudex node ls.
cloudex node rm
Remove a node. Its agent is disconnected at once and can’t connect again; the node stays listed as revoked until it’s removed a second time. A node that still has sandboxes is refused unless --force is given. With --force, an online node removes their machines first; the sandboxes stay listed, in state error, until you delete them. An offline node’s agent hears that it was removed when it next connects, and stops its machines; their disks stay on the host until you run the installer there with --uninstall.
cloudex node rm <name> [flags]
Also: cloudex node remove, cloudex node delete.
| Flag | Description |
|---|---|
--force |
remove it even though it has sandboxes |
-y, --yes |
don’t ask for confirmation |
cloudex tokens
Access tokens work in place of the deployment’s admin key, each with a role, and can be limited to the sandboxes they make, expire, and be revoked at once:
admin everything, including tokens and provider keys user everything to sandboxes and saves, but not tokens or provider keys read lists, info, agent events, command output and file reads
--own limits a token to the sandboxes it makes (and their forks): it sees no others, and can start from named saves but not make or delete them. That suits CI and agents. Making and revoking tokens needs the admin key or an admin token.
cloudex login on another computer, without a key, asks for a token with a code; approve it here with cloudex tokens approve. With no subcommand, lists the tokens.
cloudex tokens [flags]
cloudex tokens [command]
| Command | Description |
|---|---|
cloudex tokens approve |
Approve a computer’s sign-in by the code it shows |
cloudex tokens create |
Make a token; its secret is shown once |
cloudex tokens deny |
Refuse a computer’s sign-in |
cloudex tokens list |
List the tokens, with their roles and when each was last used |
cloudex tokens revoke |
Revoke a token or a dashboard session; it stops working at once |
Examples:
cloudex tokens create ci --own --expires 90d
cloudex tokens
cloudex tokens approve BCDF-GHJK
cloudex tokens revoke tk-a2b3c4d5
cloudex tokens approve
cloudex login on a computer without a key shows a code such as BCDF-GHJK. Approving it gives that computer a token of its own, which expires in 90 days unless --expires says otherwise. Its role is user, or read if it asked for read; admin only with --role admin, since anyone can ask for admin. With no code, lists the sign-ins waiting. Only approve a code you started yourself: whoever holds the other computer gets the token.
cloudex tokens approve [code] [flags]
| Flag | Description |
|---|---|
--expires string |
how long its token works, such as 12h, 30d or never (default “90d”) |
--own |
only the sandboxes that computer makes |
--role string |
admin, user or read (default: user, or read if it asked for read) |
-y, --yes |
approve without asking |
cloudex tokens create
Make an access token and print its secret, which nothing shows again. Give it to the program that will use it as CLOUDEX_API_KEY, with CLOUDEX_API_URL set to this deployment’s URL, or with cloudex login on another computer.
cloudex tokens create <name> [flags]
| Flag | Description |
|---|---|
--expires string |
how long it works, such as 12h, 30d or never (default “never”) |
--own |
only the sandboxes this token makes |
--role string |
admin, user or read (default “user”) |
cloudex tokens list
List the tokens, with their roles and when each was last used.
cloudex tokens list [flags]
Also: cloudex tokens ls.
cloudex tokens revoke
Revoke a token or a dashboard session; it stops working at once.
cloudex tokens revoke <id> [flags]
Also: cloudex tokens rm.
cloudex keys
Store an AI provider’s API key in your deployment: anthropic, openai, openrouter, google, groq, mistral, xai or deepseek. Sandboxes started after that get a placeholder key, and the real one is added to their HTTPS calls to the provider as they leave, so it never enters a sandbox, its saves, backups or forks. Claude Code, Codex, OpenCode, the providers’ SDKs and curl work as if the key were there. A key a sandbox brings itself is used as is. While a provider’s key is stored here, the agents in a sandbox use it even if someone signs in there with a subscription; to use a subscription instead, remove the key with cloudex keys rm.
A new provider reaches a running sandbox when it next starts (stop it, then resume it, to start it now); a changed key reaches it within a minute. With no subcommand, lists the keys.
cloudex keys [flags]
cloudex keys [command]
| Command | Description |
|---|---|
cloudex keys list |
List the stored keys (only their last 4 characters) |
cloudex keys rm |
Remove a provider’s key |
cloudex keys set |
Store a provider’s key |
Examples:
cloudex keys set anthropic
cloudex keys set openai --from-env
cloudex keys set openrouter < key.txt
cloudex keys
cloudex keys rm openai
cloudex keys rm
Remove a provider’s key.
cloudex keys rm <provider> [flags]
Also: cloudex keys delete.
cloudex keys set
Store a provider’s API key: anthropic, openai, openrouter, google, groq, mistral, xai or deepseek. It’s read from a hidden prompt, from standard input when piped, or with --from-env from the provider’s usual variable, such as $ANTHROPIC_API_KEY, $OPENROUTER_API_KEY or, for Google, $GEMINI_API_KEY. The provider is asked whether it accepts the key first, and a key it rejects isn’t stored.
cloudex keys set <provider> [flags]
| Flag | Description |
|---|---|
--from-env |
read the key from the provider’s usual variable, such as $ANTHROPIC_API_KEY |
cloudex status
Check the connection to your Cloudex deployment.
cloudex status [flags]
| Flag | Description |
|---|---|
--show-key |
print the API key too |
cloudex doctor
Check this computer and your deployment for problems.
cloudex doctor [flags]
cloudex update
Download the latest release of the CLI, check it against the release’s checksums and put it in place of this one. Then, if your deployment runs an older version, offer to update it with cloudex deploy, which keeps your sandboxes. Sandboxes running during the update keep the old version until they stop. --check only says what’s out of date.
cloudex update [flags]
| Flag | Description |
|---|---|
--check |
only say whether the CLI or the deployment is out of date |
cloudex version
Print the CLI version.
cloudex version [flags]
cloudex feedback
Send feedback to the Cloudex maintainers as a public issue on github.com/lucataco/cloudex. With --last-error, the report includes the last command that failed (its flags’ names, not their values) and its error. A message of - is read from standard input. Flags go before the message.
Before anything is sent, Cloudex removes the deployment’s key and addresses, link tokens, the sandbox names it knows of, public IP addresses and anything that looks like a secret, and shows you the report. In a terminal it then asks. It’s filed with the GitHub CLI (gh) when that’s signed in, under that account; otherwise GitHub’s new-issue page opens with the report filled in, for you to submit.
Without a terminal, as when an agent runs it, or with a piped message, nothing is sent: the report is printed and saved with an id. Show it to the person you work for and, with their OK, send exactly that report, the way it said it would go, with --send <id>.
Report security problems privately instead, at https://github.com/lucataco/cloudex/security/advisories/new.
cloudex feedback [flags] [message]
| Flag | Description |
|---|---|
--last-error |
include the last command that failed and its error |
--send string |
send the report saved with this id, exactly as it was shown |
--web |
open GitHub’s new-issue page instead of filing with gh |
-y, --yes |
send without asking; the report is printed as it goes |
Examples:
cloudex feedback "fork is slow on a 15 GB sandbox"
cloudex feedback --last-error "this happened while deploying"
cat notes.md | cloudex feedback -
cloudex feedback --send 3f2a9c1d
cloudex completion
Generate the autocompletion script for cloudex for the specified shell. See each sub-command’s help for details on how to use the generated script.
cloudex completion [command]
| Command | Description |
|---|---|
cloudex completion bash |
Generate the autocompletion script for bash |
cloudex completion fish |
Generate the autocompletion script for fish |
cloudex completion powershell |
Generate the autocompletion script for powershell |
cloudex completion zsh |
Generate the autocompletion script for zsh |