Dokumentacja Agent Sandboxes · Pojęcia
Cykl życia sandboxa: automatyczne wstrzymanie, zatrzymanie i bezczynność
Sandbox zostawiony w spokoju wstrzymuje się po 5 minutach, zatrzymuje po 30 i nigdy nie jest usuwany, chyba że o to poprosisz. Decydują o tym trzy liczniki na jednym zegarze bezczynności, a każdy z nich możesz zmienić albo wyłączyć. Ta strona mówi, co liczy się jako aktywność, co robi każdy licznik i jakie wartości pasują do agenta, użytkowników aplikacji, podglądu i zadania wsadowego.
- Bezczynność to brak wywołań, strumieni, linków, sesji SSH, żądań do portów, tur agenta i poleceń z
keep_awake. Sam proces w tle się nie liczy: wstrzymuje się razem z sandboxem i wznawia tam, gdzie był. - Trzy liczniki:
pause_after_idle_seconds(300),stop_after_idle_seconds(1800) idelete_after_idle_seconds(wyłączony). Każdy wyłącza 0. - Długa praca, do której nikt nie wysyła wywołań, jak build albo zestaw testów, działa z
keep_awake, żeby sandbox nie wstrzymał się w jej trakcie. - Zatrzymany sandbox startuje ponownie przez
ResumeSandboxalbo przy następnym wywołaniu, gdy włączone jestwake_when_stopped. next_stateinext_state_timesandboxa mówią, co i kiedy zrobi z nim cykl życia.
Co liczy się jako aktywność
Sandbox jest bezczynny, dopóki nic się w nim nie dzieje. Każda z tych rzeczy nie pozwala mu zasnąć i gdy się kończy, zeruje jego zegar bezczynności:
- wywołanie API środowiska uruchomieniowego (polecenie, plik, pulpit, agent) albo jeden z jego otwartych strumieni;
- otwarty link: terminal albo podgląd pulpitu na żywo w przeglądarce;
- sesja SSH;
- żądanie do jednego z jego portów;
- tura agenta, która wciąż trwa;
- polecenie uruchomione z
keep_awake, dopóki się nie skończy.
Nie liczy się proces, który sam działa w tle: serwer deweloperski, zadanie uruchomione przez nohup, watcher. Gdy sandbox się wstrzymuje, taki proces zatrzymuje się tam, gdzie jest, i stamtąd rusza dalej, gdy sandbox się obudzi. Serwer nie potrzebuje niczego więcej: żądanie do jego portu budzi sandbox.
Domyślna oś czasu
- 0 minOstatnia aktywność: działa.
- 5 minPAUSED: pamięć i procesy zostają na jego serwerze, za 30% ceny.
- 30 minSTOPPED: dysk zostaje, procesy się kończą, 0,03 $ miesięcznie za GiB.
- NigdyUsuwasz go tylko ty albo jego licznik usunięcia.
Trzy liczniki
lifecycle sandboxa ma trzy liczniki, każdy to liczba sekund na tym samym zegarze bezczynności i każdy wyłącza 0:
| Pole | Domyślnie | Co się dzieje |
|---|---|---|
pause_after_idle_seconds | 300 | Sandbox RUNNING przechodzi w PAUSED. |
stop_after_idle_seconds | 1800 | Sandbox RUNNING albo PAUSED przechodzi w STOPPED. |
delete_after_idle_seconds | 0, nigdy | Sandbox w dowolnym stanie jest usuwany. |
Gdy licznik zatrzymania przychodzi nie później niż licznik wstrzymania, bezczynny sandbox RUNNING zatrzymuje się bez wstrzymania. Gdy oba są wyłączone, sandbox działa, dopóki go nie wstrzymasz, nie zatrzymasz albo nie usuniesz.
Cykl życia ustawiasz przy tworzeniu sandboxa albo później przez UpdateSandbox. Cykl życia to jedna grupa ustawień: wysłana grupa zastępuje całą grupę sandboxa, a pominięty licznik dostaje wartość domyślną. Wysyłaj więc każdy licznik, który chcesz ustawić. Każda odpowiedź niesie obowiązujące ustawienia z wpisanymi wartościami domyślnymi, więc to, co czytasz, możesz odesłać.
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}}}'
Długa praca: keep_awake
Build, zestaw testów albo trening może trwać minuty bez żadnego wywołania do sandboxa, a licznik wstrzymania wstrzymałby go w trakcie pracy. Uruchom takie polecenie z keep_awake: dopóki działa, sandbox nie wstrzymuje się z bezczynności i liczy się jako RUNNING. Daj mu też timeout_seconds, żeby polecenie, które się zawiesi, nie trzymało sandboxa na nogach w nieskończoność.
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'
Życie sandboxa nie ma limitu: sandbox trzymany na nogach działa i jest rozliczany, dopóki jego polecenie się nie skończy albo go nie zatrzymasz.
Budzenie zatrzymanego sandboxa: wake_when_stopped
Domyślnie sandbox STOPPED budzi się tylko przez ResumeSandbox. Wywołanie środowiska uruchomieniowego do niego odpowiada FAILED_PRECONDITION ze Stopped, a żądanie do jednego z jego portów odpowiada HTTP 503, „stopped: resume it”.
Z włączonym wake_when_stopped zatrzymany sandbox budzi się przy wywołaniu, logowaniu SSH albo żądaniu do portu, tak jak wstrzymany: w ok. 0,2 s, gdy jego dysk jest na serwerze, dłużej, gdy dysk wraca z magazynu obiektów, ok. 10 s na GiB własnych danych. Pasuje do projektu, który budzi się od czasu do czasu, jak endpoint webhooka albo sandbox, który twoja aplikacja wywołuje bez wcześniejszego wznowienia.
Kosztuje budżet, nie pieniądze: vCPU takiego sandboxa liczą się do twojego planu także wtedy, gdy jest zatrzymany, żeby zawsze miał miejsce na wybudzenie. Włączenie tej opcji dla zatrzymanego sandboxa jest odrzucane, gdy przestrzeni roboczej nie zostały wolne vCPU, a wyłączenie je zwalnia. Sandbox zatrzymany przez CRASH nigdy nie budzi się w ten sposób.
Samosprzątanie: delete_after_idle_seconds
Zatrzymany sandbox kosztuje tylko przechowywane bajty, ale kosztuje je co miesiąc. Dla sandboxów, do których nie wrócisz, ustaw delete_after_idle_seconds: po tak długiej bezczynności, w dowolnym stanie, sandbox jest usuwany razem z pamięcią i dyskiem. Jego wolumeny zostają. Jego zapis zostaje przez 30 dni, a zdarzenia i metryki przez dzień. Twój program może też wywołać DeleteSandbox, gdy skończy, i to jest najpewniejszy sposób.
Kiedy sandbox wstrzymuje się albo zatrzymuje wcześniej
Sandbox może wstrzymać się albo zatrzymać przed czasem z liczników, gdy jego serwerowi brakuje miejsca:
- Mało pamięci: sandbox RUNNING bezczynny od 1 minuty lub dłużej zostaje wcześniej wstrzymany. Jego
state_messagemówi „paused early: its server's memory ran short”. - Mało dysku: serwer zatrzymuje sandboxy PAUSED, które najdłużej są bezczynne, „stopped early: its server's disk ran short”, a w tym czasie wstrzymanie zamienia się w zatrzymanie, „stopped instead of paused”.
- Brak dysku: serwer zatrzymuje sandbox RUNNING, którego dysk urósł najbardziej, z powodem CRASH, „its server ran out of disk space”. Jego dysk zostaje.
Sandbox, który nie jest bezczynny, nigdy nie jest wcześniej wstrzymywany z braku pamięci.
Co dalej: next_state i powody
GetSandbox odpowiada z next_state i next_state_time: co cykl życia zrobi z sandboxem, jeśli wcześniej nic się nie wydarzy, PAUSED, STOPPED albo DELETED, i kiedy. Nie ma ich, gdy coś nie pozwala sandboxowi zasnąć, i gdy w jego stanie nie biegnie żaden licznik.
Każda zmiana stanu ma state_reason, a zdarzenia sandboxa pokazują te same powody:
| Powód | Co oznacza |
|---|---|
REQUEST | Poprosiło o to wywołanie. |
IDLE | Licznik albo brak pamięci lub dysku na jego serwerze. |
WAKE | Wznowiło go wywołanie, logowanie SSH albo żądanie do portu. |
CRASH | Jego maszyna wirtualna albo serwer uległy awarii albo nie wystartował. Ponownie uruchamia go tylko ResumeSandbox. |
MAINTENANCE | Maszyna jego serwera się zrestartowała: przedtem wstrzymany, bez opłat, a potem znów działa. |
UNPAID | Nic nie płaci za przestrzeń roboczą: rozliczenia. |
Wartości do zastosowań
To zalecenia, wyprowadzone z reguł powyżej. Liczniki są w sekundach, tak jak przyjmuje je API.
| Zastosowanie | Wstrzymanie | Zatrzymanie | Usunięcie | wake_when_stopped | keep_awake |
|---|---|---|---|---|---|
| Sesja agenta, np. Claude Code w chmurze | 300, domyślnie | 0 albo 86400 | 0 | Nie | Przy długich buildach |
| Sandbox na użytkownika twojej aplikacji AI | 60 do 300 | 1800, domyślnie | 604800 | Jeśli twoja aplikacja wywołuje bez ResumeSandbox | Nie |
| Podgląd, który zasypia | 120 | 0 | 2592000 | Nie | Nie |
| Zadanie wsadowe albo ewaluacja | 0 | 60 | 600 albo DeleteSandbox na końcu | Nie | Na poleceniu zadania |
Sandbox agenta, który nigdy się nie zatrzymuje, zachowuje swoje procesy, a dzień wstrzymania kosztuje 30% dnia działania. Podgląd bez licznika zatrzymania budzi się przy wizycie w ok. 0,2 s z serwerem deweloperskim tam, gdzie był. Rozliczenia wyliczają, ile kosztuje każdy z nich.
Gdy to nie działa
- Wstrzymał się w trakcie długiego buildu. Nic do niego nie wywoływało, a build to proces w tle. Uruchom build z
keep_awake. - Wywołanie odpowiada FAILED_PRECONDITION ze Stopped. Sandbox jest w stanie STOPPED. Wywołaj
ResumeSandboxalbo włączwake_when_stopped. - Port odpowiada 503, „stopped: resume it”. To samo, widziane z przeglądarki albo curl.
- Wywołanie odpowiada UNAVAILABLE z Restoring. Jego dysk wraca z magazynu obiektów, ok. 10 s na GiB. Poczekaj albo wywołaj ponownie
ResumeSandbox, żeby śledzić postęp. - Wstrzymał się przed czasem z licznika. Jego serwerowi zabrakło pamięci:
state_messageto mówi. Budzi się jak zwykle przy następnym wywołaniu.
Pytania
Czy proces w tle nie pozwala sandboxowi zasnąć?
Nie. Robią to tylko wywołania, otwarte strumienie i linki, sesje SSH, żądania do portów, trwające tury agenta i polecenia uruchomione z keep_awake. Proces w tle wstrzymuje się razem z sandboxem i rusza dalej, gdy ten się obudzi.
Jak sprawić, żeby sandbox nigdy się nie zatrzymywał?
Ustaw stop_after_idle_seconds na 0. W bezczynności dalej się wstrzymuje, co zachowuje jego procesy, i budzi się przy następnym wywołaniu.
Jak sprawić, żeby sandbox działał cały czas?
Ustaw pause_after_idle_seconds i stop_after_idle_seconds na 0, a będzie działał, dopóki go nie wstrzymasz, nie zatrzymasz albo nie usuniesz, po cenie działania.
Czy zatrzymany sandbox budzi się, gdy go wywołam?
Tylko z włączonym wake_when_stopped, a wtedy jego vCPU liczą się do twojego planu także wtedy, gdy jest zatrzymany. Inaczej uruchamia go ResumeSandbox.
Czy bezczynne sandboxy są usuwane automatycznie?
Domyślnie nie. Ustaw delete_after_idle_seconds albo wywołaj DeleteSandbox, gdy skończysz.
Wypróbuj Pethost Agent Sandboxes
Okres próbny na 7 dni z 1 $ zużycia i 4 vCPU, z kartą. Potem plan od 20 $ miesięcznie, który zawiera tyle samo zużycia.