DocsCLI reference

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:

Open dash.cloudflare.com

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

For agents and LLMs: this page as Markdown,llms.txt and all docs in one file.