---
title: "Fork a sandbox, memory and processes included | Pethost Agent Sandboxes"
description: "Copy a running sandbox, with its memory, processes and disk, into up to 100 sandboxes in one call, to try several things from the same point at once."
---

[Agent Sandboxes docs](https://pethost.dev/docs/sandboxes/) · Tasks

# Fork a sandbox, memory and processes included

Updated 22 November 2026 · 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.

[PreviousSecrets and egress: keys a sandbox never holds](https://pethost.dev/docs/sandboxes/secrets-and-egress/) [NextVolumes: a disk that outlives sandboxes](https://pethost.dev/docs/sandboxes/volumes/)

## 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](https://console.pethost.dev/)

Pethost · Stephan Gomer · NIP 1133096755

Pethost

- [Templates](https://pethost.dev/templates/)
- [About](https://pethost.dev/about/)
- [Docs](https://pethost.dev/docs/)
- [Blog](https://pethost.dev/blog/)
- [API](https://pethost.dev/docs/api/)
- [CLI](https://pethost.dev/docs/cli/)
- [Plugin](https://github.com/pethost-dev/plugin)
- [Terms](https://pethost.dev/terms/)
- [Privacy](https://pethost.dev/privacy/)
- [Refunds](https://pethost.dev/refunds/)
- [support@pethost.dev](mailto:support@pethost.dev)

Databases

- [Postgres](https://pethost.dev/postgres/)
- [Valkey](https://pethost.dev/valkey/)

Agent Sandboxes

- [Sandboxes](https://pethost.dev/sandboxes/)
- [Pricing](https://pethost.dev/sandboxes/#pricing)
- [Docs](https://pethost.dev/docs/sandboxes/)
- [API](https://pethost.dev/docs/sandboxes/api/)

Comparisons

- [Coolify vs Dokploy vs CapRover vs Dokku](https://pethost.dev/blog/coolify-vs-dokploy-vs-caprover-vs-dokku/)
- [Coolify Cloud vs Dokploy Cloud](https://pethost.dev/blog/coolify-cloud-vs-dokploy-cloud/)
- [Railway vs Render vs Fly.io pricing](https://pethost.dev/blog/railway-vs-render-vs-fly-io-pricing/)
- [Managed Docker Compose hosting](https://pethost.dev/blog/managed-docker-compose-hosting/)

Alternatives

- [Railway alternatives](https://pethost.dev/blog/railway-alternatives/)
- [Heroku alternatives](https://pethost.dev/blog/heroku-alternatives/)
- [Dokploy alternatives](https://pethost.dev/blog/dokploy-alternatives/)
- [Coolify alternatives](https://pethost.dev/blog/coolify-alternatives/)
- [Render alternatives](https://pethost.dev/blog/render-alternatives/)
- [Sliplane alternatives](https://pethost.dev/blog/sliplane-alternatives/)
