Use sandboxes
Sandboxes
Create, list, change, stop, resume and delete sandboxes, pick a size or a node, run commands at every start, manage a sandbox from inside it, and how idle stop, the 6-hour limit, saves and backups work.
Create a sandbox
cloudex new --name web
cloudex new --name big --size standard-4 --idle 2h
cloudex new creates a sandbox, starts it and waits until it’s running. The first start on a Cloudflare host can take a minute while the host fetches the image.
| Flag | Default | Effect |
|---|---|---|
--name |
none | A name to use instead of the id |
--size |
standard-2 |
standard-1, standard-2, standard-3 or standard-4; see Sizes |
--idle |
30m |
Stop after this long without activity; see Idle stop |
--no-use |
off | Don’t make it the current sandbox |
--from, --count |
none | Start from a copy of another sandbox’s disk; see Forks |
--on, --cpus, --memory |
none | Run it on one of your nodes instead of Cloudflare, with these limits |
--env, --env-file, --file, --repo |
none | Environment variables and files at every start, and a repo to clone; see Settings |
Every sandbox has an id like cx-7f3a2k. A name is optional and must be unique. Names are 2 to 32 characters of lowercase letters, digits and hyphens, start with a letter, don’t end with a hyphen, and don’t start with cx-, which marks ids. Commands take either the id or the name. cloudex set --name changes the name later; see Change a sandbox.
The current sandbox
cloudex new makes the new sandbox the current one, and so does cloudex fork when it makes a single fork. Commands with an optional [sandbox] argument, such as ssh, exec, stop and info, act on it when you don’t name one. cloudex use <sandbox> picks another.
cloudex list # all sandboxes; * marks the current one
cloudex info # details of the current sandbox
cloudex use api # make "api" the current sandbox
cloudex list (or cloudex ls) shows each sandbox’s id, name, state, where it runs (cloudflare or a node), size, when it was last saved and when it was created. cloudex info adds the idle setting, how much the last save held, the last backup, what it was forked from or the named save it started from, and notes such as a restore from backup.
A sandbox is in one of five states: starting, running, stopping, stopped or error. error means its first start failed; the note in cloudex info says why, and cloudex resume tries again. A command the state doesn’t allow says what to do instead. While the sandbox is starting or stopping, it says to try again in a moment. When the sandbox is stopped, it says to resume it.
Sizes
Sizes are Cloudflare’s container instance types. The disk includes the system image.
| Size | vCPU | Memory | Disk |
|---|---|---|---|
standard-1 |
1/2 | 4 GiB | 8 GB |
standard-2 (default) |
1 | 6 GiB | 12 GB |
standard-3 |
2 | 8 GiB | 16 GB |
standard-4 |
4 | 12 GiB | 20 GB |
The largest is 4 vCPU, 12 GiB and 20 GB. A sandbox on a node has the CPUs and memory you give it with --cpus and --memory instead, up to the node’s own. A sandbox’s size is set when you create it. cloudex resume --size standard-4 starts a stopped sandbox on another size, which it keeps from then on; its disk has to fit the new size’s. A fork can also have a different size from its original.
Stop and resume
cloudex stop
cloudex resume
cloudex stop saves the sandbox’s disk, backs up /home to R2, and stops its container. A save holds only what changed since the previous one. Saving a full disk took about three minutes in testing; small changes take seconds.
cloudex resume starts a stopped sandbox from its save, with its files, installed packages and agent logins. A sandbox with a few GB of files is usually back within seconds; one with 15 GB can take about two minutes.
A save holds the disk, not running programs. After a resume, start your servers and agent sessions again, or let start commands do it. Agent history on disk is still there.
On a node, cloudex stop stops the machine in about a second and its disk stays on the node, with no save and no backup. cloudex resume starts it again in a second or two.
Start commands
cloudex exec web -- 'mkdir -p ~/.cloudex && echo "cd ~/app && npm run dev" > ~/.cloudex/start'
If the sandbox has a file ~/.cloudex/start, it runs at every start: after cloudex new (and the repo clone, if any), cloudex resume and cloudex fork. It runs with bash as the cloudex user from a login shell, so it has the sandbox’s variables and provider keys, in the background, so the start doesn’t wait for it. Its output goes to ~/.cloudex/start.log.
Use it to start dev servers, workers and agents’ tools again after a resume. Since the file is on the sandbox’s disk, saves, backups and forks keep it. To give a new sandbox one, use cloudex new --file .cloudex/start=./start.sh; a file from the settings is written again at every start, replacing any change made inside the sandbox.
Idle stop
A sandbox stops by itself, saving its disk first, after --idle without activity. The default is 30 minutes. These count as activity:
- An SSH connection that is sending data:
cloudex ssh, plainsshthrough ssh-config,cloudex promptandcloudex attach. ssh sends a keepalive every 30 seconds, so an open session counts. A connection that has gone silent doesn’t. - A command run with
cloudex exec, or with an exec call through the API or an SDK, for as long as it runs, even when it prints nothing cloudex cpandcloudex run, and command and file calls through the API or an SDK- A background command that has printed output in the last 10 minutes
- Requests to a preview link
- A browser showing the sandbox’s desktop
- An agent session that has printed output in the last 10 minutes
- Calls to AI providers that use provider keys
--idle takes a duration such as 45m or 2h, rounded down to whole minutes, up to 6 hours. --idle 0 turns off Cloudex’s own idle stop, which leaves Cloudflare’s limit below; on a node, which has no such limit, the sandbox then runs until you stop it. cloudex set --idle changes it later.
Change a sandbox
cloudex set --idle 2h # the current sandbox
cloudex set web --name site # rename
cloudex set changes a sandbox’s name or its idle time, running or stopped. A new idle time applies at once, counting from now. To change the size, stop the sandbox and run cloudex resume --size.
Inside the sandbox
Every sandbox has its own cloudex command, which manages that sandbox and nothing else. It needs no key: the deployment knows which sandbox each request comes from.
cloudex host 3000 # a preview link to port 3000
cloudex host --list # the links that work; --revoke and --revoke-all as outside
cloudex info # this sandbox
cloudex set --idle 2h # stay up longer without activity
cloudex stop # save the disk and stop
It prints JSON when its output isn’t a terminal, like the CLI on your computer. It can’t create, fork or delete sandboxes. cloudex stop answers at once, and the sandbox saves and stops a few seconds later. It works the same on a node, where its requests go through the node’s agent.
Claude Code, Codex and OpenCode in a sandbox are told about it, in /etc/claude-code/CLAUDE.md and a marked block in ~/.codex/AGENTS.md and ~/.config/opencode/AGENTS.md, so an agent that starts a server can give you its link. A cloudex you install in the sandbox yourself is left alone.
The 6-hour limit
Whatever --idle says, Cloudflare stops a container after at most 6 hours of inactivity. Sandboxes on a node have no such limit. Its timer counts connections from outside, such as an open cloudex ssh session; work inside the sandbox, such as an agent running on its own, doesn’t reset it. To keep a long task going past 6 hours, keep a connection open, for example cloudex attach in a terminal.
When Cloudflare stops a sandbox, the sandbox saves its disk and backs up /home first. If that save fails, cloudex info says so, and cloudex resume starts from the previous save.
Saves
A save is a copy of the sandbox’s whole disk, stored in your account’s container registry. A sandbox on a node has none: its disk stays on the node when it stops.
- A save expires 30 days after it was made or last restored. After that,
cloudex resumerestores/homefrom the newest backup onto a fresh copy of the image instead, and anything installed outside/homeneeds installing again.cloudex resumeandcloudex infosay when this happened. - A save keeps the system image it was made on. Resuming from it brings back the same system, even after
cloudex deployhas installed a newer image. To move a sandbox onto the current image, usecloudex resume --from-backup.
To keep a copy of a sandbox’s disk for longer, and start new sandboxes from it, make a named save with cloudex save.
Backups
Each stop also backs up /home, without ~/.cache, and the SSH host keys to the R2 bucket cloudex-backups in your account. Cloudex keeps the newest backup for each sandbox. Backups don’t expire, and they restore onto any image.
cloudex resume --from-backup
--from-backup restores /home from the newest backup onto a fresh copy of the current image instead of using the save. Anything installed outside /home, such as apt packages and Docker images, needs installing again.
- If a backup fails, the stop still succeeds and the save has your files.
cloudex stopprints the error, andcloudex infoshows it. - Backups need R2 turned on for the account.
cloudex statusshows whether they’re on; see Backups and R2. - In testing, backups moved about 110 MiB/s each way: a 5 GB home directory backed up in 43 seconds and restored in 54.
- Sandboxes on a node have no backups. For a copy off the node, make a named save.
Delete
cloudex delete web
cloudex delete (or cloudex rm) deletes a sandbox and its backups. It asks first; -y or --yes skips the question, and is required when the command isn’t run in a terminal. The files can’t be recovered. The sandbox’s last save stays in your account’s container registry until it expires, within 30 days.
On a node, delete removes the sandbox’s machine there. While the node is offline it’s refused, unless you add --force: then the sandbox goes at once, and the node removes the machine when it’s back.