Use sandboxes
Forks
Make up to ten new sandboxes that start from a copy of one sandbox's whole disk, with cloudex fork or cloudex new --from --count.
A fork is a new sandbox that starts from a copy of another sandbox’s whole disk: files, installed packages, settings and agent logins. Set up a sandbox once, then fork it to try several approaches at once, or to give each agent its own copy.
cloudex fork # one fork of the current sandbox
cloudex fork web --name web-try
cloudex fork web --count 5 --name agent # agent-1 to agent-5
cloudex new --from web --count 5 --name agent # the same thing
cloudex new --from <sandbox> does the same as cloudex fork <sandbox> and takes the same flags.
| Flag | Default | Effect |
|---|---|---|
--count |
1 |
How many forks to make, up to 10 |
--name |
none | The fork’s name. With --count, forks are named <name>-1, <name>-2 and so on. |
--size |
the original’s | standard-1 to standard-4. Not for a sandbox on a node. |
--cpus, --memory |
the original’s | For a sandbox on a node: the forks’ CPUs and memory there |
--idle |
the original’s | Stop after this long without activity |
--no-use |
off | Don’t make the fork the current sandbox |
What gets copied
On Cloudflare:
- A running sandbox is saved first. That takes a few seconds, and it keeps running; its file system pauses for a moment.
- A stopped sandbox is copied from its last save.
- Every fork starts from the same save, at the same time. Ten forks took about 20 seconds in testing.
- The copy is of the disk, not of running programs. Start servers and agents again in each fork.
- Anything stored in files comes along, including agent logins and any API keys you’ve saved on the disk. Keys stored with
cloudex keysaren’t on the disk; forks use them like any new sandbox. Forks also get a copy of the original’s settings, its environment variables and files, which then change separately.
A fork on a node is copied differently; see On a node.
A fork copies a sandbox as it is now. To keep a copy for later, and start sandboxes from it when you need them, make a named save instead: it stays until you delete it.
After forking
Each fork is a separate sandbox from then on, with its own id, saves and backups. Changes in a fork don’t reach the original, or the other way round. cloudex info shows what a sandbox was forked from.
A single fork becomes the current sandbox, unless you pass --no-use. With --count, the CLI prints a table of the forks and leaves the current sandbox as it was. With --json, it prints the list of forks.
A fork that fails to start is kept in the error state with the reason. The CLI says how many failed and exits with an error. Run cloudex resume on a failed fork to try again, or delete it.
When a sandbox can’t be forked
- A stopped sandbox with no save can’t be forked. Resume it, then fork it.
- A stopped sandbox whose save has expired can’t be forked either. Resume it, which restores its backup, then fork it.
- A sandbox that is starting or stopping can’t be forked until it has finished.
- A fork stays where its original is: a sandbox on Cloudflare can’t be forked onto a node, nor one on a node onto Cloudflare or another node. Save the sandbox with
cloudex save, then start sandboxes from the save withcloudex new --from <save>, adding--on <node>to start them on a node. - A sandbox on a node that’s offline can’t be forked until the node is back.
On a node
A sandbox on a node forks on that node, where its disk is. Forks are new on nodes in v0.2.3, and need it on the deployment and the node’s agent.
cloudex fork n1 --count 3 # n1-1 to n1-3, on n1's node
cloudex fork n1 --cpus 8 --memory 32G # more than n1 has
- The copy. The node copies the original’s disk into an image, running or stopped, with no save and no 30-day limit. The forks of one request share that image, so the node holds one copy however many forks there are. Each fork then writes to its own layer on top.
- A running original pauses while its disk is copied, then carries on. That takes about 2 to 3 seconds per GB the sandbox has written on Docker’s overlay2 image store, or 12 to 13 seconds on its containerd image store, which Docker 29 uses on new installs. A sandbox that has written 5 GB is paused for about a minute on the containerd store.
cloudex forksays before it starts about how long it is per GB on that node, andcloudex node infoshows it too. Stop the sandbox first to avoid the pause. Starting the forks after the copy takes a few seconds. - Disk. The copy takes about as much space as the original had written, twice that on the containerd store, and is removed with the last sandbox that uses it, once each fork of the request has started or been deleted (a fork that hasn’t keeps it for up to 7 days). Copies under way count against the node’s free space, so a second fork, or a new sandbox, that would leave the node under 10 GB free once the copy is done is refused until it finishes. See Disk.
- Limits.
--cpusand--memorydefault to the original’s, up to what the node has.--sizeis refused. Own-only tokens can’t fork on plain-Docker nodes, as they can’t make sandboxes there. Each fork of a fork adds a layer to its image, so forks of forks go about 100 levels deep; past that, make a named save and start from it, which starts flat. - Docker inside. On a Sysbox node, the forks have the original’s Docker images and containers, whether it was running or stopped.
- What’s new in each fork: its id, host name, preview links and run state, as on Cloudflare. Like a Cloudflare fork, it shares the original’s SSH host keys.
From code
The SDKs fork too. This runs a test suite in ten forks at once:
import { Cloudex } from "cloudex";
const box = await new Cloudex().get("web");
const forks = await box.fork({ count: 10, name: "try" });
const results = await Promise.all(forks.map((f, i) => f.exec(["npm", "test", "--", `--shard=${i + 1}/10`])));
await Promise.all(forks.map((f) => f.delete()));