Deutsch
Menü der Doku

Doku zu Agent Sandboxes · Konzepte

Best Practices für Pethost Agent Sandboxes

Aktualisiert · 8 Min. Lesezeit

Eine Handvoll Entscheidungen bestimmt, wie schnell deine Sandboxes starten, was sie beim Warten kosten und was ein Agent darin erreichen kann. Jede Praxis unten ist eine Regel, die Zahl dahinter und die Felder, die es tun. Die meisten sind eine Einstellung, die du einmal machst.

Kurz gesagt
  • Tempo: Speichere dein Setup als Vorlage, starte Server mit wait_for_port und forke für parallele Versuche.
  • Kosten: Lass die Sandbox eines Agenten pausieren statt stoppen, lösch Batch-Sandboxes, wenn sie fertig sind, und fang klein an.
  • Zuverlässigkeit: Markier lange Befehle mit keep_awake, wiederhole mit request_id, streame statt zu pollen und nimm Volumes für das, was eine Sandbox überdauern muss.
  • Sicherheit: Binde API-Keys als Secrets, schränk Egress für Code ein, den du nicht geschrieben hast, und behandle alles, was eine Sandbox zurückgibt, als Daten.
  • Ordnung: Gib jeder Sandbox Labels und liste sie nach Label.

Tempo

Dein Setup als Vorlage speichern

Deine Abhängigkeiten bei jedem Start zu installieren kostet jedes Mal dieselben Minuten. Installier sie einmal in einer Sandbox und speichere dann ihre Disk mit CreateTemplate: Pakete, Build-Caches und Docker-Images inklusive. Eine Sandbox aus deiner Vorlage startet in etwa 0,22 s mit allem an seinem Platz, auf jedem Server: Die erste auf jedem Server holt die Version, etwa 10 s pro GiB, und die nächsten starten aus seiner Kopie. Halte Secrets aus den gespeicherten Dateien heraus, denn jede Sandbox aus der Vorlage bekommt sie, und mach eine neue Version, wenn sich deine Abhängigkeiten ändern: my-app startet aus der neuesten, my-app@3 aus dieser.

Server mit wait_for_port starten

Ein Dev-Server braucht einen Moment, bis er lauscht, und ihn von außen abzufragen verschwendet Aufrufe. Starte ihn mit wait_for_port: RunCommand antwortet, sobald etwas auf diesem Port lauscht, während der Befehl weiterläuft, also startet ein Aufruf den Server und sagt dir, dass er läuft. Dann öffne den Port öffentlich, oder gib deiner Seite ein Token dafür: Ports und Vorschauen.

Für parallele Versuche forken

Soll ein Agent mehrere Fixes probieren oder ein Eval viele Läufe aus einem vorbereiteten Zustand starten, forke die Sandbox, statt diesen Zustand neu aufzubauen. ForkSandbox kopiert RAM, Prozesse und Disk in einem Aufruf in bis zu 100 neue Sandboxes: Eine Kopie dauerte etwa 0,25 s. Jede Kopie ist ein Start, und es entstehen alle oder keine. Zwei Dinge solltest du wissen:

  • Setz Zufallsgeneratoren in den Kopien neu. Jede Kopie hat eigene Zufallszahlen des Kernels, aber die Zufallsgeneratoren, die in ihren Prozessen schon laufen (die von OpenSSL, Python, Node, Go), liefern in jeder Kopie dieselben Zahlen, bis sie neu gesetzt werden.
  • Ein Volume mit Schreibzugriff verhindert einen Fork, denn nur eine Sandbox darf es schreiben. Ein Volume wird nur beim Erstellen gemountet, also mounte es mit read_only in einer Sandbox, die du forken willst.

Kosten

Die Sandbox eines Agenten pausieren lassen, nicht stoppen

