Deutsch
Menü der Doku

Doku zu Agent Sandboxes · Konzepte

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

Aktualisiert · 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 minDie letzte Aktivität: Sie läuft.
  2. 5 minPAUSED: RAM und Prozesse bleiben auf ihrem Server, zu 30 % des Preises.
  3. 30 minSTOPPED: Die Disk bleibt, die Prozesse enden, 0,03 $ pro GiB und Monat.
  4. NieGelö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:

FeldStandardWas passiert
pause_after_idle_seconds300Eine RUNNING-Sandbox wird PAUSED.
stop_after_idle_seconds1.800Eine RUNNING- oder PAUSED-Sandbox wird STOPPED.
delete_after_idle_seconds0, nieEine 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:

GrundWas er bedeutet
REQUESTEin Aufruf hat es verlangt.
IDLEEin Timer, oder ihr Server hatte zu wenig RAM oder Disk.
WAKEEin Aufruf, ein SSH-Login oder ein Port-Request hat sie fortgesetzt.
CRASHDie VM oder ihr Server ist ausgefallen, oder sie ist nicht gestartet. Nur ResumeSandbox startet sie wieder.
MAINTENANCEDie Maschine ihres Servers wurde neu gestartet: vorher pausiert, nicht abgerechnet, danach wieder laufend.
UNPAIDNichts bezahlt den Workspace: Abrechnung.

Werte je Einsatz

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

EinsatzPauseStoppLöschenwake_when_stoppedkeep_awake
Die Sitzung eines Agenten, etwa Claude Code in der Cloud300, der Standard0 oder 864000NeinBei langen Builds
Eine Sandbox pro Nutzer deiner KI-App60 bis 3001800, der Standard604800Wenn deine App ohne ResumeSandbox aufruftNein
Eine Vorschau, die schläft12002592000NeinNein
Ein Batch-Job oder ein Eval060600 oder DeleteSandbox am EndeNeinBeim 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 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.

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