Español
Menú de la documentación

Documentación de Agent Sandboxes · Tareas

Haz un fork de un sandbox, memoria y procesos incluidos

Actualizado · 6 min de lectura

Un fork copia un sandbox tal como está en este momento, su memoria, sus procesos en ejecución y su disco, en sandboxes nuevos que siguen desde ahí. Un agente prueba tres arreglos a la vez desde el mismo estado, una eval ejecuta cien semillas desde un mismo entorno ya preparado, y las copias que pierden se eliminan.

En resumen
  • ForkSandbox hace hasta 100 copias en una llamada, RUNNING en el servidor del original; tres tardan unos 0,25 s.
  • El original sigue: uno en ejecución se pausa unos milisegundos; uno en pausa sigue en pausa; las copias de uno detenido parten de su disco.
  • Cada copia tiene su propio id, hostname, machine-id y aleatoriedad del kernel, el tamaño del original, y ningún nombre.
  • Todas o ninguna: cada copia es un inicio y cuenta sus vCPU; cuando no caben todas, no se crea ninguna.

Step 1: Haz el fork del sandbox

Dale a las copias una etiqueta propia, para encontrarlas juntas más tarde. Sin ella, toman las etiquetas del original.

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: Dale a cada copia su propio trabajo

Cada copia responde a sus propias llamadas. Inicia un trabajo distinto en cada una, sin esperarlo, y márcalo con keep_awake para que ninguna copia se pause a mitad de su trabajo.

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: Quédate con la que funcionó, elimina el resto

ListSandboxes con la etiqueta de la ejecución encuentra las copias; elimina las que no te quedes. Una copia que te quedas es un sandbox como cualquier otro: dale un nombre con 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

Qué tiene una copia

Una copia es el original tal como estaba en el fork: los mismos archivos, la misma memoria, los mismos procesos en la misma instrucción. Un servidor de desarrollo sigue sirviendo, una sesión de Python conserva sus variables, la conversación de un agente de programación está ahí para seguirla, en cada copia. Las copias se ejecutan en el servidor del original, con el tamaño del original y con su disco. Sus demás ajustes son los del original salvo que el fork envíe un grupo propio (settings), como otra salida u otro entorno; un tamaño distinto se rechaza.

Cada copia recibe su propio id, que también es su hostname, su propio machine-id y aleatoriedad del kernel nueva, así que /dev/urandom difiere desde la primera lectura. No tiene nombre: los nombres son únicos, y UpdateSandbox le da uno a una copia que te quedas.

Vuelve a sembrar lo que genera números aleatorios

El kernel vuelve a sembrarse en cada copia; el generador propio de un proceso, no. Un generador aleatorio sembrado antes del fork, random de Python, math/rand de Go, Math.random de V8 o el de OpenSSL, da los mismos números en cada copia hasta que se vuelve a sembrar, y las claves creadas antes del fork son las mismas en cada copia. Siembra los experimentos después del fork, como hace la semilla de arriba, y crea también las claves después.

El original, y cuánto cuesta un fork

  • Un original RUNNING se pausa unos milisegundos mientras se toman su memoria y su disco, y sigue.
  • Un original PAUSED sigue en pausa, y sus copias parten de su memoria guardada.
  • Un original STOPPED no tiene memoria: sus copias parten de su disco, como un arranque.

Un fork es todo o nada. Cada copia cuenta sus vCPU para tu plan desde su inicio, y cada una es un inicio que cuenta para los inicios por minuto, hora y día del plan. Los inicios son gratis: una copia cuesta lo que se ejecuta, por segundo, como cualquier sandbox. Cuando el servidor del original no tiene espacio para todas las copias, la llamada se rechaza con UNAVAILABLE y NoCapacity, cuyo fork_count dice cuántas caben. No se puede hacer un fork de un sandbox con un volumen de lectura y escritura, ya que un volumen lo escribe un sandbox cada vez.

Cuando no funciona

  • UNAVAILABLE con NoCapacity: el servidor del original no tiene espacio para todas las copias. Pide fork_count copias o menos, o vuelve a intentarlo más tarde.
  • RESOURCE_EXHAUSTED con LimitReached, vcpus: las copias superarían las vCPU de tu plan. Elimina sandboxes que ya no necesites, o haz menos copias.
  • LimitReached con un límite starts_per_*: las copias superarían los inicios de una ventana; retry_time dice cuándo caben. Un fork de más copias que el propio límite no tiene retry_time: divídelo.
  • FAILED_PRECONDITION: el sandbox monta un volumen de lectura y escritura. Haz el fork de uno que lo monte de solo lectura, o de uno sin volumen.
  • Todas las copias imprimen los mismos números aleatorios: el generador se sembró antes del fork. Vuelve a sembrarlo en cada copia.

Preguntas

¿Cómo clono un sandbox en ejecución?

ForkSandbox con count: cada copia tiene la memoria, los procesos y el disco del original, y sigue desde donde estaba el original.

¿Cuántas copias puede hacer un fork?

Hasta 100, todas o ninguna, dentro de las vCPU y los inicios de tu plan.

¿Hacer un fork detiene el sandbox original?

No. Un original en ejecución se pausa unos milisegundos y sigue.

¿Se factura hacer un fork?

Los inicios son gratis. Cada copia se factura por segundo según su estado, como cualquier sandbox.

¿Qué diferencia hay entre un fork y una plantilla?

Un fork copia un sandbox ahora, con memoria y procesos, en su servidor. Una plantilla conserva los archivos de un sandbox para sandboxes nuevos en cualquier servidor, sin memoria ni procesos.

Prueba Pethost Agent Sandboxes

Una prueba gratis de 7 días con 1 US$ de uso y 4 vCPU, con tarjeta. Después, un plan desde 20 US$ al mes, que incluye ese mismo importe en uso.

Empezar la prueba gratis