How to fork a running sandbox into parallel copies

Call sbx.fork({ count }) for up to 10 running copies with the source's files, memory and processes, all answered in one call.

On Runtime a fork copies a live machine, not just its disk: a server that was running in the source is still running in every copy. The snapshot the fork takes for itself is deleted when the fork ends and is never billed, so three waiting 2 vCPU, 4 GiB copies cost 3 × $0.03125, about $0.094 an hour, and nothing more (rates checked 25 September 2026, pricing). Copies run on the source's server.

Fork a machine with a server running

Start the work once, fork, and each copy carries on from that moment:

TypeScriptimport { Sandbox } from "withruntime";await using base = await Sandbox.create();await base.exec("pip install --quiet requests", { timeoutMs: 120_000 });await base.spawn("python3 -m http.server 8000", { cwd: "/workspace" });const copies = await base.fork({ count: 3, labels: { experiment: "retry-policy" } });for (const copy of copies) {  const probe = await copy.exec("curl -s -o /dev/null -w '%{http_code}' localhost:8000");  console.log(copy.id, probe.stdout); // 200: the server came along}await Promise.all(copies.map((copy) => copy.stop()));

Pythonfrom withruntime import Sandboxwith Sandbox.create() as base:    base.exec("pip install --quiet requests", timeout_ms=120_000)    base.spawn("python3 -m http.server 8000", cwd="/workspace")    copies = base.fork(count=3, labels={"experiment": "retry-policy"})    for copy in copies:        probe = copy.exec("curl -s -o /dev/null -w '%{http_code}' localhost:8000")        print(copy.id, probe.stdout)    for copy in copies:        copy.stop()

Terminalruntime sandbox fork "${id}" --count 3runtime sandbox fork "${id}" --count 3 --paid --keep-snapshot

With count, fork returns a list; without it, one sandbox. The source is paused for the moment the fork takes, about a second for a fresh sandbox and longer the more memory it holds, then woken. A paused source stays paused.

Options

Each copy gets the source's vCPUs, memory, disk and CPU setting (reserved CPU, or a raised floor), and is billed as a create of that size would be.

When a copy fails

A fork that fails after its snapshot answers with the failing step's error. The copies that did start are in details.startedSandboxIds, and they keep running, and billing, until you stop them.

TypeScriptimport { RuntimeError, Sandbox } from "withruntime";const base = await Sandbox.create();try {  const copies = await base.fork({ count: 5 });  console.log(copies.map((copy) => copy.id));} catch (error) {  if (!(error instanceof RuntimeError)) throw error;  const started = (error.details?.startedSandboxIds ?? []) as string[];  for (const id of started) await (await Sandbox.connect(id)).stop();  console.log(error.code, error.hint);}

A failed fork is over. The same idempotency key answers the same error, so fork again with a new key (idempotency keys).

Limits and refusals

A paid account runs 100 sandboxes at once to start, so ten copies of several sources fit comfortably (how many at once).

Where forking pays off

• Trying several fixes. A coding agent reaches a failing test with the repo built and the dev server up, then forks one copy per candidate fix (coding agent sandbox).
• Sampling answers. Run the same prepared environment against several model outputs and keep the best (RL environments).
• Evaluation episodes. Every episode starts from exactly the same memory and process state (agent evals).

Mistakes to avoid

• Forgetting the copies. Each copy is a sandbox with its own lease, billed until it stops or pauses. Stop each one when its attempt is done, even after an error.
• Forking for later. Copies start now. To start copies next week, take a snapshot, or pass keepSnapshot: true.
• Retrying a trial fork that asks for too many. More copies than the trial's eight at once never fit, however long you wait. Ask for fewer, or pass funding: "paid".

The idea behind forks is explained in what is a sandbox fork?.

Facts on this page were checked on 25 September 2026.