---
title: "Lebenszyklus einer Sandbox: Auto-Pause, Auto-Stopp und Leerlauf | Pethost Agent Sandboxes"
description: "Wann eine Sandbox im Leerlauf pausiert, stoppt oder gelöscht wird: was als Aktivität zählt, die drei Timer, keep_awake, wake_when_stopped und Werte je Einsatz."
---

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

# Lebenszyklus einer Sandbox: Auto-Pause, Auto-Stopp und Leerlauf

Aktualisiert 22. November 2026 · 8 Min. Lesezeit

Eine Sandbox, die du in Ruhe lässt, pausiert nach 5 Minuten und stoppt nach 30, und sie wird nie gelöscht, außer du verlangst es. Das entscheiden drei Timer auf einer Leerlauf-Uhr, und jeden davon kannst du ändern oder abschalten. Diese Seite sagt, was als Aktivität zählt, was jeder Timer tut und welche Werte zu einem Agenten, zu den Nutzern einer App, zu einer Vorschau und zu einem Batch-Job passen.

**Kurz gesagt**

- **Leerlauf** heißt: kein Aufruf, kein Stream, kein Link, keine SSH-Sitzung, kein Port-Request, kein Turn eines Agenten und kein `keep_awake`-Befehl. Ein Hintergrundprozess allein zählt nicht: Er pausiert mit der Sandbox und macht dort weiter, wo er war.
- **Drei Timer:** `pause_after_idle_seconds` (300), `stop_after_idle_seconds` (1.800) und `delete_after_idle_seconds` (aus). Jeder ist mit 0 aus.
- **Lange Arbeit,** in die niemand hineinruft, etwa ein Build oder eine Testsuite, läuft mit `keep_awake`, damit die Sandbox nicht mittendrin pausiert.
- **Eine gestoppte Sandbox** startet wieder durch `ResumeSandbox` oder beim nächsten Aufruf, wenn `wake_when_stopped` an ist.
- `next_state` und `next_state_time` einer Sandbox sagen, was ihr Lebenszyklus als Nächstes tut, und wann.

## Was als Aktivität zählt

Eine Sandbox ist im Leerlauf, solange nichts in ihr passiert. Jedes davon hält sie wach und setzt ihre Leerlauf-Uhr zurück, wenn es endet:

- ein Aufruf der Runtime-API (ein Befehl, eine Datei, der Desktop, ein Agent) oder einer ihrer Streams, der offen bleibt;
- ein offener Link: ein Terminal oder eine Live-Ansicht des Desktops in einem Browser;
- eine SSH-Sitzung;
- ein Request an einen ihrer Ports;
- ein Turn eines Agenten, der noch läuft;
- ein Befehl, der mit `keep_awake` gestartet wurde, bis er endet.

Nicht zählt ein Prozess, der allein im Hintergrund läuft: ein Dev-Server, ein mit `nohup` gestarteter Job, ein Watcher. Pausiert die Sandbox, hält ein solcher Prozess an, wo er ist, und macht dort weiter, wenn die Sandbox aufwacht. Ein Server braucht nichts weiter: Ein Request an seinen Port weckt die Sandbox.

## Der Standard-Ablauf

1. **0 min**Die letzte Aktivität: Sie läuft.
2. **5 min**PAUSED: RAM und Prozesse bleiben auf ihrem Server, zu 30 % des Preises.
3. **30 min**STOPPED: Die Disk bleibt, die Prozesse enden, 0,03 $ pro GiB und Monat.
4. **Nie**Gelöscht nur von dir oder von ihrem Lösch-Timer.

Die Leerlauf-Uhr beginnt bei jeder Aktivität neu: Ein Aufruf in Minute 4 schiebt die Pause auf Minute 9.

## Die drei Timer

Der `lifecycle` einer Sandbox hat drei Timer, jeder eine Zahl von Sekunden auf derselben Leerlauf-Uhr, jeder mit 0 aus:

| Feld | Standard | Was passiert |
| --- | --- | --- |
| `pause_after_idle_seconds` | 300 | Eine RUNNING-Sandbox wird PAUSED. |
| `stop_after_idle_seconds` | 1.800 | Eine RUNNING- oder PAUSED-Sandbox wird STOPPED. |
| `delete_after_idle_seconds` | 0, nie | Eine Sandbox in jedem Zustand wird gelöscht. |

Kommt der Stopp-Timer nicht später als der Pause-Timer, stoppt eine RUNNING-Sandbox im Leerlauf, ohne zu pausieren. Sind beide aus, läuft eine Sandbox, bis du sie pausierst, stoppst oder löschst.

