# 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

```sh
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](#sizes) |
| `--idle` | `30m` | Stop after this long without activity; see [Idle stop](#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](https://cloudex.build/docs/forks.md) |
| `--on`, `--cpus`, `--memory` | none | Run it on one of your [nodes](https://cloudex.build/docs/nodes.md) 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](https://cloudex.build/docs/settings.md) |

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](#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.

```sh
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](https://cloudex.build/docs/nodes.md)), 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](https://cloudex.build/docs/saves.md) 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](https://cloudex.build/docs/nodes.md) 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](https://cloudex.build/docs/forks.md) can also have a different size from its original.

## Stop and resume

```sh
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](#start-commands) do it. Agent history on disk is still there.

On a [node](https://cloudex.build/docs/nodes.md), `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

```sh
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](https://cloudex.build/docs/settings.md) and [provider keys](https://cloudex.build/docs/keys.md), 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](https://cloudex.build/docs/settings.md) 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`, plain `ssh` through [ssh-config](https://cloudex.build/docs/connect.md#scp-rsync-and-editors), `cloudex prompt` and `cloudex 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 cp` and `cloudex run`, and command and file calls through the API or an SDK
- A [background command](https://cloudex.build/docs/commands.md#background-commands) that has printed output in the last 10 minutes
- Requests to a preview link
- A browser showing the sandbox's [desktop](https://cloudex.build/docs/desktop.md)
- An [agent session](https://cloudex.build/docs/agents.md) that has printed output in the last 10 minutes
- Calls to AI providers that use [provider keys](https://cloudex.build/docs/keys.md)

`--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](https://cloudex.build/docs/nodes.md), which has no such limit, the sandbox then runs until you stop it. `cloudex set --idle` changes it later.

## Change a sandbox

```sh
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.

```sh
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](https://cloudex.build/docs/nodes.md), 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](https://cloudex.build/docs/nodes.md) 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](https://cloudex.build/docs/nodes.md) 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 resume` restores `/home` from the newest [backup](#backups) onto a fresh copy of the image instead, and anything installed outside `/home` needs installing again. `cloudex resume` and `cloudex info` say when this happened.
- A save keeps the system image it was made on. Resuming from it brings back the same system, even after `cloudex deploy` has installed a newer image. To move a sandbox onto the current image, use `cloudex resume --from-backup`.

To keep a copy of a sandbox's disk for longer, and start new sandboxes from it, make a [named save](https://cloudex.build/docs/saves.md) 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.

```sh
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 stop` prints the error, and `cloudex info` shows it.
- Backups need R2 turned on for the account. `cloudex status` shows whether they're on; see [Backups and R2](https://cloudex.build/docs/deploy.md#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](https://cloudex.build/docs/nodes.md) have no backups. For a copy off the node, make a [named save](https://cloudex.build/docs/saves.md).

## Delete

```sh
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](https://cloudex.build/docs/nodes.md), 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.
