Dokumentacja Agent Sandboxes · Pierwsze kroki
Jak działają Pethost Agent Sandboxes
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.
- 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:
| Rozmiar | vCPU | Pamięć | Dysk |
|---|---|---|---|
| SMALL | 2 | 4 GiB | 10 GiB |
| DEFAULT | 4 | 8 GiB | 20 GiB |
| LARGE | 8 | 16 GiB | 40 GiB |
| XLARGE | 16 | 32 GiB | 80 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
urljego 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
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
Na dysku swojego serwera
Zachowuje pamięć, procesy, dysk i swoje miejsce na serwerze.
0,0108 $ za godzinę, DEFAULT
30 min bezczynności albo StopSandbox
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
| Stan | Gdzie jest | Co zachowuje | Jak się budzi |
|---|---|---|---|
| RUNNING | W pamięci swojego serwera | Wszystko, w ruchu | Nie śpi |
| PAUSED | Na dysku swojego serwera | Pamięć, procesy, dysk | Przy następnym wywołaniu, logowaniu SSH albo żądaniu do portu, w ok. 0,1 s; nigdy nie jest odrzucany z braku miejsca |
| STOPPED | W magazynie obiektów i na dysku swojego serwera, dopóki jest miejsce | Swój dysk | Przez ResumeSandbox albo jak wstrzymany, z wake_when_stopped |
| DELETED | Nigdzie | Swó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
| Z | Do | Co go przenosi |
|---|---|---|
| RUNNING | PAUSED | Jego 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) |
| PAUSED | RUNNING | Dowolne wywołanie środowiska uruchomieniowego, logowanie SSH albo żądanie do portu (WAKE); ResumeSandbox |
| RUNNING albo PAUSED | STOPPED | Jego licznik zatrzymania; StopSandbox; brak dysku na jego serwerze (wstrzymany); przestrzeń robocza bez środków (UNPAID); awaria jego maszyny wirtualnej albo serwera (CRASH) |
| STOPPED | RUNNING | ResumeSandbox; wywołanie, logowanie SSH albo żądanie do portu tylko z wake_when_stopped, i nigdy po CRASH |
| Dowolny | DELETED | DeleteSandbox; 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_PRECONDITIONze szczegółemStopped; - żą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
| Co | Wstrzymanie | Zatrzymanie | Fork | Szablon | Usunięcie |
|---|---|---|---|---|---|
| Pamięć | Zostaje | Ginie | Skopiowana | Niezapisana | Usunięta |
| Działające procesy | Zostają | Kończą się | Skopiowane, działają | Niezapisane | Usunięte |
| Pliki i obrazy Dockera | Zostają | Zostają | Skopiowane | Zapisane | Usunięte |
| Rozmowy agentów | Zostają | Zostają | Skopiowane | Niezapisane | Usunię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.