Setz den Lebenszyklus beim Erstellen einer Sandbox oder später mit `UpdateSandbox`. Der Lebenszyklus ist eine Gruppe von Einstellungen: Eine Gruppe, die du schickst, ersetzt die ganze Gruppe der Sandbox, und ein Timer, den du weglässt, nimmt seinen Standard. Schick also jeden Timer, den du setzen willst. Jede Antwort trägt die geltenden Einstellungen mit ausgefüllten Standards, also ist, was du liest, das, was du zurückschickst.

Python

```
from pethost.sandboxes import Lifecycle, SandboxSettings, Sandboxes

sandboxes = Sandboxes()  # The token: PETHOST_TOKEN.

sandbox = sandboxes.create_sandbox(
    settings=SandboxSettings(
        lifecycle=Lifecycle(
            pause_after_idle_seconds=300,  # pause after 5 idle minutes
            stop_after_idle_seconds=86400,  # stop after an idle day
        ),
    ),
)
print(sandbox.sandbox_id)
```

TypeScript

```
import { Sandboxes } from "pethost/sandboxes";

const sandboxes = new Sandboxes({ token: process.env.PETHOST_TOKEN! });

const sandbox = await sandboxes.createSandbox({
  settings: {
    lifecycle: { pauseAfterIdleSeconds: 300, stopAfterIdleSeconds: 86400 },
  },
});
console.log(sandbox.sandboxId);
```

Go

```
client := sandboxes.NewClient(sandboxes.Config{Token: os.Getenv("PETHOST_TOKEN")})

sandbox, err := client.CreateSandbox(ctx, &sandboxes.CreateSandboxRequest{
	Settings: &sandboxes.SandboxSettings{
		Lifecycle: &sandboxes.Lifecycle{
			PauseAfterIdleSeconds: new(uint32(300)),
			StopAfterIdleSeconds:  new(uint32(86400)),
		},
	},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(sandbox.SandboxID)
```

Rust

```
use pethost::sandboxes::{types::*, Client};

let sandboxes = Client::new(&std::env::var("PETHOST_TOKEN")?);
let sandbox = sandboxes
    .create_sandbox(CreateSandboxRequest {
        settings: Some(SandboxSettings {
            lifecycle: Some(Lifecycle {
                pause_after_idle_seconds: Some(300),
                stop_after_idle_seconds: Some(86400),
                ..Default::default()
            }),
            ..Default::default()
        }),
        ..Default::default()
    })
    .await?;
println!("{}", sandbox.sandbox_id);
```

CLI

```
pethost sandbox new --pause-after 5m --stop-after 24h
```

MCP

```
CreateSandbox {"settings": {"lifecycle": {"pause_after_idle_seconds": 300, "stop_after_idle_seconds": 86400}}}
```

HTTP

```
curl https://console.pethost.dev/pethost.sandboxes.v1.SandboxService/CreateSandbox \
  -H "Authorization: Bearer $PETHOST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"settings": {"lifecycle": {"pause_after_idle_seconds": 300, "stop_after_idle_seconds": 86400}}}'
```

## Lange Arbeit: keep_awake

Ein Build, eine Testsuite oder ein Trainingslauf kann Minuten ohne einen Aufruf in die Sandbox dauern, und der Pause-Timer würde sie mitten in der Arbeit pausieren. Starte einen solchen Befehl mit `keep_awake`: Solange er läuft, pausiert die Sandbox nicht wegen Leerlaufs und zählt als RUNNING. Gib ihm auch `timeout_seconds`, damit ein Befehl, der hängt, die Sandbox nicht für immer wach hält.

Python

```
command = sandboxes.run_command(
    sandbox.sandbox_id,
    command="npm ci && npm test",
    keep_awake=True,
    timeout_seconds=1800,
    wait_seconds=0,  # answer once it has started
)
print(command.command_id, command.state.name)
```

TypeScript

```
const command = await sandboxes.runCommand({
  sandboxId: sandbox.sandboxId,
  command: "npm ci && npm test",
  keepAwake: true,
  timeoutSeconds: 1800,
  waitSeconds: 0, // answer once it has started
});
console.log(command.commandId, command.state);
```

Go

```
command, err := client.RunCommand(ctx, &sandboxes.RunCommandRequest{
	SandboxID:      sandbox.SandboxID,
	Command:        "npm ci && npm test",
	KeepAwake:      true,
	TimeoutSeconds: 1800,
	WaitSeconds:    new(uint32(0)), // answer once it has started
})
```

Rust

