Deutsch
Menü der Doku

Doku zu Agent Sandboxes · Aufgaben

Volumes: eine Disk, die Sandboxes überdauert

Aktualisiert · 6 Min. Lesezeit

Ein Volume ist eine Disk außerhalb jeder Sandbox, an einem Pfad in eine gemountet: ein Datensatz, den viele Sandboxes lesen, ein Cache, der jeden Job überdauert, Dateien, die eine Sandbox, die du löschst, zurücklassen soll. Es liegt auf der Disk eines Servers, und genau das solltest du wissen, bevor du etwas darauf legst.

Kurz gesagt
  • CreateVolume erstellt eins mit 1 bis 1.000 GiB; CreateSandbox mountet beim Erstellen bis zu 4, jedes an einem Pfad.
  • Schreibend von einer Sandbox auf einmal, lesend von beliebig vielen.
  • Auf einem Server, nicht kopiert: Eine Sandbox, die es mountet, läuft dort, und geht dieser Server verloren, ist das Volume auch weg.
  • Nach seiner ganzen Größe abgerechnet, 0,20 $ pro GiB und Monat, genutzt oder nicht.

Step 1: Volume erstellen

Ein Volume wird leer erstellt, auf einem Server mit Platz, und sein Wurzelverzeichnis gehört user.

Python
volume = sandboxes.create_volume("data", size_gib=10)
print(volume.volume_id, volume.size_gib)  # ziwv1r8ean3dd9sk 10
TypeScript
const volume = await sandboxes.createVolume({ name: "data", sizeGib: 10 });
console.log(volume.volumeId, volume.sizeGib);
Go
volume, err := client.CreateVolume(ctx, &sandboxes.CreateVolumeRequest{Name: "data", SizeGib: 10})
if err != nil {
	log.Fatal(err)
}
fmt.Println(volume.VolumeID, volume.SizeGib)
Rust
let volume = sandboxes
    .create_volume(CreateVolumeRequest { name: "data".into(), size_gib: 10, ..Default::default() })
    .await?;
println!("{} {}", volume.volume_id, volume.size_gib);
CLI
$ pethost sandbox volume new data --size 10
✓ Made the volume data, 10 GiB. Mount it:  pethost sandbox new --mount o2rvhgm1dxaefoj7:/data
o2rvhgm1dxaefoj7

Step 2: In eine Sandbox mounten

Mounts werden beim Erstellen angegeben, jeder ein Volume und ein absoluter Pfad. Die Sandbox läuft auf dem Server des Volumes.

Python
from pethost.sandboxes import Mount

writer = sandboxes.create_sandbox("base", mounts=[Mount(volume_id=volume.volume_id, path="/data")])
sandboxes.run_command(writer.sandbox_id, command="date > /data/first-run.txt")
TypeScript
const writer = await sandboxes.createSandbox({
  template: "base",
  mounts: [{ volumeId: volume.volumeId, path: "/data" }],
});
await sandboxes.runCommand({ sandboxId: writer.sandboxId, command: "date > /data/first-run.txt" });
Go
writer, err := client.CreateSandbox(ctx, &sandboxes.CreateSandboxRequest{
	Template: "base",
	Mounts:   []sandboxes.Mount{{VolumeID: volume.VolumeID, Path: "/data"}},
})
if err != nil {
	log.Fatal(err)
}
_, err = client.RunCommand(ctx, &sandboxes.RunCommandRequest{SandboxID: writer.SandboxID, Command: "date > /data/first-run.txt"})
Rust
let mount = Mount { volume_id: volume.volume_id.clone(), path: "/data".into(), ..Default::default() };
let writer = sandboxes
    .create_sandbox(CreateSandboxRequest { template: "base".into(), mounts: vec![mount], ..Default::default() })
    .await?;
sandboxes
    .run_command(RunCommandRequest {
        sandbox_id: writer.sandbox_id.clone(),
        command: "date > /data/first-run.txt".into(),
        ..Default::default()
    })
    .await?;
CLI
$ pethost sandbox new --name writer --mount o2rvhgm1dxaefoj7:/data
✓ Made sandbox writer (upc3ehxd65rjgz32): default, running, from base@17, in <1 s
upc3ehxd65rjgz32
Next:   pethost sandbox run upc3ehxd65rjgz32 -- <command>   ·   pethost sandbox shell upc3ehxd65rjgz32
$ pethost sandbox run writer -- 'date > /data/first-run.txt'
MCP
CreateSandbox {"name": "writer", "mounts": [{"volume_id": "…", "path": "/data"}]}

