Sandboxes

A sandbox is a container with a workspace directory mounted into it. It is identified by a name you choose, and that name is how you find it again — across calls, and across process restarts.

const sandboxes = new Sandboxes({ root: "/var/tmp/sandboxes" });
const box = await sandboxes.create("workspace-42", { memory: MiB(512) });

Reuse is meet-or-exceed, not equality

Calling create() for a name that already exists returns the existing sandbox when its shape still serves the request, starting it first if it had stopped. The rule is meet-or-exceed, and the distinction is load-bearing. Under equality, a build asking for 2 GiB and a small command asking for 256 MiB never share a sandbox, so each one replaces the other’s and destroys whatever it had installed. That turns every dependency install cold. A bigger sandbox runs a smaller command perfectly well; the reverse is not true, so a raised budget still takes effect.

const big = await sandboxes.create("w", { memory: GiB(2) });
const small = await sandboxes.create("w", { memory: MiB(256) });
small.id === big.id;            // true — the big one serves

const bigger = await sandboxes.create("w", { memory: GiB(4) });
bigger.id === big.id;           // false — rebuilt, because 2 GiB will not do

The image is an exception, because it is an identity rather than a quantity: a Python command can never land in a Node sandbox, and no amount of spare memory makes it able to.

A rebuild keeps the workspace

When a sandbox no longer serves — a different image, more room, a tighter ceiling — the container is rebuilt and the workspace stays. A job that moves between images keeps what it installed:

const site = await sandboxes.create("w", { runtime: "node-python" });
await site.exec("npm install");
const check = await sandboxes.create("w", { runtime: "browser", memory: GiB(1) });
// a new container over the same workspace — node_modules is still there

Installed packages with native parts are built for the image that installed them. browser is Debian (glibc) and the others are Alpine (musl), so run installs and builds in the image that will use them, and give the browser step what is already built.

Ceilings run the other way

Capacities meet-or-exceed. Ceilings meet-or-undercut. A sandbox entitled to live for an hour is not handed to a caller who just asked for a minute, so it is rebuilt. The reverse is fine: one that stops sooner than asked is harmless, because the next create() starts it again.

await sandboxes.create("w", { maxLifetimeMs: 60 * 60 * 1000 });
await sandboxes.create("w", { maxLifetimeMs: 60_000 });   // rebuilt

Reuse also refuses a sandbox already older than the requested ceiling. Being entitled to live long enough is not the same as having done so — a sweep may not have run yet, and handing back a sandbox past its ceiling would break it on arrival.

Forcing a fresh one

When the workspace itself is suspect, replace skips reuse entirely:

const box = await sandboxes.create("w", { replace: true });

It removes the container and its workspace, then builds clean. replace is an action, not a property. It is never recorded on the sandbox and never influences whether a later create() reuses it — otherwise every subsequent call would keep replacing. You should rarely need it: a sandbox whose shape no longer serves is already rebuilt without it.

Finding what exists

const all = await sandboxes.list();
// [{ name, id, state, image, createdAt, idleTimeoutMs, maxLifetimeMs, stopGraceMs }]

list() is scoped by label to the sandboxes this runtime created, so a sweep can never touch a container it does not own. Set prefix on the constructor to separate one fleet from another on a shared host:

new Sandboxes({ prefix: "ci" });      // containers named ci-<name>

Removing

await box.stop();                  // keeps the container and the workspace
await sandboxes.remove("w");       // removes the container AND the workspace
await sandboxes.removeAll();       // every sandbox this runtime owns

stop() is the reversible one: the next create() starts the same container again, with everything the last command installed still in place. remove() is not reversible — it deletes the workspace directory. Removing something that is already gone is not an error; remove() returns whether there was anything there.

Getting started

Images

CLI

Guides

Operations

Reuse is meet-or-exceed, not equality

A rebuild keeps the workspace

Ceilings run the other way

Forcing a fresh one

Finding what exists

Removing

​Reuse is meet-or-exceed, not equality

​A rebuild keeps the workspace

​Ceilings run the other way

​Forcing a fresh one

​Finding what exists

​Removing

Reuse is meet-or-exceed, not equality

A rebuild keeps the workspace

Ceilings run the other way

Forcing a fresh one

Finding what exists

Removing