Deutsch
Menü der Doku

Doku zu Agent Sandboxes · Aufgaben

Vorlagen: Sandboxes startklar starten

Aktualisiert · 6 Min. Lesezeit

Eine Vorlage ist das, woraus eine Sandbox startet. Unsere, base, hat die Tools; deine ist die Disk einer Sandbox, so gespeichert, wie sie ist, mit den Paketen, die du installiert hast, deinem Code und seinen Docker-Images. Eine Sandbox daraus startet in etwa 0,22 s, und nichts bleibt zu installieren.

Kurz gesagt
  • CreateTemplate speichert Disk und Einstellungen einer Sandbox als neue Version, my-app@1, my-app@2, während die Sandbox weiterläuft.
  • SAVING, dann READY in etwa 1,5 s bei einer kleinen, und etwa 10 s pro GiB ihrer eigenen Daten.
  • CreateSandbox mit "my-app" startet aus ihrer neuesten READY-Version, auf jedem Server.
  • Nur Dateien: Eine Vorlage behält keinen RAM, keine Prozesse und keine Unterhaltungen von Agenten. Sie wird nicht abgerechnet; dein Tarif begrenzt ihre Größe.

Step 1: Sandbox vorbereiten

Erstell eine Sandbox aus base und richte sie so ein, wie jede neue sein soll: Klon deinen Code, installier seine Abhängigkeiten, pull die Docker-Images, die er ausführt, wärm die Caches vor (Befehle und Dateien). Die Einstellungen zählen auch: Die Vorlage übernimmt Lebenszyklus, Egress, öffentliche Ports und Umgebung der Sandbox, wie sie gerade sind, und Sandboxes daraus starten damit, außer ihr Erstellen sagt etwas anderes.

Step 2: Als Vorlage speichern

CreateTemplate antwortet innerhalb von Millisekunden mit der neuen Version im Zustand SAVING, sobald es die Disk hält, wie sie ist: Die Sandbox läuft weiter. Der Server schrumpft die Version dann auf das, was sie hält, und lädt sie hoch. Warte auf READY, bevor du aus dieser Version startest.

Python
import time

from pethost.sandboxes import TemplateState

version = sandboxes.create_template("my-app", sandbox_id=sandbox_id, description="Node 22 and our dependencies")
while version.state == TemplateState.SAVING:
    time.sleep(1)
    version = sandboxes.get_template(f"my-app@{version.version}")
print(version.name, version.version, version.state.name, version.min_size.name, version.size_bytes)
# my-app 1 READY SMALL 25447048
TypeScript
let version = await sandboxes.createTemplate({
  name: "my-app",
  sandboxId,
  description: "Node 22 and our dependencies",
});
while (version.state === TemplateState.SAVING) {
  await new Promise((resolve) => setTimeout(resolve, 1000));
  version = await sandboxes.getTemplate({ template: `my-app@${version.version}` });
}
console.log(version.name, version.version, version.state, version.minSize, version.sizeBytes);
Go
version, err := client.CreateTemplate(ctx, &sandboxes.CreateTemplateRequest{
	Name:        "my-app",
	SandboxID:   id,
	Description: "Node 22 and our dependencies",
})
for err == nil && version.State == sandboxes.TemplateStateSaving {
	time.Sleep(time.Second)
	version, err = client.GetTemplate(ctx, &sandboxes.GetTemplateRequest{Template: fmt.Sprintf("my-app@%d", version.Version)})
}
if err != nil {
	log.Fatal(err)
}
fmt.Println(version.Name, version.Version, version.State, version.MinSize, version.SizeBytes)
Rust
let mut version = sandboxes
    .create_template(CreateTemplateRequest {
        name: "my-app".into(),
        sandbox_id: id.clone(),
        description: "Node 22 and our dependencies".into(),
        ..Default::default()
    })
    .await?;