Step 3: Lesend teilen und am Ende löschen

Sobald keine Sandbox es schreibend mountet, dürfen es beliebig viele lesend mounten. Ein Volume bleibt, wenn die Sandboxes gelöscht werden, die es gemountet haben, und verschwindet nur durch DeleteVolume, das abgelehnt wird, solange eine Sandbox es mountet.

Python
sandboxes.delete_sandbox(writer.sandbox_id)
reader = sandboxes.create_sandbox("base", mounts=[Mount(volume_id=volume.volume_id, path="/data", read_only=True)])
print(sandboxes.run_command(reader.sandbox_id, command="cat /data/first-run.txt").stdout)  # Sun Nov 22 00:25:33 UTC 2026
sandboxes.delete_sandbox(reader.sandbox_id)
sandboxes.delete_volume(volume.volume_id)
TypeScript
await sandboxes.deleteSandbox({ sandboxId: writer.sandboxId });
const reader = await sandboxes.createSandbox({
  template: "base",
  mounts: [{ volumeId: volume.volumeId, path: "/data", readOnly: true }],
});
console.log((await sandboxes.runCommand({ sandboxId: reader.sandboxId, command: "cat /data/first-run.txt" })).stdout);
await sandboxes.deleteSandbox({ sandboxId: reader.sandboxId });
await sandboxes.deleteVolume({ volumeId: volume.volumeId });
Go
if _, err := client.DeleteSandbox(ctx, &sandboxes.DeleteSandboxRequest{SandboxID: writer.SandboxID}); err != nil {
	log.Fatal(err)
}
reader, err := client.CreateSandbox(ctx, &sandboxes.CreateSandboxRequest{
	Template: "base",
	Mounts:   []sandboxes.Mount{{VolumeID: volume.VolumeID, Path: "/data", ReadOnly: true}},
})
if err != nil {
	log.Fatal(err)
}
read, err := client.RunCommand(ctx, &sandboxes.RunCommandRequest{SandboxID: reader.SandboxID, Command: "cat /data/first-run.txt"})
if err != nil {
	log.Fatal(err)
}
fmt.Print(read.Stdout)
_, err = client.DeleteSandbox(ctx, &sandboxes.DeleteSandboxRequest{SandboxID: reader.SandboxID})
if err == nil {
	_, err = client.DeleteVolume(ctx, &sandboxes.DeleteVolumeRequest{VolumeID: volume.VolumeID})
}
Rust
sandboxes
    .delete_sandbox(DeleteSandboxRequest { sandbox_id: writer.sandbox_id.clone(), ..Default::default() })
    .await?;
let mount = Mount { volume_id: volume.volume_id.clone(), path: "/data".into(), read_only: true };
let reader = sandboxes
    .create_sandbox(CreateSandboxRequest { template: "base".into(), mounts: vec![mount], ..Default::default() })
    .await?;
let read = sandboxes
    .run_command(RunCommandRequest {
        sandbox_id: reader.sandbox_id.clone(),
        command: "cat /data/first-run.txt".into(),
        ..Default::default()
    })
    .await?;
print!("{}", read.stdout);
sandboxes
    .delete_sandbox(DeleteSandboxRequest { sandbox_id: reader.sandbox_id.clone(), ..Default::default() })
    .await?;
sandboxes
    .delete_volume(DeleteVolumeRequest { volume_id: volume.volume_id.clone(), ..Default::default() })
    .await?;
CLI
$ pethost sandbox rm writer --yes
upc3ehxd65rjgz32   deleted
$ pethost sandbox new --name reader --mount o2rvhgm1dxaefoj7:/data:ro
✓ Made sandbox reader (zc44605gliwn2v1b): default, running, from base@17, in <1 s
zc44605gliwn2v1b
Next:   pethost sandbox run zc44605gliwn2v1b -- <command>   ·   pethost sandbox shell zc44605gliwn2v1b
$ pethost sandbox run reader -- cat /data/first-run.txt
Sun Nov 22 00:25:40 UTC 2026
$ pethost sandbox rm reader --yes
zc44605gliwn2v1b   deleted
$ pethost sandbox volume rm o2rvhgm1dxaefoj7 --yes
o2rvhgm1dxaefoj7