Die Sandbox eines Agenten wartet die meiste Zeit, und sie zu stoppen beendet ihre Prozesse: den Dev-Server, die REPL, den Browser, den sie offen hatte. Behalte den Pause-Timer, und erhöh den Stopp-Timer oder schalt ihn ab (stop_after_idle_seconds 0). Pausiert kostet die Sandbox 30 % ihres Preises im Betrieb und wacht beim nächsten Aufruf in etwa 0,1 s auf, mit allem dort, wo es war. Eine DEFAULT-Sandbox, die 2 Stunden am Tag arbeitet und den Rest pausiert, kostet etwa 9,42 $ im Monat, gegenüber 26,28 $, wenn sie immer läuft.

Die Sitzung eines AgentenPausiert zwischen den Turns, stoppt nie

  1. läuft
  2. pausiert
  3. läuft
  4. pausiert

Die Sandbox eines Nutzers deiner AppPausiert, dann stoppt sie nach einer halben Stunde

  1. läuft
  2. pausiert
  3. gestoppt

Eine Vorschau, die schläftWacht bei jedem Besuch auf

  1. pausiert
  2. läuft
  3. pausiert
  4. läuft
  5. pausiert

Ein Batch-JobLäuft, dann wird er gelöscht

  1. läuft
  2. gestoppt
  3. gelöscht
  • RUNNING
  • PAUSED
  • STOPPED
  • DELETED
Vier Jobs über einen Tag, jeder mit eigenem Lebenszyklus. Die Werte stehen in Lebenszyklus und Leerlauf.

Batch-Sandboxes löschen, wenn sie fertig sind

Eine Sandbox für einen einzelnen Job, einen Testlauf oder einen Eval-Fall soll nichts mehr kosten, sobald der Job endet. Ruf am Ende DeleteSandbox auf, und setz delete_after_idle_seconds als Netz für einen Job, der vorher stirbt. Schalt den Pause-Timer ab und gib ihr einen kurzen Stopp-Timer, damit die Sandbox eines Jobs im Leerlauf schnell geht. Eine gestoppte Sandbox, die du vergisst, kostet 0,03 $ pro GiB und Monat, jeden Monat. Starts sind kostenlos, also kostet eine frische Sandbox pro Job nur ihre Sekunden: 1.000 Läufe von 40 s auf SMALL kosten 0,20 $.

Klein anfangen und bei Bedarf die Größe ändern

Eine Größe sind ihre vCPUs, ihr RAM und ihre Disk, und ihr Preis verdoppelt sich mit jeder Stufe. Fang mit SMALL an, 0,018 $ pro Stunde, und beobachte GetSandboxMetrics. Braucht ein Job mehr, startet UpdateSandbox mit einer neuen Größe eine RUNNING-Sandbox in einer VM dieser Größe neu, ihre Dateien bleiben, in etwa 283 ms: Die Prozesse enden, also ändere die Größe zwischen Jobs. Füg grow_disk hinzu, um die Disk auf die der neuen Größe zu vergrößern; eine Disk schrumpft nie, also kann eine vergrößerte Sandbox nicht zu einer kleineren Größe zurück.

Zuverlässigkeit

Lange Befehle mit keep_awake markieren

Ein Build oder eine Testsuite kann minutenlang ohne einen Aufruf in die Sandbox laufen, und der Pause-Timer würde sie mitten in der Arbeit pausieren. Starte sie mit keep_awake und mit timeout_seconds, damit ein Befehl, der hängt, die Sandbox nicht für immer laufen lässt. Ein Server braucht beides nicht: Ein Request an seinen Port weckt die Sandbox. Lebenszyklus und Leerlauf hat die Details.

Mit request_id wiederholen

Ein Netzwerk kann die Antwort eines Aufrufs verlieren, der seine Arbeit getan hat. Ein Aufruf, der etwas erstellt, nimmt eine request_id: Eine Wiederholung mit derselben ID innerhalb von 24 Stunden antwortet mit dem, was der erste Aufruf getan hat, und tut nichts noch einmal. CreateSandbox, ForkSandbox, CreateTemplate, CreateVolume, RunCommand und PromptAgent nehmen eine. Erzeug sie einmal pro Sache, die du tun willst, behalte sie und schick sie bei jeder Wiederholung wieder. Eine Einschränkung: Eine Sandbox hält die IDs dessen, was in ihr läuft, auf ihrer Disk, also hat eine gestoppte die ihrer letzten Sekunden vielleicht verloren, und eine Wiederholung eines solchen Befehls führt ihn noch einmal aus.