```
let command = sandboxes
    .run_command(RunCommandRequest {
        sandbox_id: sandbox.sandbox_id.clone(),
        command: "npm ci && npm test".into(),
        keep_awake: true,
        timeout_seconds: 1800,
        wait_seconds: Some(0), // answer once it has started
        ..Default::default()
    })
    .await?;
```

CLI

```
pethost sandbox run k7f3q2xy0a1b2c3d -d --keep-awake --timeout 30m -- 'npm ci && npm test'
```

Das Leben einer Sandbox hat keine Obergrenze: Eine wach gehaltene läuft und wird abgerechnet, bis ihr Befehl endet oder du sie stoppst.

## Eine gestoppte Sandbox wecken: wake_when_stopped

Standardmäßig wacht eine STOPPED-Sandbox nur durch `ResumeSandbox` auf. Ein Runtime-Aufruf in sie antwortet `FAILED_PRECONDITION` mit `Stopped`, und ein Request an einen ihrer Ports antwortet mit HTTP 503, „stopped: resume it“.

Mit `wake_when_stopped` wacht eine gestoppte Sandbox bei einem Aufruf, einem SSH-Login oder einem Port-Request auf, wie eine pausierte: in etwa 0,2 s, solange ihre Disk auf ihrem Server liegt, länger, wenn die Disk aus dem Objektspeicher zurückkommt, etwa 10 s pro GiB ihrer eigenen Daten. Das passt zu einem Projekt, das ab und zu aufwacht, etwa dem Endpunkt eines Webhooks oder einer Sandbox, die deine App aufruft, ohne sie vorher fortzusetzen.

Es kostet Budget, kein Geld: Die vCPUs einer solchen Sandbox zählen auch im gestoppten Zustand gegen deinen Tarif, damit sie immer Platz zum Aufwachen hat. Es für eine gestoppte Sandbox einzuschalten wird abgelehnt, wenn der Workspace keine vCPUs mehr frei hat, und es auszuschalten gibt sie frei. Eine Sandbox, die ein CRASH gestoppt hat, wacht nie so auf.

## Von selbst aufräumen: delete_after_idle_seconds

Eine gestoppte Sandbox kostet nur ihre gespeicherten Bytes, aber die jeden Monat. Für Sandboxes, zu denen du nicht zurückkommst, setz `delete_after_idle_seconds`: Ist sie so lange im Leerlauf, in jedem Zustand, wird die Sandbox gelöscht, mit RAM und Disk. Die Volumes bleiben. Der Eintrag bleibt 30 Tage, ihre Events und Metriken einen Tag. Dein Programm kann auch `DeleteSandbox` aufrufen, wenn es fertig ist, was der sicherste Weg ist.

## Wenn eine Sandbox früher pausiert oder stoppt

Eine Sandbox kann pausieren oder stoppen, bevor ihre Timer es sagen, wenn ihr Server knapp an Platz wird:

- **RAM knapp:** Eine RUNNING-Sandbox, die 1 Minute oder länger im Leerlauf ist, wird früher pausiert. Die `state_message` sagt „paused early: its server's memory ran short“.
- **Disk knapp:** Der Server stoppt die PAUSED-Sandboxes, die am längsten im Leerlauf sind, „stopped early: its server's disk ran short“, und eine Pause wird währenddessen zum Stopp, „stopped instead of paused“.
- **Disk voll:** Der Server stoppt die RUNNING-Sandbox, deren Disk am meisten gewachsen ist, mit dem Grund CRASH, „its server ran out of disk space“. Die Disk bleibt.

Eine Sandbox, die nicht im Leerlauf ist, wird nie wegen RAM früher pausiert.

## Was als Nächstes passiert: next_state und die Gründe

`GetSandbox` antwortet mit `next_state` und `next_state_time`: was der Lebenszyklus als Nächstes mit der Sandbox tut, wenn vorher nichts passiert, PAUSED, STOPPED oder DELETED, und wann. Sie fehlen, solange etwas die Sandbox wach hält und wenn in ihrem Zustand kein Timer läuft.

Jeder Zustandswechsel hat einen `state_reason`, und die Events der Sandbox zeigen dieselben Gründe:

