English
Docs menu

Agent Sandboxes docs · Tasks

Fork a sandbox, memory and processes included

Updated · 6 min read

A fork copies a sandbox as it is this moment, its memory, its running processes and its disk, into new sandboxes that go on from there. An agent tries three fixes at once from the same state, an eval runs a hundred seeds from one warmed-up environment, and the copies that lose are deleted.

In short
  • ForkSandbox makes up to 100 copies in one call, RUNNING on the source's server; three take about 0.25 s.
  • The source goes on: a running one pauses for some milliseconds; a paused one stays paused; a stopped one's copies start from its disk.
  • Each copy has its own id, hostname, machine-id and kernel randomness, the source's size, and no name.
  • All or none: each copy is a start and counts its vCPUs; when not all fit, none is made.

Step 1: Fork the sandbox

Give the copies a label of their own, so you can find them together later. Without one they take the source's labels.

Python
from pethost.sandboxes import Label

run = Label(key="run", value="seeds-7")
copies = sandboxes.fork_sandbox(sandbox_id, count=3, labels=[run]).sandboxes
print([copy.sandbox_id for copy in copies])
# ['kecrb56zb2sqfmy0', '9pd5esg1e2vguf1j', 'zawco1pzbjzgxjyy']
TypeScript
const run = { key: "run", value: "seeds-7" };
const { sandboxes: copies } = await sandboxes.forkSandbox({ sandboxId, count: 3, labels: [run] });
console.log(copies.map((copy) => copy.sandboxId));
Go
run := sandboxes.Label{Key: "run", Value: "seeds-7"}
forked, err := client.ForkSandbox(ctx, &sandboxes.ForkSandboxRequest{SandboxID: id, Count: 3, Labels: []sandboxes.Label{run}})
if err != nil {
	log.Fatal(err)
}
for _, copy := range forked.Sandboxes {
	fmt.Println(copy.SandboxID)
}
Rust
let run = Label { key: "run".into(), value: "seeds-7".into() };
let copies = sandboxes
    .fork_sandbox(ForkSandboxRequest {
        sandbox_id: id.clone(),
        count: 3,
        labels: vec![run.clone()],
        ..Default::default()
    })
    .await?
    .sandboxes;
for copy in &copies {
    println!("{}", copy.sandbox_id);
}
CLI
$ pethost sandbox fork api-dev --count 3 --label run=seeds-7
✓ Forked api-dev into 3 sandboxes in 1 s
us8wjivt4ndyu3mn
7sfjrgzwk72v3ie4
955mpq7p89sfaezv
MCP
ForkSandbox {"sandbox_id": "…", "count": 3, "labels": [{"key": "run", "value": "seeds-7"}]}

Step 2: Give each copy its own work

Each copy answers its own calls. Start a different job in each, without waiting for it, and mark it keep_awake so no copy pauses under its job.

Python
for seed, copy in enumerate(copies):
    sandboxes.run_command(
        copy.sandbox_id,
        command=f"python3 experiment.py --seed {seed} > result.txt",
        wait_seconds=0,
        keep_awake=True,
    )
TypeScript
await Promise.all(
  copies.map((copy, seed) =>
    sandboxes.runCommand({
      sandboxId: copy.sandboxId,
      command: `python3 experiment.py --seed ${seed} > result.txt`,
      waitSeconds: 0,
      keepAwake: true,
    }),
  ),
);
Go
for seed, copy := range forked.Sandboxes {
	_, err := client.RunCommand(ctx, &sandboxes.RunCommandRequest{
		SandboxID:   copy.SandboxID,
		Command:     fmt.Sprintf("python3 experiment.py --seed %d > result.txt", seed),
		WaitSeconds: new(uint32(0)),
		KeepAwake:   true,
	})
	if err != nil {
		log.Fatal(err)
	}
}
Rust
for (seed, copy) in copies.iter().enumerate() {
    sandboxes
        .run_command(RunCommandRequest {
            sandbox_id: copy.sandbox_id.clone(),
            command: format!("python3 experiment.py --seed {seed} > result.txt"),
            wait_seconds: Some(0),
            keep_awake: true,
            ..Default::default()
        })
        .await?;
}

Step 3: Keep the one that worked, delete the rest

ListSandboxes with the run's label finds the copies; delete those you do not keep. A copy you keep is a sandbox like any other: give it a name with UpdateSandbox.

Python
best = copies[0].sandbox_id  # the copy whose result you keep
for copy in sandboxes.list_sandboxes(labels=[run]).sandboxes:
    if copy.sandbox_id != best:
        sandboxes.delete_sandbox(copy.sandbox_id)
