Документація Agent Sandboxes · Початок
Як працюють Pethost Agent Sandboxes
Пісочниця — це ВМ Linux, яку ваш код чи ваш агент запускає приблизно за 0,15 с, використовує через API і лишає в спокої. Коли в ній нічого не відбувається, вона стає на паузу разом із пам’яттю й процесами, а згодом зупиняється, зберігши лише диск. Наступний виклик будить її там, де вона була. Ця сторінка — модель: що таке пісочниця, її три стани, що переводить її з одного в інший і де лежить кожен байт.
- microVM на кожну пісочницю: Firecracker, власне ядро, root усередині, Ubuntu з Python, Node.js, Docker, трьома агентами для коду й Chrome.
- Три стани: RUNNING у пам’яті свого сервера, PAUSED на диску свого сервера зі збереженими пам’яттю й процесами, STOPPED в об’єктному сховищі лише з диском.
- Пробудження від використання: будь-який виклик у пісочницю на паузі, вхід по SSH або запит до одного з її портів продовжує її приблизно за 0,1 с.
- Два API: панель зберігає запис про кожну пісочницю, а власний сервер пісочниці виконує те, що відбувається всередині. SDK і CLI приховують цю різницю.
- Посекундна оплата кожного стану: оплата.
Що таке пісочниця
Пісочниця — це одна віртуальна машина, створена із шаблону. Усередині ви 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: шаблони.
Два API: панель і сервер пісочниці
Відповідають два сервіси, за тим, що кожен знає:
- SandboxService — це панель, за адресою
https://console.pethost.dev, яку викликають із вашим API-токеном. Вона зберігає робочий простір і кожну пісочницю як запис: створення, налаштування, пауза, продовження, копіювання, видалення, шаблони, томи, події й використання. - SandboxRuntimeService — це власний сервер пісочниці, за
urlїї з’єднання, який викликають із токеном з’єднання лише для цієї пісочниці. Він виконує те, що відбувається всередині: команди, файли, робочий стіл, агентів для коду й посилання.
SDK і CLI підключаються за вас: run_command — один виклик, а SDK сам знаходить сервер і оновлює токен. Виклики середовища виконання йдуть прямо на сервер, тож панель ніколи не стоїть на шляху того, що працює в пісочниці, а сервер виконує свої пісочниці без панелі.
Три стани
У пам’яті свого сервера
Виконує ваші процеси й відповідає на кожен виклик.
0,036 $ на годину, DEFAULT
5 хв простою або PauseSandbox
Будь-який виклик, вхід по SSH чи запит до порту, приблизно за 0,1 с
На диску свого сервера
Зберігає пам’ять, процеси, диск і своє місце на сервері.
0,0108 $ на годину, DEFAULT
30 хв простою або StopSandbox
В об’єктному сховищі
Зберігає диск; процеси завершуються.
0,03 $ за GiB власних даних на місяць
ResumeSandbox завантажує її знову: приблизно за 0,2 с, якщо диск на сервері, і приблизно 10 с на GiB з об’єктного сховища
| Стан | Де вона | Що зберігає | Як прокидається |
|---|---|---|---|
| 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. Життєвий цикл і простій пояснює, що вважається активністю і як задавати таймери.
Що будить пісочницю
Будь-який виклик 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
Пробний період на 7 днів із використанням на 1 $ і 4 vCPU, потрібна картка. Далі — тариф від 20 $ на місяць, який включає стільки ж використання.