Wo ein Volume liegt

Ein Volume ist eine Datei auf der Disk eines Sandbox-Servers, die ein ext4-Dateisystem enthält, und eine Sandbox, die es mountet, läuft auf diesem Server. Es wird weder in den Objektspeicher noch auf einen anderen Server kopiert. Das hat drei Folgen:

  • Geht sein Server verloren, ist das Volume verloren: Es wird DELETED, und die Sandboxes, die es gemountet hatten, verlieren es. Leg dort keine einzige Kopie von irgendetwas ab: Schieb, was zählt, zusätzlich in einen eigenen Speicher.
  • Eine Sandbox mit Volume bleibt auf ihrem Server. Eine gestoppte Sandbox ohne Volumes kann auf einem anderen Server starten, wenn ihr eigener voll ist; eine mit Volume wartet auf Platz auf ihrem eigenen und wird währenddessen mit NoCapacity abgelehnt.
  • Eine Sandbox mit einem Volume mit Schreibzugriff lässt sich nicht forken: Ein Volume schreibt immer nur eine Sandbox.

Ein Volume teilt die Disk-Geschwindigkeit der Sandbox, die es mountet, 64 MiB/s pro vCPU. Eins, das größer als die halbe Disk eines Servers ist, wird abgelehnt.

Volumes und die eigene Disk einer Sandbox

Die meiste Arbeit braucht kein Volume. Die eigene Disk einer Sandbox übersteht ihre Pausen und Stopps: Die Disk einer gestoppten Sandbox liegt im Objektspeicher und kommt beim Fortsetzen zurück, auf jedem Server. Eine Vorlage bringt Dateien in jede neue Sandbox. Ein Volume ist für Daten, die die Sandboxes überdauern, die sie nutzen, oder die viele gleichzeitig lesen: ein Datensatz, die Gewichte eines Modells, ein geteilter Cache.

Was es kostet

Ein Volume zählt seine ganze Größe, 0,20 $ pro GiB und Monat, sekundengenau, vom Erstellen bis zum Löschen, ob eine Sandbox es mountet oder nicht. Dein Tarif begrenzt, was die Volumes des Workspace zusammen belegen: 100 GiB im Tarif für 20 $, 600 GiB im Tarif für 100 $, 10 GiB in der Testphase. Workspace.volume_gib_used sagt, was sie gerade belegen.

Wenn es nicht funktioniert

  • FAILED_PRECONDITION, das Volume ist von einer anderen Sandbox gemountet: Es ist schreibend gemountet. Mounte es lesend, oder lösch oder stopp die Sandbox, die es schreibt.
  • FAILED_PRECONDITION, sein Journal muss vielleicht nachgespielt werden: Die letzte Sandbox, die es geschrieben hat, endete, bevor sie es aushängte. Mounte es einmal schreibend, dann wieder lesend.
  • FAILED_PRECONDITION bei DeleteVolume: Eine Sandbox mountet es. Lösch diese Sandbox zuerst.
  • RESOURCE_EXHAUSTED mit LimitReached, volume_gib: Die Volumes des Workspace würden die GiB des Tarifs überschreiten. Lösch eins, oder mach es kleiner.
  • UNAVAILABLE mit NoCapacity beim Erstellen oder Fortsetzen: Der Server des Volumes hat gerade keinen Platz, und eine Sandbox mit Volume kann nicht woandershin. Versuch es später noch einmal.

Fragen

Wird ein Volume gesichert?

Nein. Es liegt auf der Disk eines Servers und wird nirgendwohin kopiert: Halte eine Kopie dessen, was zählt, woanders.

Können sich mehrere Sandboxes ein Volume teilen?

Lesend beliebig viele gleichzeitig. Schreibend eine auf einmal.

Kann ich ein Volume in eine laufende Sandbox mounten?

Nein: Mounts werden beim Erstellen angegeben, bis zu 4 pro Sandbox.

Wird ein Volume abgerechnet, während nichts es mountet?

Ja, nach seiner ganzen Größe, 0,20 $ pro GiB und Monat, bis du es löschst.

Brauche ich ein Volume, um Dateien zwischen Sitzungen zu behalten?

Nein. Die eigene Disk einer Sandbox übersteht Pausen und Stopps; ein Volume ist für Daten, die die Sandbox überdauern.

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