DocsNamed saves

Use sandboxes

Named saves

Keep a copy of a sandbox's disk under a name until you delete it, start new sandboxes from it with cloudex save and cloudex new --from, and move sandboxes between Cloudflare and your nodes.

A sandbox’s own save goes 30 days after it was last made or resumed from. A named save is a copy of a sandbox’s disk that stays in your account’s R2 bucket until you delete it. Set a sandbox up once, with its packages, Docker images, repos and agent logins, save it, and start new sandboxes from it whenever you need one.

cloudex save base                               # save the current sandbox as base
cloudex save web node-22                        # save the sandbox web as node-22
cloudex new --from base --name task-1           # a new sandbox from the save
cloudex new --from base --count 5 --name agent  # agent-1 to agent-5
cloudex saves                                   # list the saves
cloudex saves rm node-22                        # delete one

Making a save

cloudex save [sandbox] <name> saves a running sandbox, which keeps running. To save a stopped sandbox, resume it first.

Names follow the rules for sandbox names: lowercase letters, digits and dashes, 2 to 32 characters. Saving under a name that’s taken replaces that save once the new one has finished; until then, the old one keeps working.

In testing on standard-2, saving and restoring each took about 15 seconds per GB: a sandbox with 2 GB of new files saved in 26 seconds, and a new sandbox started from that save in 30.

What a save holds

The image lists its own files, so a save holds only what the sandbox changed:

  • Files you made or changed anywhere on the disk, and the image’s files you deleted.
  • Packages installed with apt, npm or pip, and Docker’s images, containers and volumes.
  • The sandbox’s settings: its environment variables and files. Sandboxes started from the save get a copy, which then changes separately.
  • Everything else stored in files, including agent logins and any keys you’ve saved on the disk. Keys stored with cloudex keys aren’t on the disk; sandboxes started from a save use them like any new sandbox.

A save leaves out:

  • The SSH host keys, so each new sandbox makes its own.
  • /tmp, /run and Cloudex’s own logs.
  • Running programs. Commands in ~/.cloudex/start run when a sandbox starts from the save, and Docker containers with a restart policy start again.

A file that’s being written while the save is made, such as a busy database, may be saved halfway through a write. Stop such programs first for an exact copy.

Starting sandboxes from a save

cloudex new --from <name> takes the same flags as a fork: --count, --name, --size, --idle and --no-use. The size and idle time default to those of the sandbox that was saved. With --on <node>, and --cpus and --memory if you like, the new sandboxes start on one of your nodes.

Each new sandbox starts from a fresh copy of the image, and the save is restored before anything in it runs, so services start with the restored files. cloudex info shows the save a sandbox started from.

If a sandbox and a save have the same name, --from picks the sandbox; --from save:<name> picks the save.

Saves and nodes

A sandbox on a node makes named saves as one on Cloudflare does. The save goes up to your R2 bucket over the node’s own line.

A save is how a sandbox moves between Cloudflare and a node, or between nodes. Start a sandbox from the save where you want it:

cloudex save n1 n1-copy                      # n1 runs on the node box
cloudex new --from n1-copy --name n1-cf      # the same files, on Cloudflare
cloudex new --from base --on box --name n2   # a Cloudflare save, on the node

The new sandbox has a new id and new preview links. Both sides run the same image, so the whole disk comes back, apart from a few device files that Docker in a Cloudflare sandbox keeps and a node can’t make; the notice counts them.

A save made on a node holds whatever that node put in it. cloudex saves shows the node each save was made on, in its ON column, and cloudex new --from says so when it starts one. Treat such a save like code from that node, especially before you start it on Cloudflare.

After an update

A save restores in full only onto the image it was made on. After cloudex deploy installs a newer image, a sandbox started from an older save gets only /home back: your files, anything installed in the home directory (pip install --user, ~/.local), agent logins and ~/.cloudex/start. Anything installed elsewhere, such as apt packages and Docker images, needs installing again, and the new sandbox’s notice says so. cloudex new prints it, and cloudex info shows it.

To bring a save onto the new image, start a sandbox from it, install what’s missing, and save that sandbox under the same name.

Sandboxes that run an image from before v0.1.15 make saves of /home only, because those images don’t list their files. An image of your own built FROM ghcr.io/lucataco/cloudex-base (see cloudex deploy --image) should end with RUN cloudex-files baseline, which writes that list, so that saves hold only what sandboxes change.

Deleting a save

cloudex saves rm <name> deletes a save for good. It asks first; -y or --yes skips the question, and is required when the command isn’t run in a terminal. Sandboxes already started from the save keep their disks.

A sandbox that started from a save, but stopped before it made a save of its own, starts from that save again when you resume it. If the save has been replaced since, it uses the newest save of that name, and if the save has been deleted, a fresh copy of the image. Its notice says which.

Storage

Saves are kept, compressed, in the R2 bucket cloudex-backups in your account. Like backups, they need R2 turned on; see Backups and R2. R2 charges for storage beyond its free tier, so delete the saves you no longer need. cloudex saves shows how much each one holds and how much it takes up.

From code

The SDKs make and use saves too:

import { Cloudex } from "cloudex";

const cx = new Cloudex();
await (await cx.get("setup")).save("base");
const boxes = await cx.startFromSave("base", { count: 3, name: "job" });
from cloudex import Cloudex

cx = Cloudex()
cx.get("setup").save("base")
boxes = cx.start_from_save("base", count=3, name="job")

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