Polski
Menu dokumentacji

Dokumentacja Agent Sandboxes · Pojęcia

Cykl życia sandboxa: automatyczne wstrzymanie, zatrzymanie i bezczynność

Zaktualizowano · 7 min czytania

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.

W skrócie
  • 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) i delete_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 ResumeSandbox albo przy następnym wywołaniu, gdy włączone jest wake_when_stopped.
  • next_state i next_state_time sandboxa 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

  1. 0 minOstatnia aktywność: działa.
  2. 5 minPAUSED: pamięć i procesy zostają na jego serwerze, za 30% ceny.
  3. 30 minSTOPPED: dysk zostaje, procesy się kończą, 0,03 $ miesięcznie za GiB.
  4. NigdyUsuwasz go tylko ty albo jego licznik usunięcia.
Zegar bezczynności rusza od nowa przy każdej aktywności: wywołanie w 4. minucie odsuwa wstrzymanie do 9. minuty.

Trzy liczniki

lifecycle sandboxa ma trzy liczniki, każdy to liczba sekund na tym samym zegarze bezczynności i każdy wyłącza 0:

PoleDomyślnieCo się dzieje
pause_after_idle_seconds300Sandbox RUNNING przechodzi w PAUSED.
stop_after_idle_seconds1800Sandbox RUNNING albo PAUSED przechodzi w STOPPED.
delete_after_idle_seconds0, nigdySandbox 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ć.

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}}}'

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ść.

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'

Ż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_message mó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ódCo oznacza
REQUESTPoprosiło o to wywołanie.
IDLELicznik albo brak pamięci lub dysku na jego serwerze.
WAKEWznowiło go wywołanie, logowanie SSH albo żądanie do portu.
CRASHJego maszyna wirtualna albo serwer uległy awarii albo nie wystartował. Ponownie uruchamia go tylko ResumeSandbox.
MAINTENANCEMaszyna jego serwera się zrestartowała: przedtem wstrzymany, bez opłat, a potem znów działa.
UNPAIDNic 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.

ZastosowanieWstrzymanieZatrzymanieUsunięciewake_when_stoppedkeep_awake
Sesja agenta, np. Claude Code w chmurze300, domyślnie0 albo 864000NiePrzy długich buildach
Sandbox na użytkownika twojej aplikacji AI60 do 3001800, domyślnie604800Jeśli twoja aplikacja wywołuje bez ResumeSandboxNie
Podgląd, który zasypia12002592000NieNie
Zadanie wsadowe albo ewaluacja060600 albo DeleteSandbox na końcuNieNa 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 ResumeSandbox albo włącz wake_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_message to 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.

Zacznij okres próbny