Python
import uuid

from pethost.sandboxes import Label, Sandboxes

sandboxes = Sandboxes()  # The token: PETHOST_TOKEN.
request_id = str(uuid.uuid4())  # Keep it: a retry sends the same one.

sandbox = sandboxes.create_sandbox(
    template="my-app",
    labels=[Label(key="user", value="42"), Label(key="job", value="nightly-evals")],
    request_id=request_id,
)
TypeScript
import { Sandboxes } from "pethost/sandboxes";

const sandboxes = new Sandboxes({ token: process.env.PETHOST_TOKEN! });
const requestId = crypto.randomUUID(); // Keep it: a retry sends the same one.

const sandbox = await sandboxes.createSandbox({
  template: "my-app",
  labels: [{ key: "user", value: "42" }, { key: "job", value: "nightly-evals" }],
  requestId,
});
Go
requestID := rand.Text() // crypto/rand. Keep it: a retry sends the same one.

sandbox, err := client.CreateSandbox(ctx, &sandboxes.CreateSandboxRequest{
	Template:  "my-app",
	Labels:    []sandboxes.Label{{Key: "user", Value: "42"}, {Key: "job", Value: "nightly-evals"}},
	RequestID: requestID,
})
Rust
let request_id = uuid::Uuid::new_v4().to_string(); // Keep it: a retry sends the same one.

let sandbox = sandboxes
    .create_sandbox(CreateSandboxRequest {
        template: "my-app".into(),
        labels: vec![
            Label { key: "user".into(), value: "42".into() },
            Label { key: "job".into(), value: "nightly-evals".into() },
        ],
        request_id: request_id.clone(),
        ..Default::default()
    })
    .await?;
MCP
CreateSandbox {"template": "my-app", "labels": [{"key": "user", "value": "42"}], "request_id": "b7e1c2d4-0f3a-4c55-9a7e-2d1f6c8e9a10"}
HTTP
curl https://console.pethost.dev/pethost.sandboxes.v1.SandboxService/CreateSandbox \
  -H "Authorization: Bearer $PETHOST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template": "my-app", "labels": [{"key": "user", "value": "42"}], "request_id": "b7e1c2d4-0f3a-4c55-9a7e-2d1f6c8e9a10"}'

Streamen statt pollen

Einen Befehl oder eine Sandbox abzufragen kostet jedes Mal einen Aufruf und erfährt es trotzdem spät. Ein Aufruf, der wartet, übernimmt das Warten für dich: RunCommand, GetCommand, PromptAgent und GetAgentTurn warten bis zu 45 s (wait_seconds) und antworten, sobald die Arbeit endet. Um Arbeit zu folgen, während sie passiert, streame sie: WatchCommand für die Ausgabe eines Befehls, WatchConversation für die Nachrichten und Tool-Aufrufe eines Agenten, WatchSandboxEvents für den Lebenszyklus, die Befehle und Verbindungen einer Sandbox.

Volumes nur für das, was eine Sandbox überdauern muss

Ein Volume ist eine Disk außerhalb jeder Sandbox, gemountet an einem Pfad: Datensätze, Caches, die viele Sandboxes teilen, die Dateien einer Datenbank. Es liegt auf der Disk eines Servers und wird nirgendwohin kopiert, also ist das Volume weg, wenn dieser Server verloren geht. Eine Sandbox, die eins mountet, kann nicht auf einen anderen Server umziehen, und ein Mount mit Schreibzugriff verhindert Forks. Die meiste Arbeit braucht kein Volume: Die eigene Disk einer Sandbox übersteht Pausen und Stopps, und eine Vorlage bringt Dateien in neue Sandboxes. Was nicht verloren gehen darf, schieb zusätzlich in einen eigenen Speicher.

Sicherheit

API-Keys als Secrets binden

