Polski
Menu dokumentacji

Dokumentacja Agent Sandboxes · Pierwsze kroki

Jak działają Pethost Agent Sandboxes

Zaktualizowano · 7 min czytania

Sandbox to maszyna wirtualna z Linuksem, którą twój kod albo twój agent uruchamia w ok. 0,15 s, używa przez API i zostawia w spokoju. Gdy nic się w nim nie dzieje, wstrzymuje się razem z pamięcią i procesami, a później zatrzymuje, zostawiając sam dysk. Następne wywołanie budzi go tam, gdzie był. Ta strona to model: czym jest sandbox, jego trzy stany, co przenosi go między nimi i gdzie leży każdy bajt.

W skrócie
  • MicroVM na każdy sandbox: Firecracker, własne jądro, root w środku, Ubuntu z Pythonem, Node.js, Dockerem, trzema agentami kodującymi i Chrome.
  • Trzy stany: RUNNING w pamięci swojego serwera, PAUSED na dysku swojego serwera z zachowaną pamięcią i procesami, STOPPED w magazynie obiektów z samym dyskiem.
  • Budzi się, gdy go używasz: każde wywołanie do wstrzymanego sandboxa, logowanie SSH albo żądanie do jednego z jego portów wznawia go w ok. 0,1 s.
  • Dwa API: panel trzyma zapis każdego sandboxa, a serwer sandboxa wykonuje to, co dzieje się w środku. SDK i CLI ukrywają tę różnicę.
  • Rozliczanie co do sekundy za każdy stan: rozliczenia.

Czym jest sandbox

Sandbox to jedna maszyna wirtualna, zrobiona z szablonu. W środku jesteś rootem, a polecenia działają jako użytkownik user, który ma sudo bez hasła, w /home/user. Nazwa hosta to jego id: 16 znaków, małe litery i cyfry.

Nasz szablon, base, ma Ubuntu 24.04 z narzędziami do budowania i gitem, Pythona 3, Node.js 22, Dockera, agentów kodujących Claude Code, Codex i OpenCode oraz pulpit z Google Chrome. Dwie z tych rzeczy startują dopiero przy pierwszym użyciu i do tego czasu nic nie kosztują: pulpit, przy pierwszym zrzucie ekranu albo linku do pulpitu (kilka sekund), i demon Dockera, przy pierwszym połączeniu z /var/run/docker.sock.

Izolacja: osobna microVM Firecracker

Każdy sandbox to osobna microVM Firecracker z własnym jądrem Linuksa. Firecracker uruchamia każdą maszynę wirtualną w swoim jailerze: z własnym chrootem, nieuprzywilejowanym użytkownikiem, cgroup, filtrem seccomp i własną przestrzenią nazw sieci. System gościa jest twój, łącznie z rootem i jądrem; co dostaje, decyduje host.

  • Rozmiaru pilnuje host. Maszyna wirtualna dostaje od serwera vCPU i pamięć swojego rozmiaru i nic, co powie gość, tego nie zmienia.
  • Własna tożsamość. Każdy sandbox dostaje świeżą losowość jądra, własną nazwę hosta i własny machine-id, nawet gdy startuje z tego samego snapshotu co inny.
  • Żadnych sekretów w środku. Sekrety przestrzeni roboczej nigdy nie trafiają do maszyny wirtualnej, tokeny API też nie: do sandboxa łączysz się tokenem tylko dla niego, który wygasa.

Rozmiary

Sandbox ma jeden z czterech rozmiarów, przez całe życie swojej maszyny wirtualnej:

RozmiarvCPUPamięćDysk
SMALL24 GiB10 GiB
DEFAULT48 GiB20 GiB
LARGE816 GiB40 GiB
XLARGE1632 GiB80 GiB

Dysk to miejsce, które sandbox może zapisać: pliki samego szablonu się do niego nie liczą. Nowy rozmiar (UpdateSandbox) restartuje sandbox w stanie RUNNING w maszynie wirtualnej tego rozmiaru, z zachowanymi plikami i zakończonymi procesami; sandbox STOPPED dostaje nowy rozmiar przy następnym starcie, a PAUSED trzeba najpierw wznowić albo zatrzymać. Nowy rozmiar zachowuje dysk, chyba że ustawisz grow_disk, który powiększa go do dysku nowego rozmiaru. Dysk nigdy się nie zmniejsza.

Szablony

Szablon to pliki, z którymi sandbox startuje. Nasz to base, przebudowywany co miesiąc i od razu przy poprawce bezpieczeństwa. Twój to dysk sandboxa zapisany przez CreateTemplate: jego pliki, zainstalowane przez ciebie pakiety i jego obrazy Dockera. Szablon nie zachowuje pamięci, procesów ani rozmów agentów: sandbox z niego zrobiony startuje od zera.