while matches!(version.state, TemplateState::Saving) {
    tokio::time::sleep(std::time::Duration::from_secs(1)).await;
    let template = format!("my-app@{}", version.version);
    version = sandboxes.get_template(GetTemplateRequest { template, ..Default::default() }).await?;
}
println!("{} {} {:?} {:?} {}", version.name, version.version, version.state, version.min_size, version.size_bytes);
CLI
$ pethost sandbox template save api-dev my-app --description 'Node 22 and our dependencies'
✓ Saving my-app@2: it is ready once uploaded. See:  pethost sandbox template show my-app@2
my-app@2
$ pethost sandbox template ls my-app
my-app@2   ready   68 MB      55 s ago    Node 22 and our dependencies
my-app@1   ready   24 MB      1 min ago   Node 22 and our dependencies
MCP
CreateTemplate {"name": "my-app", "sandbox_id": "…", "description": "Node 22 and our dependencies"}
ListTemplates {"name": "my-app"}

Step 3: Sandboxes daraus starten

Nenn die Vorlage in CreateSandbox: "my-app" ist ihre neueste READY-Version, "my-app@2" genau diese. Die erste Sandbox einer Version auf einem Server holt sie, etwa 10 s pro GiB; der Server behält sie, und die nächsten starten in etwa 0,22 s.

Python
preview = sandboxes.create_sandbox("my-app")
print(preview.sandbox_id, preview.template)  # 8j37xshusqwdz8cs my-app@1
TypeScript
const preview = await sandboxes.createSandbox({ template: "my-app" });
console.log(preview.sandboxId, preview.template);
Go
preview, err := client.CreateSandbox(ctx, &sandboxes.CreateSandboxRequest{Template: "my-app"})
if err != nil {
	log.Fatal(err)
}
fmt.Println(preview.SandboxID, preview.Template)
Rust
let preview = sandboxes
    .create_sandbox(CreateSandboxRequest { template: "my-app".into(), ..Default::default() })
    .await?;
println!("{} {}", preview.sandbox_id, preview.template);
CLI
$ pethost sandbox new --template my-app
✓ Made sandbox ofvm8by6buvd4rkd: default, running, from my-app@2, in <1 s
  port 5173: https://5173-ofvm8by6buvd4rkd.sbx1.sandboxes.pethost.network
ofvm8by6buvd4rkd
Next:   pethost sandbox run ofvm8by6buvd4rkd -- <command>   ·   pethost sandbox shell ofvm8by6buvd4rkd
MCP
CreateSandbox {"template": "my-app"}

Das template der Antwort nennt die genaue Version, aus der sie gestartet ist, etwa my-app@1.

Was eine Vorlage behält

  • Behalten: jede Datei auf der Disk der Sandbox, darunter die Pakete, dein Code, die Images und Container von Docker; und die Einstellungen der Sandbox, mit denen ihre Sandboxes starten, außer ihr Erstellen sagt etwas anderes.
  • Nicht behalten: RAM und Prozesse, also startet eine Sandbox aus einer Vorlage ohne etwas von dem, was lief; den Verlauf der Befehle und die Unterhaltungen der Coding-Agenten, ohne die ihre Sandboxes starten.
  • Frisch in jeder Sandbox: eigene ID, eigener Hostname, eigene machine-id und eigene Zufallszahlen des Kernels.

Um eine Sandbox mit RAM und Prozessen zu kopieren, so wie sie in dieser Sekunde ist, forke sie stattdessen: Forks. Eine Vorlage ist für viele Sandboxes über Tage; ein Fork für ein paar Kopien jetzt.

Versionen und Größen

Jedes Speichern unter einem Namen ist dessen nächste Version. "my-app" meint immer die neueste READY-Version, die vorige, während eine neue gespeichert wird, also macht das Speichern deine Erstellungen nie kaputt. Ein Name behält 10 Versionen; eine FAILED-Version belegt nichts und verschwindet nach einem Tag. Ein Workspace speichert eine Version auf einmal, und eine Sandbox behält die Version, aus der sie gestartet ist, auch nachdem du die Vorlage gelöscht hast.

