Документация Agent Sandboxes · Начало
Как устроены Pethost Agent Sandboxes
Песочница — это ВМ Linux, которую ваш код или ваш агент запускает примерно за 0,15 с, использует через API и оставляет в покое. Когда в ней ничего не происходит, она встает на паузу вместе с памятью и процессами, а позже останавливается, сохранив только диск. Следующий вызов будит ее там, где она была. Эта страница — модель: что такое песочница, ее три состояния, что переводит ее из одного в другое и где лежит каждый байт.
- МикроВМ на каждую песочницу: 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.
Изоляция: у каждой своя микроВМ Firecracker
Каждая песочница — отдельная микроВМ 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) перезапускает работающую песочницу в ВМ этого размера: файлы сохраняются, процессы завершаются; остановленная получает новый размер при следующем запуске, а песочницу на паузе сначала нужно возобновить или остановить. Новый размер оставляет диск прежним, если не задать 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 сам находит сервер и обновляет токен. Вызовы runtime идут прямо на сервер, поэтому панель никогда не стоит на пути того, что работает внутри песочницы, и сервер выполняет свои песочницы без панели.
Три состояния
В памяти своего сервера
Выполняет ваши процессы и отвечает на каждый вызов.
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
ВМ агента большую часть времени ждет: пока модель думает, пока человек читает ответ, пока придет следующее сообщение. Остановка завершает ее процессы, а с ними dev-сервер, REPL, состояние шелла и открытый браузер, которым пользовался агент. Если же держать ее в RUNNING, ожидание оплачивается по полной цене.
PAUSED сохраняет все, включая память и процессы, за 30 % цены работы, а сервер держит за песочницей ее место, поэтому в возобновлении никогда не отказывают из-за нехватки места. Будить ее вашему коду не нужно: следующий вызов к песочнице сначала возобновляет ее, примерно за 0,1 с, а затем выполняется так, будто песочница и не останавливалась. На сервере возобновление песочницы на паузе занимает 41 ms, а команда, отправленная такой песочнице, отвечает примерно за 80 ms.
Что меняет состояние песочницы
| Из | В | Что переводит |
|---|---|---|
| RUNNING | PAUSED | Ее таймер паузы; PauseSandbox; нехватка памяти на ее сервере, если она простаивает уже минуту; перезагрузка машины ее сервера (MAINTENANCE, за нее ничего не начисляется) |
| PAUSED | RUNNING | Любой вызов runtime, вход по 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 или запрос к одному из ее портов сначала возобновляет песочницу на паузе, на ее собственном сервере. Остановленная песочница просыпается так, только если в ее жизненном цикле задан wake_when_stopped. Без него:
- вызов runtime отвечает
FAILED_PRECONDITIONс детальюStopped; - запрос к порту отвечает HTTP 503, «stopped: resume it»;
- запустить ее может только
ResumeSandbox.
Песочница, остановленная из-за CRASH, запускается снова только через ResumeSandbox. Пока диск остановленной песочницы забирается обратно из объектного хранилища, вызовы к ней отвечают UNAVAILABLE с Restoring, а ResumeSandbox ждет до 45 с и затем сообщает, сколько уже загружено (Sandbox.restore).
Где лежат ваши данные
| Что | Пауза | Остановка | Форк | Шаблон | Удаление |
|---|---|---|---|---|---|
| Память | Сохраняется | Теряется | Копируется | Не сохраняется | Удаляется |
| Работающие процессы | Сохраняются | Завершаются | Копируются и работают | Не сохраняются | Удаляются |
| Файлы и образы Docker | Сохраняются | Сохраняются | Копируются | Сохраняются | Удаляются |
| Разговоры агентов | Сохраняются | Сохраняются | Копируются | Не сохраняются | Удаляются |
Диск остановленной песочницы копируется в объектное хранилище в ЕС через минуту после остановки, частями, зашифрованными ключом только для этой песочницы; память туда никогда не копируется. Ее сервер хранит свою копию, пока у него есть место. С томом иначе: он лежит на диске одного сервера и никуда не копируется, поэтому храните то, что должно пережить потерю сервера, еще и в другом месте.
Переезды и потерянные серверы
Остановленная песочница с актуальной копией и без тома запускается на другом сервере, если на ее собственном для нее нет места, и ее адреса переезжают вместе с ней: url подключения, URL ее портов и ее ssh_command. Песочница на паузе никогда не переезжает: она возобновляется на сервере, который хранит ее память.
Если сервер потерян, каждая его песочница с копией становится STOPPED из своей последней копии и запускается на другом сервере при следующем ResumeSandbox. Песочница без копии удаляется, как и тома на этом сервере.
Вопросы
Песочница — это контейнер?
Нет. Каждая песочница — микроВМ Firecracker с собственным ядром Linux, и внутри у вас root. В песочнице можно запускать контейнеры Docker.
Что происходит с моими процессами, когда песочница встает на паузу?
Они замирают там, где были, и сохраняют свою память, открытые файлы и состояние. Следующий вызов, вход по SSH или запрос к порту возобновляет их примерно за 0,1 с, будто ничего не случилось.
Может ли песочница на паузе не проснуться из-за нехватки места?
Нет. Пока она на паузе, сервер держит за ней место, поэтому в возобновлении никогда не отказывают из-за нехватки места. Остановленной песочнице отказать могут: тогда ResumeSandbox может запустить ее на другом сервере.
Где мои файлы, когда песочница остановлена?
На ее диске, скопированном в объектное хранилище в ЕС и зашифрованном ключом этой песочницы, а также на ее сервере, пока там есть место. При возобновлении они возвращаются такими, какими были.
Сохраняет ли шаблон работающие процессы?
Нет. Шаблон сохраняет только диск: файлы, пакеты и образы Docker. Песочница из него загружается с нуля, без процессов и разговоров агентов той песочницы, из которой он сохранен. Чтобы скопировать работающую песочницу, сделайте ее форк.
Попробуйте Pethost Agent Sandboxes
Пробный период на 7 дней: 1 $ использования и 4 vCPU, нужна карта. Затем тариф от 20 $ в месяц, в который входит столько же использования.