| Grund | Was er bedeutet |
| --- | --- |
| `REQUEST` | Ein Aufruf hat es verlangt. |
| `IDLE` | Ein Timer, oder ihr Server hatte zu wenig RAM oder Disk. |
| `WAKE` | Ein Aufruf, ein SSH-Login oder ein Port-Request hat sie fortgesetzt. |
| `CRASH` | Die VM oder ihr Server ist ausgefallen, oder sie ist nicht gestartet. Nur `ResumeSandbox` startet sie wieder. |
| `MAINTENANCE` | Die Maschine ihres Servers wurde neu gestartet: vorher pausiert, nicht abgerechnet, danach wieder laufend. |
| `UNPAID` | Nichts bezahlt den Workspace: [Abrechnung](https://pethost.dev/de/docs/sandboxes/billing/#unpaid). |

## Werte je Einsatz

Das sind Empfehlungen, gebaut aus den Regeln oben. Die Timer sind in Sekunden, wie die API sie nimmt.

| Einsatz | Pause | Stopp | Löschen | wake_when_stopped | keep_awake |
| --- | --- | --- | --- | --- | --- |
| Die Sitzung eines Agenten, etwa Claude Code in der Cloud | `300`, der Standard | `0` oder `86400` | `0` | Nein | Bei langen Builds |
| Eine Sandbox pro Nutzer deiner KI-App | `60` bis `300` | `1800`, der Standard | `604800` | Wenn deine App ohne `ResumeSandbox` aufruft | Nein |
| Eine Vorschau, die schläft | `120` | `0` | `2592000` | Nein | Nein |
| Ein Batch-Job oder ein Eval | `0` | `60` | `600` oder `DeleteSandbox` am Ende | Nein | Beim Befehl des Jobs |

Die Sandbox eines Agenten behält ihre Prozesse, wenn sie nie stoppt, und ein pausierter Tag kostet 30 % eines laufenden. Eine Vorschau ohne Stopp-Timer wacht bei einem Besuch in etwa 0,2 s auf, mit ihrem Dev-Server dort, wo er war. [Abrechnung](https://pethost.dev/de/docs/sandboxes/billing/#examples) rechnet aus, was jedes kostet.

## Wenn es nicht funktioniert

- **Sie hat während eines langen Builds pausiert.** Nichts hat in sie hineingerufen, und ein Build ist ein Hintergrundprozess. Führ den Build mit `keep_awake` aus.
- **Ein Aufruf antwortet FAILED_PRECONDITION mit Stopped.** Die Sandbox ist STOPPED. Ruf `ResumeSandbox` auf oder schalt `wake_when_stopped` ein.
- **Ein Port antwortet 503, „stopped: resume it“.** Dasselbe, aus einem Browser oder mit curl gesehen.
- **Ein Aufruf antwortet UNAVAILABLE mit Restoring.** Die Disk kommt aus dem Objektspeicher zurück, etwa 10 s pro GiB. Warte, oder ruf `ResumeSandbox` noch einmal auf, um zu verfolgen, wie weit es ist.
- **Sie hat vor ihrem Timer pausiert.** Der Server hatte zu wenig RAM: `state_message` sagt es. Sie wacht wie üblich beim nächsten Aufruf auf.

## Fragen

### Hält ein Hintergrundprozess eine Sandbox wach?

Nein. Das tun nur Aufrufe, offene Streams und Links, SSH-Sitzungen, Port-Requests, laufende Turns von Agenten und Befehle, die mit `keep_awake` gestartet wurden. Ein Hintergrundprozess pausiert mit der Sandbox und macht weiter, wenn sie aufwacht.

### Wie verhindere ich, dass eine Sandbox je stoppt?

Setz `stop_after_idle_seconds` auf 0. Sie pausiert im Leerlauf trotzdem, was ihre Prozesse behält, und wacht beim nächsten Aufruf auf.

### Wie lasse ich eine Sandbox die ganze Zeit laufen?

Setz `pause_after_idle_seconds` und `stop_after_idle_seconds` beide auf 0, und sie läuft, bis du sie pausierst, stoppst oder löschst, zu ihrem Preis im Betrieb.

### Wacht eine gestoppte Sandbox auf, wenn ich sie aufrufe?

Nur mit `wake_when_stopped`, und dann zählen ihre vCPUs auch im gestoppten Zustand gegen deinen Tarif. Sonst startet `ResumeSandbox` sie.

### Werden Sandboxes im Leerlauf automatisch gelöscht?

Standardmäßig nicht. Setz `delete_after_idle_seconds`, oder ruf `DeleteSandbox` auf, wenn du fertig bist.

[ZurückEinen Agenten über MCP mit Sandboxes verbinden](https://pethost.dev/de/docs/sandboxes/connect-an-agent/) [WeiterPreise und Abrechnung von Sandboxes: sekundengenau, je Zustand](https://pethost.dev/de/docs/sandboxes/billing/)

## 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/)