Eine READY-Version hat ein min_size: die kleinste Größe, deren Disk fasst, was sie gespeichert hat. Sandboxes daraus nehmen jede Größe ab dieser. Ein Erstellen mit einer kleineren Größe wird abgelehnt und nennt die, die passt.

Wo sie liegt und was sie kostet

Eine Version wird auf das geschrumpft, was sie hält, komprimiert, mit einem eigenen Schlüssel verschlüsselt und in einem Objektspeicher in der EU aufbewahrt, wo jeder Server Sandboxes daraus starten kann. Nur ihre eigenen Bytes zählen, nicht die Basis darunter. Vorlagen werden nicht abgerechnet: Dein Tarif begrenzt, was die Versionen des Workspace zusammen belegen, 5 GiB im Tarif für 20 $ und 30 GiB im Tarif für 100 $ (Limits.template_gib; Workspace.template_bytes ist, was sie gerade belegen). DeleteTemplate löscht jede Version eines Namens und gibt den Platz sofort frei; Sandboxes, die daraus erstellt wurden, laufen, pausieren und werden fortgesetzt wie zuvor.

Unsere Vorlage: base

base ist Ubuntu 24.04 mit Build-Tools und git, Python 3, Node.js 22, Docker mit Compose, Claude Code, Codex und OpenCode und einem Desktop mit Google Chrome. Wir bauen sie monatlich neu, und sofort bei einem Sicherheitsfix von Chrome, des Kernels oder eines Pakets. Template.base nennt die Version, auf der die Sandboxes einer Vorlage starten, über einen Hash dessen, was sie hält: Eine Version, die du speicherst, behält die Basis, auf der ihre Sandbox gestartet ist, also ändert sich deine Vorlage nicht unter dir.

Es gibt keinen Build aus einem Dockerfile: Führ die Schritte deines Dockerfiles in einer Sandbox aus, oder docker build darin, und speichere diese Sandbox.

Wenn es nicht funktioniert

  • RESOURCE_EXHAUSTED mit LimitReached, template_gib: Die Versionen des Workspace belegen den Platz seines Tarifs, oder eine andere Version wird gerade gespeichert. Lösch eine alte Vorlage, oder warte auf das Speichern.
  • LimitReached, template_versions: Der Name hat 10 Versionen. Speichere unter einem neuen Namen, oder lösch die Vorlage und speichere neu.
  • Die Version ist FAILED: failure_message sagt, warum, etwa eine Version, deren eigene Bytes den übrigen Platz überschritten haben. Mach Platz frei, dann speichere neu.
  • INVALID_ARGUMENT, das eine Größe nennt: Die Größe ist kleiner als das min_size der Version. Frag nach dieser Größe oder einer größeren.
  • Die erste Sandbox aus einer neuen Version ist langsam: Der Server hat die Version geholt, etwa 10 s pro GiB. Die nächsten dort starten in etwa 0,22 s.

Fragen

Wie erstelle ich eine eigene Vorlage für Sandboxes?

Richte eine Sandbox so ein, wie du neue haben willst, dann CreateTemplate mit einem Namen und ihrer ID. Starte neue Sandboxes mit diesem Namen.

Behält eine Vorlage laufende Prozesse?

Nein: nur Dateien und Einstellungen. Um eine laufende Sandbox mit RAM und Prozessen zu kopieren, forke sie.

Werden Vorlagen abgerechnet?

Nein. Dein Tarif begrenzt, wie viele GiB die Vorlagen des Workspace im Objektspeicher belegen.

Kann ich eine Vorlage aus einem Dockerfile bauen?

Nicht direkt: Führ die Schritte des Dockerfiles oder docker build in einer Sandbox aus und speichere die Sandbox dann als Vorlage.

Bleiben Docker-Images in einer Vorlage erhalten?

Ja. Die Images und Container von Docker liegen auf der Disk der Sandbox, die die Vorlage behält.

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