Każdy zapis to nowa wersja, name@1, name@2, a sandbox uruchomiony z name bierze najnowszą. Każdy serwer uruchamia sandboxy z dowolnej wersji. min_size wersji to najmniejszy rozmiar, którego dysk mieści to, co zapisała. Sandbox z twojego szablonu startuje w ok. 0,22 s, gdy jego serwer ma już tę wersję; pierwszy na każdym serwerze ją pobiera, ok. 10 s na GiB: szablony.

Dwa API: panel i serwer sandboxa

Odpowiadają dwie usługi, każda według tego, co wie:

  • SandboxService to panel, pod https://console.pethost.dev, wywoływany twoim tokenem API. Trzyma przestrzeń roboczą i każdy sandbox jako zapis: tworzenie, ustawienia, wstrzymanie, wznowienie, fork, usuwanie, szablony, wolumeny, zdarzenia i zużycie.
  • SandboxRuntimeService to serwer samego sandboxa, pod url jego połączenia, wywoływany tokenem połączenia tylko dla tego sandboxa. Wykonuje to, co dzieje się w środku: polecenia, pliki, pulpit, agentów kodujących i linki.

SDK i CLI łączą się za ciebie: run_command to jedno wywołanie, a SDK samo znajduje serwer i odświeża token. Wywołania środowiska uruchomieniowego idą prosto do serwera, więc panel nigdy nie stoi na drodze tego, co działa w sandboxie, a serwer prowadzi swoje sandboxy bez panelu.

Trzy stany

RUNNING

W pamięci swojego serwera

Wykonuje twoje procesy i odpowiada na każde wywołanie.

0,036 $ za godzinę, DEFAULT

5 min bezczynności albo PauseSandbox

Dowolne wywołanie, logowanie SSH albo żądanie do portu, w ok. 0,1 s

PAUSED

Na dysku swojego serwera

Zachowuje pamięć, procesy, dysk i swoje miejsce na serwerze.

0,0108 $ za godzinę, DEFAULT

30 min bezczynności albo StopSandbox

STOPPED

W magazynie obiektów

Zachowuje dysk; jego procesy się kończą.

0,03 $ miesięcznie za GiB własnych danych

ResumeSandbox uruchamia go ponownie: ok. 0,2 s, gdy jego dysk jest na serwerze, ok. 10 s na GiB z magazynu obiektów

Domyślne liczniki, liczone od ostatniej rzeczy, która wydarzyła się w sandboxie. Sandbox RUNNING można też zatrzymać od razu, a każdy sandbox można usunąć.
StanGdzie jestCo zachowujeJak się budzi
RUNNINGW pamięci swojego serweraWszystko, w ruchuNie śpi
PAUSEDNa dysku swojego serweraPamięć, procesy, dyskPrzy następnym wywołaniu, logowaniu SSH albo żądaniu do portu, w ok. 0,1 s; nigdy nie jest odrzucany z braku miejsca
STOPPEDW magazynie obiektów i na dysku swojego serwera, dopóki jest miejsceSwój dyskPrzez ResumeSandbox albo jak wstrzymany, z wake_when_stopped
DELETEDNigdzieSwój zapis przez 30 dni, zdarzenia i metryki przez dzieńNigdy

Po co jest PAUSED

Maszyna wirtualna agenta przez większość czasu czeka: aż model pomyśli, aż człowiek przeczyta odpowiedź, na następną wiadomość. Zatrzymanie jej kończy procesy, a z nimi serwer deweloperski, REPL, stan powłoki i otwartą przeglądarkę, których agent używał. Trzymanie jej w stanie RUNNING to płacenie pełnej ceny za czekanie.

PAUSED zachowuje wszystko, łącznie z pamięcią i procesami, za 30% ceny działania, a serwer trzyma miejsce sandboxa, więc wznowienie nigdy nie jest odrzucane z braku miejsca. Twój kod nie musi go budzić: następne wywołanie do sandboxa najpierw go wznawia, w ok. 0,1 s, a potem wykonuje się tak, jakby sandbox nigdy się nie zatrzymał. Wznowienie wstrzymanego sandboxa zajmuje na jego serwerze 41 ms, a polecenie wysłane do niego odpowiada w ok. 80 ms.

Co zmienia stan sandboxa