Einen Key in einer einfachen Umgebungsvariablen kann jeder Prozess in der Sandbox lesen, auch ein Agent, der seine Umgebung ausgibt. Speichere ihn stattdessen als Secret des Workspace, mit den Hosts, für die er gilt (SetSecret: anthropic, api.anthropic.com), und binde eine Variable daran (ANTHROPIC_API_KEY, Secret anthropic). Die Variable hält dann einen Platzhalter, phs_…, und der Egress-Proxy setzt den echten Key nur in die Header von HTTPS-Requests an diese Hosts ein. Ein neuer Wert gilt sofort in jeder Sandbox, die ihn bindet: Secrets und Egress.

Egress für Code einschränken, den du nicht geschrieben hast

Standardmäßig darf sich eine Sandbox überallhin verbinden. Für nicht vertrauenswürdigen Code liste auf, wohin er darf (egress.allow): eine Domain wie pypi.org, ihre Subdomains mit *.github.com (was github.com selbst auslässt), eine IP oder ein CIDR, jeweils mit einem Port, wo er nicht 80 und 443 ist, etwa github.com:22 für git über SSH. deny geht vor allow. Das DNS der Sandbox beantwortet nur Namen, die die Liste erlaubt, und nur TCP und DNS verlassen eine Sandbox: kein UDP und kein Ping. Eine Änderung gilt sofort und schließt Verbindungen, die sie nicht mehr erlaubt.

Was eine Sandbox zurückgibt, als Daten behandeln

Die Ausgabe von Befehlen, Dateiinhalte, die Nachrichten eines Agenten, Screenshots und die Seiten, die ein Browser lädt, kommen von Programmen und aus dem Internet. Liest ein Modell sie, sind sie Daten, nie Anweisungen: Eine README oder eine Webseite kann Text enthalten, der geschrieben wurde, um einen Agenten zu lenken. Zieh diese Linie in deinen Prompts, und gib einer Sandbox, die nicht vertrauenswürdige Arbeit ausführt, nicht mehr Secrets und keinen weiteren Egress, als die Arbeit braucht.

Ordnung

Jeder Sandbox Labels geben

Ein Label ist ein Schlüssel und ein Wert von dir: user=42, job=nightly-evals, run=7f3a. Eine Sandbox nimmt bis zu 32, und ListSandboxes listet die Sandboxes, die alle Labels haben, die du nennst. So findet deine App die Sandboxes eines Nutzers ohne eigene Tabelle, ein Aufräum-Job findet die Reste eines Laufs, und die Konsole zeigt, wem jede Sandbox gehört. Ein Label ist zum Finden vieler da; ein name zum Aufrufen einer: eindeutig im Workspace, bis zu 63 Zeichen aus a-z, 0-9 und „-“, und ListSandboxes mit name findet ihre ID.

Fragen

Soll ich eine Sandbox im Leerlauf stoppen oder pausieren?

Pausier sie, wenn ihre Prozesse wichtig sind oder sie bald wieder gebraucht wird: Sie wacht in etwa 0,1 s dort auf, wo sie war, zu 30 % des Preises im Betrieb. Stopp sie für einen langen Schlaf: Dann kostet sie nur ihre gespeicherten Daten.

Wie starten Sandboxes schneller?

Speichere dein Setup als Vorlage, damit beim Start nichts installiert wird: Eine Sandbox daraus startet in etwa 0,22 s mit deinen Paketen und Docker-Images.

Wie halte ich API-Keys aus einer Sandbox heraus?

Speichere jeden Key als Secret des Workspace mit seinen Hosts und binde eine Umgebungsvariable daran. Die Sandbox sieht einen Platzhalter, und der Egress-Proxy fügt den echten Key in Requests an diese Hosts ein.

Wie viele Sandboxes kann ich gleichzeitig betreiben?

So viele, wie die vCPUs deines Tarifs halten, laufend oder pausiert: 10 SMALL im Tarif für 20 $, 64 im Tarif für 100 $. Gestoppte Sandboxes zählen nicht.

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