Deutsch
Menü der Doku

Doku zu Agent Sandboxes · Aufgaben

Eine Sandbox forken, RAM und Prozesse eingeschlossen

Aktualisiert · 6 Min. Lesezeit

Ein Fork kopiert eine Sandbox, wie sie in diesem Moment ist, ihren RAM, ihre laufenden Prozesse und ihre Disk, in neue Sandboxes, die von dort aus weitermachen. Ein Agent probiert drei Fixes gleichzeitig aus demselben Zustand, ein Eval führt hundert Seeds aus einer vorbereiteten Umgebung aus, und die Kopien, die verlieren, werden gelöscht.

Kurz gesagt
  • ForkSandbox macht in einem Aufruf bis zu 100 Kopien, RUNNING auf dem Server der Quelle; drei dauern etwa 0,25 s.
  • Die Quelle macht weiter: Eine laufende pausiert für einige Millisekunden; eine pausierte bleibt pausiert; die Kopien einer gestoppten starten von ihrer Disk.
  • Jede Kopie hat eigene ID, eigenen Hostname, eigene machine-id und eigene Zufallszahlen des Kernels, die Größe der Quelle und keinen Namen.
  • Alle oder keine: Jede Kopie ist ein Start und zählt ihre vCPUs; passen nicht alle, entsteht keine.

Step 1: Sandbox forken

Gib den Kopien ein eigenes Label, damit du sie später zusammen findest. Ohne eins übernehmen sie die Labels der Quelle.

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: Jeder Kopie eigene Arbeit geben

Jede Kopie beantwortet ihre eigenen Aufrufe. Starte in jeder einen anderen Job, ohne darauf zu warten, und markier ihn mit keep_awake, damit keine Kopie mitten in ihrem Job pausiert.

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: Die behalten, die funktioniert hat, den Rest löschen

ListSandboxes mit dem Label des Laufs findet die Kopien; lösch die, die du nicht behältst. Eine Kopie, die du behältst, ist eine Sandbox wie jede andere: Gib ihr mit UpdateSandbox einen Namen.

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

Was eine Kopie hat

Eine Kopie ist die Quelle, wie sie beim Fork war: dieselben Dateien, derselbe RAM, dieselben Prozesse an derselben Instruktion. Ein Dev-Server liefert weiter aus, eine Python-Sitzung behält ihre Variablen, die Unterhaltung eines Coding-Agenten ist da, um weiterzumachen, in jeder Kopie. Die Kopien laufen auf dem Server der Quelle, in der Größe der Quelle und mit ihrer Disk. Die anderen Einstellungen sind die der Quelle, außer der Fork schickt eine eigene Gruppe (settings), etwa einen anderen Egress oder eine andere Umgebung; eine andere Größe wird abgelehnt.

Jede Kopie bekommt eine eigene ID, die auch ihr Hostname ist, eine eigene machine-id und frische Zufallszahlen des Kernels, also unterscheidet sich /dev/urandom ab dem ersten Lesen. Sie hat keinen Namen: Namen sind eindeutig, und UpdateSandbox gibt einer Kopie, die du behältst, einen.

Was Zufallszahlen erzeugt, neu setzen

Der Kernel wird in jeder Kopie neu gesetzt; der eigene Generator eines Prozesses nicht. Ein Zufallsgenerator, der vor dem Fork gesetzt wurde, random von Python, math/rand von Go, Math.random von V8, der von OpenSSL, liefert in jeder Kopie dieselben Zahlen, bis er neu gesetzt wird, und Schlüssel, die vor dem Fork erzeugt wurden, sind in jeder Kopie gleich. Setz die Seeds von Experimenten nach dem Fork, wie der Seed oben, und erzeug auch Schlüssel danach.

Die Quelle, und was ein Fork kostet

  • Eine RUNNING-Quelle pausiert für einige Millisekunden, während RAM und Disk übernommen werden, und läuft weiter.
  • Eine PAUSED-Quelle bleibt pausiert, und ihre Kopien starten aus ihrem gespeicherten RAM.
  • Eine STOPPED-Quelle hat keinen RAM: Die Kopien starten von ihrer Disk, als Boot.

Ein Fork gilt ganz oder gar nicht. Jede Kopie zählt ab ihrem Start ihre vCPUs gegen deinen Tarif, und jede ist ein Start gegen die Starts des Tarifs pro Minute, Stunde und Tag. Starts sind kostenlos: Eine Kopie kostet, was sie läuft, sekundengenau, wie jede Sandbox. Hat der Server der Quelle nicht für jede Kopie Platz, wird der Aufruf mit UNAVAILABLE und NoCapacity abgelehnt, dessen fork_count sagt, wie viele passen. Eine Sandbox mit einem Volume mit Schreibzugriff lässt sich nicht forken, denn ein Volume schreibt immer nur eine Sandbox.

Wenn es nicht funktioniert

  • UNAVAILABLE mit NoCapacity: Der Server der Quelle hat nicht für alle Kopien Platz. Frag nach fork_count Kopien oder weniger, oder versuch es später noch einmal.
  • RESOURCE_EXHAUSTED mit LimitReached, vcpus: Die Kopien würden die vCPUs deines Tarifs überschreiten. Lösch Sandboxes, die du nicht mehr brauchst, oder forke weniger.
  • LimitReached mit einem starts_per_*-Limit: Die Kopien würden die Starts eines Zeitfensters überschreiten; retry_time sagt, wann sie passen. Ein Fork mit mehr Kopien als das Limit selbst hat keine retry_time: Teil ihn auf.
  • FAILED_PRECONDITION: Die Sandbox mountet ein Volume mit Schreibzugriff. Forke eine, die es nur lesend mountet, oder gar nicht.
  • Jede Kopie gibt dieselben Zufallszahlen aus: Der Generator wurde vor dem Fork gesetzt. Setz ihn in jeder Kopie neu.

Fragen

Wie klone ich eine laufende Sandbox?

ForkSandbox mit count: Jede Kopie hat RAM, Prozesse und Disk der Quelle und läuft von dort weiter, wo die Quelle war.

Wie viele Kopien kann ein Fork machen?

Bis zu 100, alle oder keine, innerhalb der vCPUs und Starts deines Tarifs.

Stoppt das Forken die ursprüngliche Sandbox?

Nein. Eine laufende Quelle pausiert für einige Millisekunden und läuft weiter.

Wird das Forken abgerechnet?

Starts sind kostenlos. Jede Kopie wird sekundengenau für ihren Zustand abgerechnet, wie jede Sandbox.

Was ist der Unterschied zwischen einem Fork und einer Vorlage?

Ein Fork kopiert eine Sandbox jetzt, mit RAM und Prozessen, auf ihrem Server. Eine Vorlage behält die Dateien einer Sandbox für neue Sandboxes auf jedem Server, ohne RAM und Prozesse.

Pethost Agent Sandboxes ausprobieren

Eine Testphase von 7 Tagen mit 1 $ Verbrauch und 4 vCPUs, mit Karte. Danach ein Tarif ab 20 $ im Monat, der genauso viel Verbrauch enthält.

Testphase starten