ZDoCo go przenosi
RUNNINGPAUSEDJego licznik wstrzymania; PauseSandbox; brak pamięci na jego serwerze, gdy jest bezczynny od minuty; restart maszyny jego serwera (MAINTENANCE, za który nic nie liczymy)
PAUSEDRUNNINGDowolne wywołanie środowiska uruchomieniowego, logowanie SSH albo żądanie do portu (WAKE); ResumeSandbox
RUNNING albo PAUSEDSTOPPEDJego licznik zatrzymania; StopSandbox; brak dysku na jego serwerze (wstrzymany); przestrzeń robocza bez środków (UNPAID); awaria jego maszyny wirtualnej albo serwera (CRASH)
STOPPEDRUNNINGResumeSandbox; wywołanie, logowanie SSH albo żądanie do portu tylko z wake_when_stopped, i nigdy po CRASH
DowolnyDELETEDDeleteSandbox; jego licznik usunięcia; utrata jego serwera, dla sandboxa bez kopii w magazynie obiektów

Każda zmiana ma powód, state_reason, i słowa dla ludzi, state_message. Cykl życia i bezczynność mówi, co liczy się jako aktywność i jak ustawić liczniki.

Co budzi sandbox

Każde wywołanie SandboxRuntimeService, logowanie SSH albo żądanie do jednego z jego portów najpierw wznawia sandbox PAUSED, na jego własnym serwerze. Sandbox STOPPED budzi się tak tylko wtedy, gdy jego cykl życia ma wake_when_stopped. Bez tego:

  • wywołanie środowiska uruchomieniowego odpowiada FAILED_PRECONDITION ze szczegółem Stopped;
  • żądanie do portu odpowiada HTTP 503, „stopped: resume it”;
  • uruchamia go tylko ResumeSandbox.

Sandbox zatrzymany przez CRASH startuje ponownie tylko przez ResumeSandbox. Gdy dysk zatrzymanego sandboxa wraca z magazynu obiektów, wywołania do niego odpowiadają UNAVAILABLE z Restoring, a ResumeSandbox czeka do 45 s, po czym mówi, jak daleko jest pobieranie (Sandbox.restore).

Gdzie są twoje dane

CoWstrzymanieZatrzymanieForkSzablonUsunięcie
PamięćZostajeGinieSkopiowanaNiezapisanaUsunięta
Działające procesyZostająKończą sięSkopiowane, działająNiezapisaneUsunięte
Pliki i obrazy DockeraZostająZostająSkopiowaneZapisaneUsunięte
Rozmowy agentówZostająZostająSkopiowaneNiezapisaneUsunięte

Dysk zatrzymanego sandboxa trafia do magazynu obiektów w UE minutę po zatrzymaniu, w kawałkach zaszyfrowanych kluczem tylko dla tego sandboxa; pamięć nigdy tam nie trafia. Jego serwer trzyma własną kopię, dopóki ma miejsce. Z wolumenem jest inaczej: leży na dysku jednego serwera i nie jest nigdzie kopiowany, więc to, co musi przetrwać utratę serwera, trzymaj też gdzie indziej.

Przeprowadzki i utracone serwery

Sandbox STOPPED z aktualną kopią i bez wolumenu startuje na innym serwerze, gdy na jego własnym nie ma dla niego miejsca, a jego adresy przenoszą się razem z nim: url połączenia, URL-e jego portów i jego ssh_command. Sandbox PAUSED nigdy się nie przenosi: wznawia się na serwerze, który trzyma jego pamięć.

Gdy serwer przepadnie, każdy jego sandbox z kopią staje się STOPPED ze swojej ostatniej kopii i startuje na innym serwerze przy następnym ResumeSandbox. Sandbox bez kopii jest usuwany, tak jak wolumeny na tym serwerze.

Pytania

Czy sandbox to kontener?

Nie. Każdy sandbox to microVM Firecracker z własnym jądrem Linuksa, a w środku jesteś rootem. W sandboxie możesz uruchamiać kontenery Dockera.

Co dzieje się z moimi procesami, gdy sandbox się wstrzymuje?

Zatrzymują się tam, gdzie są, i zachowują pamięć, otwarte pliki i stan. Następne wywołanie, logowanie SSH albo żądanie do portu wznawia je w ok. 0,1 s, jakby nic się nie stało.

Czy wstrzymany sandbox może się nie obudzić z braku miejsca?

Nie. Jego serwer trzyma jego miejsce, dopóki jest wstrzymany, więc wznowienie nigdy nie jest odrzucane z braku miejsca. Zatrzymany może: wtedy ResumeSandbox może uruchomić go na innym serwerze.

Gdzie są moje pliki, gdy sandbox jest zatrzymany?

Na jego dysku, skopiowanym do magazynu obiektów w UE i zaszyfrowanym kluczem dla tego sandboxa, oraz na jego serwerze, dopóki jest miejsce. Wracają takie, jakie były, gdy sandbox się wznowi.

Czy szablon zachowuje działające procesy?

Nie. Szablon zapisuje tylko dysk: pliki, pakiety i obrazy Dockera. Sandbox z niego zrobiony startuje od zera, bez procesów i rozmów agentów tego, z którego go zapisano. Żeby skopiować działający sandbox, zrób jego fork.

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