---
title: "So funktionieren Pethost Agent Sandboxes | Pethost Agent Sandboxes"
description: "Was eine Sandbox ist, ihre drei Zustände RUNNING, PAUSED und STOPPED, was sie weckt, die zwei APIs und wo RAM, Prozesse und Dateien liegen."
---

[Doku zu Agent Sandboxes](https://pethost.dev/de/docs/sandboxes/) · Einstieg

# So funktionieren Pethost Agent Sandboxes

Aktualisiert 21. November 2026 · 8 Min. Lesezeit

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.

**Kurz gesagt**

- **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](https://pethost.dev/de/docs/sandboxes/billing/).

## 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](https://pethost.dev/de/docs/sandboxes/templates/).

## 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 `url` ihrer 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

**RUNNING**

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

**PAUSED**

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

**STOPPED**

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

Die Standard-Timer, ab dem Letzten, was in der Sandbox passiert ist. Eine RUNNING-Sandbox kann auch sofort stoppen, und jede Sandbox lässt sich löschen.

| 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](https://pethost.dev/de/docs/sandboxes/lifecycle/) 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_PRECONDITION` mit dem Detail `Stopped`;
- 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.

[ZurückDoku zu Pethost Agent Sandboxes](https://pethost.dev/de/docs/sandboxes/) [WeiterSchnellstart: deine erste Sandbox](https://pethost.dev/de/docs/sandboxes/quickstart/)

## 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](https://console.pethost.dev/)

Pethost · Stephan Gomer · NIP 1133096755

Pethost

- [Vorlagen](https://pethost.dev/de/templates/)
- [Über uns](https://pethost.dev/about/)
- [Doku](https://pethost.dev/docs/)
- [Blog](https://pethost.dev/de/blog/)
- [API](https://pethost.dev/docs/api/)
- [CLI](https://pethost.dev/docs/cli/)
- [Plugin](https://github.com/pethost-dev/plugin)
- [AGB](https://pethost.dev/terms/)
- [Datenschutz](https://pethost.dev/privacy/)
- [Erstattung](https://pethost.dev/refunds/)
- [support@pethost.dev](mailto:support@pethost.dev)

Datenbanken

- [Postgres](https://pethost.dev/de/postgres/)
- [Valkey](https://pethost.dev/de/valkey/)

Agent Sandboxes

- [Sandboxes](https://pethost.dev/de/sandboxes/)
- [Preise](https://pethost.dev/de/sandboxes/#pricing)
- [Doku](https://pethost.dev/de/docs/sandboxes/)
- [API](https://pethost.dev/docs/sandboxes/api/)

Vergleiche

- [Coolify vs Dokploy vs CapRover vs Dokku](https://pethost.dev/de/blog/coolify-vs-dokploy-vs-caprover-vs-dokku/)
- [Coolify Cloud vs Dokploy Cloud](https://pethost.dev/de/blog/coolify-cloud-vs-dokploy-cloud/)
- [Railway vs Render vs Fly.io Preise](https://pethost.dev/de/blog/railway-vs-render-vs-fly-io-pricing/)
- [Managed Hosting für Docker Compose](https://pethost.dev/de/blog/managed-docker-compose-hosting/)

Alternativen

- [Railway-Alternativen](https://pethost.dev/de/blog/railway-alternatives/)
- [Heroku-Alternativen](https://pethost.dev/de/blog/heroku-alternatives/)
- [Dokploy-Alternativen](https://pethost.dev/de/blog/dokploy-alternatives/)
- [Coolify-Alternativen](https://pethost.dev/de/blog/coolify-alternatives/)
- [Render-Alternativen](https://pethost.dev/de/blog/render-alternatives/)
- [Sliplane-Alternativen](https://pethost.dev/de/blog/sliplane-alternatives/)