TypeScript
const best = copies[0]!.sandboxId; // the copy whose result you keep
const { sandboxes: found } = await sandboxes.listSandboxes({ labels: [run] });
for (const copy of found) {
  if (copy.sandboxId !== best) await sandboxes.deleteSandbox({ sandboxId: copy.sandboxId });
}
Go
best := forked.Sandboxes[0].SandboxID // the copy whose result you keep
found, err := client.ListSandboxes(ctx, &sandboxes.ListSandboxesRequest{Labels: []sandboxes.Label{run}})
if err != nil {
	log.Fatal(err)
}
for _, copy := range found.Sandboxes {
	if copy.SandboxID != best {
		if _, err := client.DeleteSandbox(ctx, &sandboxes.DeleteSandboxRequest{SandboxID: copy.SandboxID}); err != nil {
			log.Fatal(err)
		}
	}
}
Rust
let best = copies[0].sandbox_id.clone(); // the copy whose result you keep
let found = sandboxes
    .list_sandboxes(ListSandboxesRequest { labels: vec![run], ..Default::default() })
    .await?;
for copy in found.sandboxes.iter().filter(|copy| copy.sandbox_id != best) {
    let gone = DeleteSandboxRequest { sandbox_id: copy.sandbox_id.clone(), ..Default::default() };
    sandboxes.delete_sandbox(gone).await?;
}
CLI
$ pethost sandbox ls --label run=seeds-7
ID                 NAME   STATE     SIZE      TEMPLATE   CREATED    LABELS
us8wjivt4ndyu3mn          running   default   base@17    20 s ago   run=seeds-7
955mpq7p89sfaezv          running   default   base@17    20 s ago   run=seeds-7
7sfjrgzwk72v3ie4          running   default   base@17    20 s ago   run=seeds-7
$ pethost sandbox rm us8wjivt4ndyu3mn 7sfjrgzwk72v3ie4 --yes
us8wjivt4ndyu3mn   deleted
7sfjrgzwk72v3ie4   deleted

What a copy has

A copy is the source as it was at the fork: the same files, the same memory, the same processes at the same instruction. A dev server keeps serving, a Python session keeps its variables, a coding agent's conversation is there to go on from, in every copy. The copies run on the source's server, at the source's size and with its disk. Their other settings are the source's unless the fork sends a group of its own (settings), as a different egress or environment; a different size is refused.

Each copy gets its own id, which is also its hostname, its own machine-id and fresh kernel randomness, so /dev/urandom differs from the first read. It has no name: names are unique, and UpdateSandbox gives one to a copy you keep.

Reseed what generates random numbers

The kernel is reseeded in each copy; a process's own generator is not. A random generator seeded before the fork, Python's random, Go's math/rand, V8's Math.random, OpenSSL's, gives the same numbers in every copy until it is seeded again, and keys made before the fork are the same in every copy. Seed experiments after the fork, as the seed above does, and make keys after it too.

The source, and what a fork costs

  • A RUNNING source pauses for some milliseconds while its memory and disk are taken, and goes on.
  • A PAUSED source stays paused, and its copies start from its saved memory.
  • A STOPPED source has no memory: its copies start from its disk, as a boot.

A fork is all or none. Each copy counts its vCPUs against your plan from its start, and each is a start against the plan's starts per minute, hour and day. Starts are free: a copy costs what it runs, by the second, as any sandbox does. When the source's server has no room for every copy, the call is refused with UNAVAILABLE and NoCapacity, whose fork_count says how many fit. A sandbox with a read-write volume cannot be forked, since a volume is written by one sandbox at a time.

When it does not work

  • UNAVAILABLE with NoCapacity: the source's server has no room for all the copies. Ask for fork_count copies or fewer, or try again later.
  • RESOURCE_EXHAUSTED with LimitReached, vcpus: the copies would pass your plan's vCPUs. Delete sandboxes you no longer need, or fork fewer.
  • LimitReached with a starts_per_* limit: the copies would pass a window's starts; retry_time says when they fit. A fork of more copies than the limit itself has no retry_time: split it.
  • FAILED_PRECONDITION: the sandbox mounts a volume read-write. Fork one that mounts it read-only, or none.
  • Every copy prints the same random numbers: the generator was seeded before the fork. Seed it again in each copy.

Questions

How do I clone a running sandbox?

ForkSandbox with count: each copy has the source's memory, processes and disk, and runs on from where the source was.

How many copies can one fork make?

Up to 100, all or none, within your plan's vCPUs and starts.

Does forking stop the original sandbox?

No. A running source pauses for some milliseconds and goes on.

Is forking billed?

Starts are free. Each copy is billed by the second for its state, as any sandbox.

What is the difference between a fork and a template?

A fork copies a sandbox now, with memory and processes, on its server. A template keeps a sandbox's files for new sandboxes on any server, without memory or processes.

Try Pethost Agent Sandboxes

A 7-day trial with $1 of usage and 4 vCPUs, with a card. Then a plan from $20 a month, which includes as much usage.

Start the trial