Русский
Меню документации

Документация Agent Sandboxes · Начало

Как устроены Pethost Agent Sandboxes

Обновлено · 7 мин чтения

Песочница — это ВМ 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ПамятьДиск
SMALL24 GiB10 GiB
DEFAULT48 GiB20 GiB
LARGE816 GiB40 GiB
XLARGE1632 GiB80 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 идут прямо на сервер, поэтому панель никогда не стоит на пути того, что работает внутри песочницы, и сервер выполняет свои песочницы без панели.

Три состояния

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Память своего сервераВсе, в работеОна не спит
PAUSEDДиск своего сервераПамять, процессы, дискПри следующем вызове, входе по SSH или запросе к порту, примерно за 0,1 с; в этом никогда не отказывают из-за нехватки места
STOPPEDОбъектное хранилище, а также диск своего сервера, пока там есть местоСвой дискЧерез ResumeSandbox или как на паузе, если задан wake_when_stopped
DELETEDНигдеСвою запись — 30 дней, события и метрики — суткиНикогда

Зачем нужно состояние PAUSED

ВМ агента большую часть времени ждет: пока модель думает, пока человек читает ответ, пока придет следующее сообщение. Остановка завершает ее процессы, а с ними dev-сервер, REPL, состояние шелла и открытый браузер, которым пользовался агент. Если же держать ее в RUNNING, ожидание оплачивается по полной цене.

PAUSED сохраняет все, включая память и процессы, за 30 % цены работы, а сервер держит за песочницей ее место, поэтому в возобновлении никогда не отказывают из-за нехватки места. Будить ее вашему коду не нужно: следующий вызов к песочнице сначала возобновляет ее, примерно за 0,1 с, а затем выполняется так, будто песочница и не останавливалась. На сервере возобновление песочницы на паузе занимает 41 ms, а команда, отправленная такой песочнице, отвечает примерно за 80 ms.

Что меняет состояние песочницы

ИзВЧто переводит
RUNNINGPAUSEDЕе таймер паузы; PauseSandbox; нехватка памяти на ее сервере, если она простаивает уже минуту; перезагрузка машины ее сервера (MAINTENANCE, за нее ничего не начисляется)
PAUSEDRUNNINGЛюбой вызов runtime, вход по SSH или запрос к порту (WAKE); ResumeSandbox
RUNNING или PAUSEDSTOPPEDЕе таймер остановки; StopSandbox; нехватка диска на ее сервере (для песочницы на паузе); рабочее пространство, которому нечем платить (UNPAID); сбой ее ВМ или ее сервера (CRASH)
STOPPEDRUNNINGResumeSandbox; вызов, вход по SSH или запрос к порту — только с wake_when_stopped и никогда после CRASH
ЛюбоеDELETEDDeleteSandbox; ее таймер удаления; потеря ее сервера, если у песочницы нет копии в объектном хранилище

У каждого изменения есть причина, 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 $ в месяц, в который входит столько же использования.

Начать пробный период