---
title: "Як працюють Pethost Agent Sandboxes | Pethost Agent Sandboxes"
description: "Що таке пісочниця, її три стани RUNNING, PAUSED і STOPPED, що її будить, два API і де лежать її пам’ять, процеси й файли."
---

[Документація Agent Sandboxes](https://pethost.dev/uk/docs/sandboxes/) · Початок

# Як працюють Pethost Agent Sandboxes

Оновлено 21 листопада 2026 р. · 7 хв читання

Пісочниця — це ВМ Linux, яку ваш код чи ваш агент запускає приблизно за 0,15 с, використовує через API і лишає в спокої. Коли в ній нічого не відбувається, вона стає на паузу разом із пам’яттю й процесами, а згодом зупиняється, зберігши лише диск. Наступний виклик будить її там, де вона була. Ця сторінка — модель: що таке пісочниця, її три стани, що переводить її з одного в інший і де лежить кожен байт.

**Коротко**

- **microVM на кожну пісочницю:** Firecracker, власне ядро, root усередині, Ubuntu з Python, Node.js, Docker, трьома агентами для коду й Chrome.
- **Три стани:** RUNNING у пам’яті свого сервера, PAUSED на диску свого сервера зі збереженими пам’яттю й процесами, STOPPED в об’єктному сховищі лише з диском.
- **Пробудження від використання:** будь-який виклик у пісочницю на паузі, вхід по SSH або запит до одного з її портів продовжує її приблизно за 0,1 с.
- **Два API:** панель зберігає запис про кожну пісочницю, а власний сервер пісочниці виконує те, що відбувається всередині. SDK і CLI приховують цю різницю.
- **Посекундна оплата** кожного стану: [оплата](https://pethost.dev/uk/docs/sandboxes/billing/).

## Що таке пісочниця

Пісочниця — це одна віртуальна машина, створена із шаблону. Усередині ви root, а команди виконуються від імені користувача `user`, у якого є sudo без пароля, у `/home/user`. Її ім’я хоста — її id: 16 символів, малі літери й цифри.

Наш шаблон, `base`, містить Ubuntu 24.04 з інструментами збирання й git, Python 3, Node.js 22, Docker, агентів для коду Claude Code, Codex і OpenCode, а також робочий стіл із Google Chrome. Дві з цих речей запускаються лише з першим використанням і доти нічого не коштують: робочий стіл — з першим скриншотом або посиланням на робочий стіл (кілька секунд), а демон Docker — з першим підключенням до `/var/run/docker.sock`.

## Ізоляція: окрема microVM Firecracker

Кожна пісочниця — окрема microVM Firecracker із власним ядром Linux. Firecracker запускає кожну ВМ у своєму jailer: власний chroot, непривілейований користувач, cgroup, фільтр seccomp і власний мережевий простір імен. Гостьова система ваша, разом із root і ядром; що вона отримує, вирішує хост.

- **Розмір тримає хост.** ВМ отримує від сервера vCPU і пам’ять свого розміру, і ніщо, що каже гостьова система, цього не змінює.
- **Власна ідентичність.** Кожна пісочниця отримує свіжу випадковість ядра, власне ім’я хоста й власний machine-id, навіть якщо стартує з того самого знімка, що й інша.
- **Жодних секретів усередині.** Секрети робочого простору ніколи не потрапляють у ВМ, як і API-токени: до пісочниці звертаються з токеном лише для неї, який спливає.

## Розміри

Пісочниця має один із чотирьох розмірів на все життя своєї ВМ:

| Розмір | vCPU | Пам’ять | Диск |
| --- | --- | --- | --- |
| SMALL | 2 | 4 GiB | 10 GiB |
| DEFAULT | 4 | 8 GiB | 20 GiB |
| LARGE | 8 | 16 GiB | 40 GiB |
| XLARGE | 16 | 32 GiB | 80 GiB |

Диск — це те, що пісочниця може записати: власні файли шаблону в нього не рахуються. Новий розмір (`UpdateSandbox`) перезапускає пісочницю RUNNING у ВМ цього розміру, зі збереженими файлами й завершеними процесами; пісочниця STOPPED отримує новий розмір під час наступного запуску, а пісочницю PAUSED спершу треба продовжити або зупинити. Новий розмір зберігає диск, якщо ви не задасте `grow_disk`, що збільшує його до диска нового розміру. Диск ніколи не зменшується.

## Шаблони

Шаблон — це файли, з якими стартує пісочниця. Наш — `base`, його перезбирають щомісяця, а для виправлення безпеки — одразу. Ваш — це диск пісочниці, збережений через `CreateTemplate`: її файли, встановлені вами пакети й образи Docker. Шаблон не зберігає пам’яті, процесів і розмов агентів: пісочниця з нього завантажується начисто.

Кожне збереження — нова версія, `name@1`, `name@2`, а пісочниця, запущена з `name`, бере найновішу. Кожен сервер запускає пісочниці з будь-якої версії. `min_size` версії — найменший розмір, чий диск уміщує те, що вона зберегла. Пісочниця з вашого шаблону запускається приблизно за 0,22 с, щойно її сервер має цю версію; перша на кожному сервері звантажує її, приблизно 10 с на GiB: [шаблони](https://pethost.dev/uk/docs/sandboxes/templates/).

## Два API: панель і сервер пісочниці

Відповідають два сервіси, за тим, що кожен знає:

- **SandboxService** — це панель, за адресою `https://console.pethost.dev`, яку викликають із вашим API-токеном. Вона зберігає робочий простір і кожну пісочницю як запис: створення, налаштування, пауза, продовження, копіювання, видалення, шаблони, томи, події й використання.
- **SandboxRuntimeService** — це власний сервер пісочниці, за `url` її з’єднання, який викликають із токеном з’єднання лише для цієї пісочниці. Він виконує те, що відбувається всередині: команди, файли, робочий стіл, агентів для коду й посилання.

SDK і CLI підключаються за вас: `run_command` — один виклик, а SDK сам знаходить сервер і оновлює токен. Виклики середовища виконання йдуть прямо на сервер, тож панель ніколи не стоїть на шляху того, що працює в пісочниці, а сервер виконує свої пісочниці без панелі.

## Три стани

**RUNNING**

У пам’яті свого сервера

Виконує ваші процеси й відповідає на кожен виклик.

0,036 $ на годину, DEFAULT

5 хв простою або PauseSandbox

Будь-який виклик, вхід по SSH чи запит до порту, приблизно за 0,1 с

**PAUSED**

На диску свого сервера

Зберігає пам’ять, процеси, диск і своє місце на сервері.

0,0108 $ на годину, DEFAULT

30 хв простою або StopSandbox

**STOPPED**

В об’єктному сховищі

Зберігає диск; процеси завершуються.

0,03 $ за GiB власних даних на місяць

ResumeSandbox завантажує її знову: приблизно за 0,2 с, якщо диск на сервері, і приблизно 10 с на GiB з об’єктного сховища

Типові таймери, від останньої події в пісочниці. Пісочницю RUNNING можна також зупинити одразу, а будь-яку пісочницю — видалити.

| Стан | Де вона | Що зберігає | Як прокидається |
| --- | --- | --- | --- |
| RUNNING | Пам’ять свого сервера | Усе, і все працює | Вона не спить |
| PAUSED | Диск свого сервера | Пам’ять, процеси, диск | Від наступного виклику, входу по SSH чи запиту до порту, приблизно за 0,1 с; ніколи не відхиляється через брак місця |
| STOPPED | Об’єктне сховище, а також диск свого сервера, поки є місце | Свій диск | Через `ResumeSandbox` або як пісочниця на паузі, з `wake_when_stopped` |
| DELETED | Ніде | Свій запис 30 днів, події й метрики — добу | Ніколи |

## Навіщо потрібен PAUSED

ВМ агента здебільшого чекає: поки модель думає, поки людина читає відповідь, поки прийде наступне повідомлення. Зупинка завершує її процеси, а з ними сервер розробки, REPL, стан оболонки й відкритий браузер, яким користувався агент. Тримати її в RUNNING означає платити повну ціну за очікування.

PAUSED зберігає все, разом із пам’яттю й процесами, за 30% ціни роботи, а сервер тримає місце пісочниці, тож продовження ніколи не відхиляють через брак місця. Вашому коду не треба нічого робити, щоб її розбудити: наступний виклик у пісочницю спершу продовжує її, приблизно за 0,1 с, а потім виконується так, ніби пісочниця й не зупинялася. Пісочниця на паузі продовжується на своєму сервері за 41 ms, а команда, надіслана в неї, відповідає приблизно за 80 ms.

## Що переводить пісочницю з одного стану в інший

| З | У | Що її переводить |
| --- | --- | --- |
| RUNNING | PAUSED | Її таймер паузи; `PauseSandbox`; брак пам’яті на її сервері, якщо вона простоює хвилину; перезапуск машини її сервера (MAINTENANCE, що нічого не рахує) |
| PAUSED | RUNNING | Будь-який виклик середовища виконання, вхід по SSH або запит до порту (WAKE); `ResumeSandbox` |
| RUNNING або PAUSED | STOPPED | Її таймер зупинки; `StopSandbox`; брак диска на її сервері (для пісочниці на паузі); робочий простір, якому нічим платити (UNPAID); збій її ВМ або сервера (CRASH) |
| STOPPED | RUNNING | `ResumeSandbox`; виклик, вхід по SSH чи запит до порту лише з `wake_when_stopped` і ніколи після CRASH |
| Будь-який | DELETED | `DeleteSandbox`; її таймер видалення; втрата її сервера, якщо в об’єктному сховищі немає її копії |

Кожна зміна має причину, `state_reason`, і слова для людей, `state_message`. [Життєвий цикл і простій](https://pethost.dev/uk/docs/sandboxes/lifecycle/) пояснює, що вважається активністю і як задавати таймери.

## Що будить пісочницю

Будь-який виклик SandboxRuntimeService, вхід по SSH або запит до одного з її портів спершу продовжує пісочницю PAUSED на її сервері. Пісочниця STOPPED прокидається так лише тоді, коли її життєвий цикл каже `wake_when_stopped`. Без цього:

- виклик середовища виконання відповідає `FAILED_PRECONDITION` з деталлю `Stopped`;
- запит до порту відповідає HTTP 503, «stopped: resume it»;
- запускає її лише `ResumeSandbox`.

Пісочниця, зупинена через CRASH, запускається знову лише через `ResumeSandbox`. Поки диск зупиненої пісочниці повертається з об’єктного сховища, виклики в неї відповідають `UNAVAILABLE` з `Restoring`, а `ResumeSandbox` чекає до 45 с, а потім каже, наскільки просунулося повернення (`Sandbox.restore`).

## Де лежать ваші дані

| Що | Пауза | Зупинка | Копія | Шаблон | Видалення |
| --- | --- | --- | --- | --- | --- |
| Пам’ять | Зберігається | Втрачається | Копіюється | Не зберігається | Зникає |
| Запущені процеси | Зберігаються | Завершуються | Копіюються й працюють | Не зберігаються | Зникають |
| Файли й образи Docker | Зберігаються | Зберігаються | Копіюються | Зберігаються | Зникають |
| Розмови агентів | Зберігаються | Зберігаються | Копіюються | Не зберігаються | Зникають |

Диск зупиненої пісочниці копіюється в об’єктне сховище в ЄС через хвилину після зупинки, частинами, зашифрованими ключем лише для цієї пісочниці; пам’ять туди ніколи не копіюється. Її сервер тримає власну копію, поки має місце. Том — інша справа: він лежить на диску одного сервера й нікуди не копіюється, тож те, що має пережити втрату сервера, тримайте ще й деінде.

## Переїзди й утрачені сервери

Пісочниця STOPPED з актуальною копією й без тому запускається на іншому сервері, коли на її власному немає для неї місця, і її адреси переїжджають разом із нею: `url` з’єднання, URL її портів і її `ssh_command`. Пісочниця PAUSED ніколи не переїжджає: вона продовжується на сервері, що тримає її пам’ять.

Якщо сервер утрачено, кожна його пісочниця з копією стає STOPPED з останньої копії й запускається на іншому сервері під час наступного `ResumeSandbox`. Пісочниця без копії видаляється, як і томи на цьому сервері.

## Запитання

### Пісочниця — це контейнер?

Ні. Кожна пісочниця — microVM Firecracker із власним ядром Linux, і всередині ви root. У пісочниці можна запускати контейнери Docker.

### Що стається з моїми процесами, коли пісочниця стає на паузу?

Вони зупиняються там, де були, і зберігають свою пам’ять, відкриті файли й стан. Наступний виклик, вхід по SSH чи запит до порту продовжує їх приблизно за 0,1 с, ніби нічого не сталося.

### Чи може пісочниця на паузі не прокинутися через брак місця?

Ні. Поки вона на паузі, сервер тримає її місце, тож продовження ніколи не відхиляють через брак місця. Зупинену пісочницю — можуть: тоді `ResumeSandbox` може запустити її на іншому сервері.

### Де мої файли, коли пісочниця зупинена?

На її диску, скопійованому в об’єктне сховище в ЄС і зашифрованому ключем цієї пісочниці, а також на її сервері, поки є місце. Коли вона продовжиться, вони повернуться такими, як були.

### Чи зберігає шаблон запущені процеси?

Ні. Шаблон зберігає лише диск: файли, пакети й образи Docker. Пісочниця з нього завантажується начисто, без процесів і розмов агентів тієї, з якої його збережено. Щоб скопіювати пісочницю, що працює, зробіть її копію (fork).

[НазадДокументація Pethost Agent Sandboxes](https://pethost.dev/uk/docs/sandboxes/) [ДаліШвидкий старт: ваша перша пісочниця](https://pethost.dev/uk/docs/sandboxes/quickstart/)

## Спробуйте Pethost Agent Sandboxes

Пробний період на 7 днів із використанням на 1 $ і 4 vCPU, потрібна картка. Далі — тариф від 20 $ на місяць, який включає стільки ж використання.

[Почати пробний період](https://console.pethost.dev/)

Pethost · Stephan Gomer · NIP 1133096755

Pethost

- [Шаблони](https://pethost.dev/uk/templates/)
- [Про нас](https://pethost.dev/about/)
- [Документація](https://pethost.dev/docs/)
- [Блог](https://pethost.dev/uk/blog/)
- [API](https://pethost.dev/docs/api/)
- [CLI](https://pethost.dev/docs/cli/)
- [Плагін](https://github.com/pethost-dev/plugin)
- [Умови](https://pethost.dev/terms/)
- [Конфіденційність](https://pethost.dev/privacy/)
- [Повернення коштів](https://pethost.dev/refunds/)
- [support@pethost.dev](mailto:support@pethost.dev)

Бази даних

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

Agent Sandboxes

- [Пісочниці](https://pethost.dev/uk/sandboxes/)
- [Тарифи](https://pethost.dev/uk/sandboxes/#pricing)
- [Документація](https://pethost.dev/uk/docs/sandboxes/)
- [API](https://pethost.dev/docs/sandboxes/api/)

Порівняння

- [Coolify vs Dokploy vs CapRover vs Dokku](https://pethost.dev/uk/blog/coolify-vs-dokploy-vs-caprover-vs-dokku/)
- [Coolify Cloud vs Dokploy Cloud](https://pethost.dev/uk/blog/coolify-cloud-vs-dokploy-cloud/)
- [Ціни Railway vs Render vs Fly.io](https://pethost.dev/uk/blog/railway-vs-render-vs-fly-io-pricing/)
- [Керований хостинг Docker Compose](https://pethost.dev/uk/blog/managed-docker-compose-hosting/)

Альтернативи

- [Альтернативи Railway](https://pethost.dev/uk/blog/railway-alternatives/)
- [Альтернативи Heroku](https://pethost.dev/uk/blog/heroku-alternatives/)
- [Альтернативи Dokploy](https://pethost.dev/uk/blog/dokploy-alternatives/)
- [Альтернативи Coolify](https://pethost.dev/uk/blog/coolify-alternatives/)
- [Альтернативи Render](https://pethost.dev/uk/blog/render-alternatives/)
- [Альтернативи Sliplane](https://pethost.dev/uk/blog/sliplane-alternatives/)
