---
title: "Как устроены Pethost Agent Sandboxes | Pethost Agent Sandboxes"
description: "Что такое песочница, ее три состояния RUNNING, PAUSED и STOPPED, что ее будит, два API и где хранятся ее память, процессы и файлы."
---

[Документация Agent Sandboxes](https://pethost.dev/ru/docs/sandboxes/) · Начало

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

Обновлено 21 ноября 2026 г. · 7 мин чтения

Песочница — это ВМ Linux, которую ваш код или ваш агент запускает примерно за 0,15 с, использует через API и оставляет в покое. Когда в ней ничего не происходит, она встает на паузу вместе с памятью и процессами, а позже останавливается, сохранив только диск. Следующий вызов будит ее там, где она была. Эта страница — модель: что такое песочница, ее три состояния, что переводит ее из одного в другое и где лежит каждый байт.

**Коротко**

- **МикроВМ на каждую песочницу:** Firecracker, собственное ядро, root внутри, Ubuntu с Python, Node.js, Docker, тремя агентами для кода и Chrome.
- **Три состояния:** RUNNING — в памяти своего сервера, PAUSED — на диске своего сервера с сохраненными памятью и процессами, STOPPED — в объектном хранилище, только диск.
- **Просыпается, когда нужна:** любой вызов к песочнице на паузе, вход по SSH или запрос к одному из ее портов возобновляет ее примерно за 0,1 с.
- **Два API:** панель хранит запись о каждой песочнице, а собственный сервер песочницы выполняет то, что происходит внутри. SDK и CLI скрывают эту разницу.
- **Посекундная оплата** каждого состояния: [оплата](https://pethost.dev/ru/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`.

## Изоляция: у каждой своя микроВМ 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: [шаблоны](https://pethost.dev/ru/docs/sandboxes/templates/).

## Два 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.

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

| Из | В | Что переводит |
| --- | --- | --- |
| 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`. Что считается активностью и как задать таймеры, рассказывает страница [«Жизненный цикл и простой»](https://pethost.dev/ru/docs/sandboxes/lifecycle/).

## Что будит песочницу

Любой вызов 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](https://pethost.dev/ru/docs/sandboxes/) [СледующаяБыстрый старт: ваша первая песочница](https://pethost.dev/ru/docs/sandboxes/quickstart/)

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

Пробный период на 7 дней: 1 $ использования и 4 vCPU, нужна карта. Затем тариф от 20 $ в месяц, в который входит столько же использования.

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

Pethost · Stephan Gomer · NIP 1133096755

Pethost

- [Шаблоны](https://pethost.dev/ru/templates/)
- [О нас](https://pethost.dev/about/)
- [Документация](https://pethost.dev/docs/)
- [Блог](https://pethost.dev/ru/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/ru/postgres/)
- [Valkey](https://pethost.dev/ru/valkey/)

Agent Sandboxes

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

Сравнения

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

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

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