---
title: "Jak działają Pethost Agent Sandboxes | Pethost Agent Sandboxes"
description: "Czym jest sandbox, jego trzy stany RUNNING, PAUSED i STOPPED, co go budzi, dwa API oraz gdzie są jego pamięć, procesy i pliki."
---

[Dokumentacja Agent Sandboxes](https://pethost.dev/pl/docs/sandboxes/) · Pierwsze kroki

# Jak działają Pethost Agent Sandboxes

Zaktualizowano 21 listopada 2026 · 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](https://pethost.dev/pl/docs/sandboxes/billing/).

## 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](https://pethost.dev/pl/docs/sandboxes/templates/).

## 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ąć.

| 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ść](https://pethost.dev/pl/docs/sandboxes/lifecycle/) 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

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

[PoprzedniaDokumentacja Pethost Agent Sandboxes](https://pethost.dev/pl/docs/sandboxes/) [NastępnaSzybki start: twój pierwszy sandbox](https://pethost.dev/pl/docs/sandboxes/quickstart/)

## 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](https://console.pethost.dev/)

Pethost · Stephan Gomer · NIP 1133096755

Pethost

- [Szablony](https://pethost.dev/pl/templates/)
- [O nas](https://pethost.dev/about/)
- [Dokumentacja](https://pethost.dev/docs/)
- [Blog](https://pethost.dev/pl/blog/)
- [API](https://pethost.dev/docs/api/)
- [CLI](https://pethost.dev/docs/cli/)
- [Plugin](https://github.com/pethost-dev/plugin)
- [Regulamin](https://pethost.dev/terms/)
- [Prywatność](https://pethost.dev/privacy/)
- [Zwroty](https://pethost.dev/refunds/)
- [support@pethost.dev](mailto:support@pethost.dev)

Bazy danych

- [Postgres](https://pethost.dev/pl/postgres/)
- [Valkey](https://pethost.dev/pl/valkey/)

Agent Sandboxes

- [Sandboxy](https://pethost.dev/pl/sandboxes/)
- [Cennik](https://pethost.dev/pl/sandboxes/#pricing)
- [Dokumentacja](https://pethost.dev/pl/docs/sandboxes/)
- [API](https://pethost.dev/docs/sandboxes/api/)

Porównania

- [Coolify vs Dokploy vs CapRover vs Dokku](https://pethost.dev/pl/blog/coolify-vs-dokploy-vs-caprover-vs-dokku/)
- [Coolify Cloud vs Dokploy Cloud](https://pethost.dev/pl/blog/coolify-cloud-vs-dokploy-cloud/)
- [Cennik Railway vs Render vs Fly.io](https://pethost.dev/pl/blog/railway-vs-render-vs-fly-io-pricing/)
- [Zarządzany hosting Docker Compose](https://pethost.dev/pl/blog/managed-docker-compose-hosting/)

Alternatywy

- [Alternatywy dla Railway](https://pethost.dev/pl/blog/railway-alternatives/)
- [Alternatywy dla Heroku](https://pethost.dev/pl/blog/heroku-alternatives/)
- [Alternatywy dla Dokploy](https://pethost.dev/pl/blog/dokploy-alternatives/)
- [Alternatywy dla Coolify](https://pethost.dev/pl/blog/coolify-alternatives/)
- [Alternatywy dla Render](https://pethost.dev/pl/blog/render-alternatives/)
- [Alternatywy dla Sliplane](https://pethost.dev/pl/blog/sliplane-alternatives/)
