Doku zu Agent Sandboxes · Einstieg
So funktionieren Pethost Agent Sandboxes
Eine Sandbox ist eine Linux-VM, die dein Code oder dein Agent in etwa 0,15 s startet, über eine API nutzt und dann in Ruhe lässt. Passiert nichts in ihr, pausiert sie mit RAM und Prozessen und stoppt später nur mit ihrer Disk. Der nächste Aufruf weckt sie dort, wo sie war. Diese Seite ist das Modell: was eine Sandbox ist, ihre drei Zustände, was sie zwischen ihnen bewegt und wo jedes Byte liegt.
- Eine MicroVM pro Sandbox: Firecracker, eigener Kernel, darin root, Ubuntu mit Python, Node.js, Docker, drei Coding-Agenten und Chrome.
- Drei Zustände: RUNNING im RAM ihres Servers, PAUSED auf der Disk ihres Servers mit RAM und Prozessen, STOPPED im Objektspeicher nur mit ihrer Disk.
- Aufwachen bei Nutzung: Jeder Aufruf in eine pausierte Sandbox, ein SSH-Login oder ein Request an einen ihrer Ports setzt sie in etwa 0,1 s fort.
- Zwei APIs: Das Panel führt den Eintrag jeder Sandbox, und der eigene Server der Sandbox führt aus, was in ihr passiert. Die SDKs und die CLI verbergen den Unterschied.
- Sekundengenau abgerechnet für jeden Zustand: Abrechnung.
Was eine Sandbox ist
Eine Sandbox ist eine virtuelle Maschine, erstellt aus einer Vorlage. Darin bist du root, und Befehle laufen als Benutzer user, der sudo ohne Passwort hat, in /home/user. Der Hostname ist ihre ID: 16 Zeichen, Kleinbuchstaben und Ziffern.
Unsere Vorlage, base, enthält Ubuntu 24.04 mit Build-Tools und git, Python 3, Node.js 22, Docker, die Coding-Agenten Claude Code, Codex und OpenCode und einen Desktop mit Google Chrome. Zwei davon starten erst bei der ersten Nutzung und kosten bis dahin nichts: der Desktop beim ersten Screenshot oder Desktop-Link (einige Sekunden) und der Docker-Daemon bei der ersten Verbindung zu /var/run/docker.sock.
Isolation: eine Firecracker-MicroVM für jede
Jede Sandbox ist eine eigene Firecracker-MicroVM mit eigenem Linux-Kernel. Firecracker führt jede VM in seinem Jailer aus: eigenes chroot, ein unprivilegierter Benutzer, eine cgroup, ein seccomp-Filter und ein eigener Network-Namespace. Der Gast gehört dir, root und Kernel eingeschlossen; was er bekommt, entscheidet der Host.
- Die Größe hält der Host. Eine VM bekommt die vCPUs und den RAM ihrer Größe vom Server, und nichts, was der Gast sagt, ändert das.
- Eigene Identität. Jede Sandbox bekommt frische Zufallszahlen des Kernels, einen eigenen Hostname und eine eigene machine-id, auch wenn sie aus demselben Snapshot startet wie eine andere.
- Keine Secrets darin. Die Secrets des Workspace kommen nie in eine VM, API-Tokens auch nicht: Eine Sandbox erreicht man mit einem Token nur für diese eine Sandbox, das abläuft.
Größen
Eine Sandbox hat eine von vier Größen, für das ganze Leben ihrer VM:
| Größe | vCPUs | RAM | Disk |
|---|---|---|---|
| SMALL | 2 | 4 GiB | 10 GiB |
| DEFAULT | 4 | 8 GiB | 20 GiB |
| LARGE | 8 | 16 GiB | 40 GiB |
| XLARGE | 16 | 32 GiB | 80 GiB |
Die Disk ist, was die Sandbox schreiben darf: Die eigenen Dateien der Vorlage zählen nicht dagegen. Eine neue Größe (UpdateSandbox) startet eine RUNNING-Sandbox in einer VM dieser Größe neu, ihre Dateien bleiben, ihre Prozesse enden; eine STOPPED-Sandbox nimmt die neue Größe beim nächsten Start, und eine PAUSED-Sandbox muss zuerst fortgesetzt oder gestoppt werden. Eine neue Größe behält die Disk, außer du setzt grow_disk, das sie auf die der neuen Größe vergrößert. Eine Disk schrumpft nie.
Vorlagen
Eine Vorlage sind die Dateien, mit denen eine Sandbox startet. Unsere ist base, jeden Monat neu gebaut und sofort bei einem Sicherheitsfix. Deine ist die Disk einer Sandbox, gespeichert mit CreateTemplate: ihre Dateien, die Pakete, die du installiert hast, und ihre Docker-Images. Eine Vorlage behält keinen RAM, keine Prozesse und keine Unterhaltungen von Agenten: Eine Sandbox daraus bootet frisch.
Jedes Speichern ist eine neue Version, name@1, name@2, und eine Sandbox, die aus name startet, nimmt die neueste. Jeder Server startet Sandboxes aus jeder Version. Das min_size einer Version ist die kleinste Größe, deren Disk fasst, was sie gespeichert hat. Eine Sandbox aus deiner eigenen Vorlage startet in etwa 0,22 s, sobald ihr Server die Version hat; die erste auf jedem Server holt sie, etwa 10 s pro GiB: Vorlagen.
Zwei APIs: das Panel und der Server der Sandbox
Zwei Services antworten, je nachdem, was sie wissen:
- SandboxService ist das Panel, unter
https://console.pethost.dev, aufgerufen mit deinem API-Token. Es hält den Workspace und jede Sandbox als Eintrag: Erstellen, Einstellungen, Pause, Fortsetzen, Fork, Löschen, Vorlagen, Volumes, Events und Verbrauch. - SandboxRuntimeService ist der eigene Server der Sandbox, unter der
urlihrer Verbindung, aufgerufen mit einem Verbindungs-Token für diese eine Sandbox. Er führt aus, was darin passiert: Befehle, Dateien, den Desktop, Coding-Agenten und Links.
Die SDKs und die CLI verbinden sich für dich: run_command ist ein Aufruf, und das SDK findet den Server und hält das Token frisch. Runtime-Aufrufe gehen direkt an den Server, also steht das Panel nie im Weg dessen, was in einer Sandbox läuft, und ein Server betreibt seine Sandboxes ohne das Panel.
Die drei Zustände
Im RAM ihres Servers
Führt deine Prozesse aus und beantwortet jeden Aufruf.
0,036 $ pro Stunde, DEFAULT
5 min Leerlauf oder PauseSandbox
Jeder Aufruf, SSH-Login oder Port-Request, in etwa 0,1 s
Auf der Disk ihres Servers
Behält RAM, Prozesse und Disk und ihren Platz auf dem Server.
0,0108 $ pro Stunde, DEFAULT
30 min Leerlauf oder StopSandbox
Im Objektspeicher
Behält ihre Disk; ihre Prozesse enden.
0,03 $ pro GiB und Monat ihrer eigenen Daten
ResumeSandbox bootet sie wieder: etwa 0,2 s mit ihrer Disk auf dem Server, etwa 10 s pro GiB aus dem Objektspeicher
| Zustand | Wo sie liegt | Was sie behält | Wie sie aufwacht |
|---|---|---|---|
| RUNNING | Im RAM ihres Servers | Alles, laufend | Sie ist wach |
| PAUSED | Auf der Disk ihres Servers | RAM, Prozesse, Disk | Beim nächsten Aufruf, SSH-Login oder Port-Request, in etwa 0,1 s; nie aus Platzmangel abgelehnt |
| STOPPED | Im Objektspeicher und auf der Disk ihres Servers, solange Platz ist | Die Disk | Durch ResumeSandbox oder wie eine pausierte mit wake_when_stopped |
| DELETED | Nirgends | Den Eintrag 30 Tage, Events und Metriken einen Tag | Nie |
Warum es PAUSED gibt
Die VM eines Agenten verbringt die meiste Zeit mit Warten: darauf, dass das Modell denkt, dass eine Person die Antwort liest, auf die nächste Nachricht. Sie zu stoppen beendet ihre Prozesse und mit ihnen den Dev-Server, die REPL, den Zustand der Shell und den offenen Browser, den der Agent benutzt hat. Sie RUNNING zu lassen zahlt den vollen Preis fürs Warten.
PAUSED behält alles, RAM und Prozesse eingeschlossen, für 30 % des Preises im Betrieb, und der Server hält den Platz der Sandbox, also wird ein Fortsetzen nie aus Platzmangel abgelehnt. Dein Code tut nichts, um sie zu wecken: Der nächste Aufruf in die Sandbox setzt sie zuerst fort, in etwa 0,1 s, und läuft dann, als hätte die Sandbox nie angehalten. Eine pausierte Sandbox braucht auf ihrem Server 41 ms zum Fortsetzen, und ein Befehl an eine pausierte antwortet in etwa 80 ms.
Was eine Sandbox bewegt
| Von | Nach | Was sie bewegt |
|---|---|---|
| RUNNING | PAUSED | Der Pause-Timer; PauseSandbox; ihr Server mit zu wenig RAM, sobald sie eine Minute im Leerlauf war; ein Neustart der Maschine ihres Servers (MAINTENANCE, die nichts zählt) |
| PAUSED | RUNNING | Jeder Runtime-Aufruf, ein SSH-Login oder ein Request an einen Port (WAKE); ResumeSandbox |
| RUNNING oder PAUSED | STOPPED | Der Stopp-Timer; StopSandbox; ihr Server mit zu wenig Disk (eine pausierte); ein Workspace, der nichts zu zahlen hat (UNPAID); ein Absturz ihrer VM oder ihres Servers (CRASH) |
| STOPPED | RUNNING | ResumeSandbox; ein Aufruf, SSH-Login oder Port-Request nur mit wake_when_stopped, und nie nach einem CRASH |
| Jeder | DELETED | DeleteSandbox; ihr Lösch-Timer; der Verlust ihres Servers, für eine Sandbox ohne Kopie im Objektspeicher |
Jede Änderung hat einen Grund, state_reason, und Worte für Menschen, state_message. Lebenszyklus und Leerlauf sagt, was als Aktivität zählt und wie du die Timer einstellst.
Was eine Sandbox weckt
Jeder Aufruf von SandboxRuntimeService, ein SSH-Login oder ein Request an einen ihrer Ports setzt eine PAUSED-Sandbox zuerst fort, auf ihrem eigenen Server. Eine STOPPED-Sandbox wacht so nur auf, wenn ihr Lebenszyklus wake_when_stopped sagt. Ohne das:
- antwortet ein Runtime-Aufruf
FAILED_PRECONDITIONmit dem DetailStopped; - antwortet ein Request an einen Port mit HTTP 503, „stopped: resume it“;
- startet sie nur
ResumeSandbox.
Eine Sandbox, die ein CRASH gestoppt hat, startet nur durch ResumeSandbox wieder. Während die Disk einer gestoppten Sandbox aus dem Objektspeicher zurückgeholt wird, antworten Aufrufe in sie UNAVAILABLE mit Restoring, und ResumeSandbox wartet bis zu 45 s und sagt dann, wie weit das Holen ist (Sandbox.restore).
Wo deine Daten liegen
| Was | Pause | Stopp | Fork | Vorlage | Löschen |
|---|---|---|---|---|---|
| RAM | Bleibt | Verloren | Kopiert | Nicht gespeichert | Weg |
| Laufende Prozesse | Bleiben | Beendet | Kopiert, laufend | Nicht gespeichert | Weg |
| Dateien und Docker-Images | Bleiben | Bleiben | Kopiert | Gespeichert | Weg |
| Unterhaltungen von Agenten | Bleiben | Bleiben | Kopiert | Nicht gespeichert | Weg |
Die Disk einer gestoppten Sandbox wird eine Minute nach dem Stopp in einen Objektspeicher in der EU kopiert, in Stücken, verschlüsselt mit einem Schlüssel nur für diese Sandbox; RAM wird nie dorthin kopiert. Der Server behält seine eigene Kopie, solange er Platz hat. Ein Volume ist anders: Es liegt auf der Disk eines Servers und wird nirgendwohin kopiert, also halte, was den Verlust eines Servers überstehen muss, auch woanders.
Umzüge und verlorene Server
Eine STOPPED-Sandbox mit aktueller Kopie und ohne Volume startet auf einem anderen Server, wenn ihr eigener keinen Platz für sie hat, und ihre Adressen ziehen mit: die url der Verbindung, die URLs ihrer Ports und ihr ssh_command. Eine PAUSED-Sandbox zieht nie um: Sie wird auf dem Server fortgesetzt, der ihren RAM hält.
Geht ein Server verloren, wird jede seiner Sandboxes mit Kopie aus ihrer letzten Kopie STOPPED und startet beim nächsten ResumeSandbox auf einem anderen Server. Eine Sandbox ohne Kopie wird gelöscht, ebenso die Volumes auf diesem Server.
Fragen
Ist eine Sandbox ein Container?
Nein. Jede Sandbox ist eine Firecracker-MicroVM mit eigenem Linux-Kernel, und darin bist du root. In einer Sandbox kannst du Docker-Container ausführen.
Was passiert mit meinen Prozessen, wenn eine Sandbox pausiert?
Sie halten an, wo sie sind, und behalten ihren RAM, ihre offenen Dateien und ihren Zustand. Der nächste Aufruf, SSH-Login oder Request an einen Port setzt sie in etwa 0,1 s fort, als wäre nichts gewesen.
Kann eine pausierte Sandbox aus Platzmangel nicht aufwachen?
Nein. Der Server hält ihren Platz, solange sie pausiert, also wird ein Fortsetzen nie aus Platzmangel abgelehnt. Bei einer gestoppten kann das passieren: Dann startet ResumeSandbox sie unter Umständen auf einem anderen Server.
Wo sind meine Dateien, wenn eine Sandbox gestoppt ist?
Auf ihrer Disk, kopiert in einen Objektspeicher in der EU, verschlüsselt mit einem Schlüssel für diese Sandbox, und auf ihrem Server, solange Platz ist. Sie kommen beim Fortsetzen so zurück, wie sie waren.
Behält eine Vorlage laufende Prozesse?
Nein. Eine Vorlage speichert nur die Disk: Dateien, Pakete und Docker-Images. Eine Sandbox daraus bootet frisch, ohne Prozess und ohne Unterhaltung eines Agenten der Sandbox, aus der sie gespeichert wurde. Um eine laufende Sandbox zu kopieren, forke sie.
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.