Doku zu Agent Sandboxes · Konzepte
Lebenszyklus einer Sandbox: Auto-Pause, Auto-Stopp und Leerlauf
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.
- 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) unddelete_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
ResumeSandboxoder beim nächsten Aufruf, wennwake_when_stoppedan ist. next_stateundnext_state_timeeiner 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_awakegestartet 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
- 0 minDie letzte Aktivität: Sie läuft.
- 5 minPAUSED: RAM und Prozesse bleiben auf ihrem Server, zu 30 % des Preises.
- 30 minSTOPPED: Die Disk bleibt, die Prozesse enden, 0,03 $ pro GiB und Monat.
- NieGelöscht nur von dir oder von ihrem Lösch-Timer.
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.
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)
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);
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)
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);
pethost sandbox new --pause-after 5m --stop-after 24h
CreateSandbox {"settings": {"lifecycle": {"pause_after_idle_seconds": 300, "stop_after_idle_seconds": 86400}}}
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.
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)
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);
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
})
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?;
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_messagesagt „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. |
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 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_awakeaus. - Ein Aufruf antwortet FAILED_PRECONDITION mit Stopped. Die Sandbox ist STOPPED. Ruf
ResumeSandboxauf oder schaltwake_when_stoppedein. - 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
ResumeSandboxnoch einmal auf, um zu verfolgen, wie weit es ist. - Sie hat vor ihrem Timer pausiert. Der Server hatte zu wenig RAM:
state_messagesagt 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.