---
title: "Faça fork de um sandbox, com memória e processos | Pethost Agent Sandboxes"
description: "Copie um sandbox rodando, com memória, processos e disco, para até 100 sandboxes em uma chamada, e tente várias coisas a partir do mesmo ponto ao mesmo tempo."
---

[Docs do Agent Sandboxes](https://pethost.dev/pt/docs/sandboxes/) · Tarefas

# Faça fork de um sandbox, com memória e processos

Atualizado em 22 de novembro de 2026 · 6 min de leitura

Um fork copia um sandbox como ele está neste momento, a memória, os processos rodando e o disco, para novos sandboxes que continuam dali. Um agente tenta três correções ao mesmo tempo a partir do mesmo estado, um eval roda cem sementes a partir de um ambiente já aquecido, e as cópias que perdem são excluídas.

**Em resumo**

- **`ForkSandbox`** cria até 100 cópias em uma chamada, RUNNING no servidor da origem; três levam cerca de 0,25 s.
- **A origem continua:** uma que roda pausa por alguns milissegundos; uma pausada continua pausada; as cópias de uma parada iniciam do disco dela.
- **Cada cópia** tem id, hostname, machine-id e aleatoriedade do kernel próprios, o tamanho da origem e nenhum nome.
- **Tudo ou nada:** cada cópia é um início e conta as vCPUs dela; quando nem todas cabem, nenhuma é criada.

### Step 1: Faça fork do sandbox

Dê às cópias um rótulo próprio, para poder encontrá-las juntas depois. Sem ele, elas levam os rótulos da origem.

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: Dê a cada cópia um trabalho próprio

Cada cópia responde às próprias chamadas. Inicie um job diferente em cada uma, sem esperar por ele, e marque-o com `keep_awake` para que nenhuma cópia pause no meio do 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: Fique com a que funcionou e exclua o resto

`ListSandboxes` com o rótulo da execução encontra as cópias; exclua as que você não vai manter. Uma cópia que você mantém é um sandbox como qualquer outro: dê um nome a ela com `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
```

## O que uma cópia tem

Uma cópia é a origem como ela estava no fork: os mesmos arquivos, a mesma memória, os mesmos processos na mesma instrução. Um servidor de desenvolvimento continua servindo, uma sessão Python mantém as variáveis, a conversa de um agente de código está lá para continuar, em cada cópia. As cópias rodam no servidor da origem, no tamanho da origem e com o disco dela. As outras configurações são as da origem, a não ser que o fork envie um grupo próprio (`settings`), como uma saída ou um ambiente diferente; um tamanho diferente é recusado.

Cada cópia recebe um id próprio, que também é o hostname dela, um machine-id próprio e aleatoriedade nova do kernel, então `/dev/urandom` difere desde a primeira leitura. Ela não tem nome: nomes são únicos, e `UpdateSandbox` dá um à cópia que você mantém.

## Gere novas sementes para o que produz números aleatórios

O kernel recebe uma nova semente em cada cópia; o gerador próprio de um processo não. Um gerador aleatório que recebeu semente antes do fork, o `random` do Python, o `math/rand` do Go, o `Math.random` do V8, o do OpenSSL, dá os mesmos números em todas as cópias até receber uma nova semente, e chaves criadas antes do fork são as mesmas em todas as cópias. Defina as sementes dos experimentos depois do fork, como a semente acima faz, e crie chaves depois dele também.

## A origem, e quanto custa um fork

- **Uma origem RUNNING** pausa por alguns milissegundos enquanto a memória e o disco dela são copiados, e continua.
- **Uma origem PAUSED** continua pausada, e as cópias dela iniciam da memória salva.
- **Uma origem STOPPED** não tem memória: as cópias dela iniciam do disco, como em um boot.

Um fork é tudo ou nada. Cada cópia conta as vCPUs dela no seu plano desde o início, e cada uma é um início nos inícios por minuto, hora e dia do plano. Inícios são grátis: uma cópia custa o que roda, por segundo, como qualquer sandbox. Quando o servidor da origem não tem espaço para todas as cópias, a chamada é recusada com `UNAVAILABLE` e `NoCapacity`, cujo `fork_count` diz quantas cabem. Um sandbox com um volume de leitura e escrita não pode ter fork, já que um volume é gravado por um sandbox de cada vez.

## Quando não funciona

- **`UNAVAILABLE` com `NoCapacity`:** o servidor da origem não tem espaço para todas as cópias. Peça `fork_count` cópias ou menos, ou tente de novo mais tarde.
- **`RESOURCE_EXHAUSTED` com `LimitReached`, `vcpus`:** as cópias passariam das vCPUs do seu plano. Exclua sandboxes de que não precisa mais, ou faça menos cópias.
- **`LimitReached` com um limite `starts_per_*`:** as cópias passariam dos inícios de uma janela; `retry_time` diz quando elas cabem. Um fork com mais cópias do que o próprio limite não tem `retry_time`: divida-o.
- **`FAILED_PRECONDITION`:** o sandbox monta um volume em leitura e escrita. Faça fork de um que o monte só para leitura, ou de um sem volume.
- **Todas as cópias imprimem os mesmos números aleatórios:** o gerador recebeu a semente antes do fork. Gere uma nova semente em cada cópia.

## Perguntas

### Como clono um sandbox rodando?

`ForkSandbox` com `count`: cada cópia tem a memória, os processos e o disco da origem, e continua rodando de onde a origem estava.

### Quantas cópias um fork pode criar?

Até 100, tudo ou nada, dentro das vCPUs e dos inícios do seu plano.

### Um fork interrompe o sandbox original?

Não. Uma origem que roda pausa por alguns milissegundos e continua.

### O fork é cobrado?

Inícios são grátis. Cada cópia é cobrada por segundo pelo estado dela, como qualquer sandbox.

### Qual a diferença entre um fork e um template?

Um fork copia um sandbox agora, com memória e processos, no servidor dele. Um template guarda os arquivos de um sandbox para novos sandboxes em qualquer servidor, sem memória nem processos.

[AnteriorSegredos e saída: chaves que um sandbox nunca guarda](https://pethost.dev/pt/docs/sandboxes/secrets-and-egress/) [PróximaVolumes: um disco que sobrevive aos sandboxes](https://pethost.dev/pt/docs/sandboxes/volumes/)

## Experimente o Pethost Agent Sandboxes

Um teste grátis de 7 dias com US$ 1 de uso e 4 vCPUs; é preciso um cartão. Depois, um plano a partir de US$ 20 por mês, que inclui esse mesmo valor em uso.

[Começar o teste grátis](https://console.pethost.dev/)

Pethost · Stephan Gomer · NIP 1133096755

Pethost

- [Templates](https://pethost.dev/pt/templates/)
- [Sobre nós](https://pethost.dev/about/)
- [Docs](https://pethost.dev/docs/)
- [Blog](https://pethost.dev/pt/blog/)
- [API](https://pethost.dev/docs/api/)
- [CLI](https://pethost.dev/docs/cli/)
- [Plugin](https://github.com/pethost-dev/plugin)
- [Termos](https://pethost.dev/terms/)
- [Privacidade](https://pethost.dev/privacy/)
- [Reembolsos](https://pethost.dev/refunds/)
- [support@pethost.dev](mailto:support@pethost.dev)

Bancos de dados

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

Agent Sandboxes

- [Sandboxes](https://pethost.dev/pt/sandboxes/)
- [Preços](https://pethost.dev/pt/sandboxes/#pricing)
- [Docs](https://pethost.dev/pt/docs/sandboxes/)
- [API](https://pethost.dev/docs/sandboxes/api/)

Comparativos

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

Alternativas

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