Документация Agent Sandboxes · Основы
Жизненный цикл песочницы: автопауза, автоостановка и простой
Песочница, которую вы оставили в покое, встает на паузу через 5 минут, останавливается через 30 и никогда не удаляется, если вы не попросите. Это решают три таймера на одних часах простоя, и каждый можно изменить или выключить. Здесь сказано, что считается активностью, что делает каждый таймер и какие значения подходят агенту, пользователям приложения, превью и пакетной задаче.
- Простой — это когда нет ни вызова, ни потока, ни ссылки, ни SSH-сессии, ни запроса к порту, ни хода агента, ни команды с
keep_awake. Фоновый процесс сам по себе не в счет: он встает на паузу вместе с песочницей и продолжает с того же места. - Три таймера:
pause_after_idle_seconds(300),stop_after_idle_seconds(1 800) иdelete_after_idle_seconds(выключен). Каждый выключается значением 0. - Долгая работа, к которой никто не обращается, например сборка или прогон тестов, запускается с
keep_awake, чтобы песочница не встала на паузу посреди нее. - Остановленная песочница запускается снова через
ResumeSandboxили при следующем вызове, если включенwake_when_stopped. next_stateиnext_state_timeу песочницы говорят, что и когда ее жизненный цикл сделает дальше.
Что считается активностью
Песочница простаивает, пока в ней ничего не происходит. Каждое из этого не дает ей уснуть и, закончившись, сбрасывает ее часы простоя:
- вызов runtime API (команда, файл, рабочий стол, агент) или один из его потоков, оставленный открытым;
- открытая ссылка: терминал или живой вид рабочего стола в браузере;
- SSH-сессия;
- запрос к одному из ее портов;
- ход агента, который еще идет;
- команда, запущенная с
keep_awake, пока она не завершится.
Не в счет процесс, который сам работает в фоне: dev-сервер, задача, запущенная через nohup, вотчер. Когда песочница встает на паузу, такой процесс замирает на месте и продолжает оттуда, когда песочница просыпается. Серверу больше ничего не нужно: запрос к его порту будит песочницу.
Шкала по умолчанию
- 0 минПоследняя активность: песочница работает.
- 5 минPAUSED: память и процессы хранятся на ее сервере, за 30 % цены.
- 30 минSTOPPED: диск хранится, процессы завершены, 0,03 $ за GiB в месяц.
- НикогдаУдаляется только вами или своим таймером удаления.
Три таймера
У lifecycle песочницы три таймера, каждый — число секунд на одних и тех же часах простоя, каждый выключается значением 0:
| Поле | По умолчанию | Что происходит |
|---|---|---|
pause_after_idle_seconds | 300 | Песочница в RUNNING переходит в PAUSED. |
stop_after_idle_seconds | 1 800 | Песочница в RUNNING или PAUSED переходит в STOPPED. |
delete_after_idle_seconds | 0, никогда | Песочница в любом состоянии удаляется. |
Если таймер остановки срабатывает не позже таймера паузы, простаивающая работающая песочница останавливается, минуя паузу. Если выключены оба, песочница работает, пока вы не поставите ее на паузу, не остановите или не удалите.
Жизненный цикл задается при создании песочницы или позже через UpdateSandbox. Жизненный цикл — одна группа настроек: отправленная группа заменяет всю группу песочницы, а пропущенный таймер получает значение по умолчанию. Поэтому отправляйте все таймеры, которые хотите задать. Каждый ответ несет действующие настройки с заполненными значениями по умолчанию, так что прочитанное можно отправить обратно как есть.
from pethost.sandboxes import Lifecycle, SandboxSettings, Sandboxes
sandboxes = Sandboxes() # The token: PETHOST_TOKEN.
sandbox = sandboxes.create_sandbox(
settings=SandboxSettings(
lifecycle=Lifecycle(
pause_after_idle_seconds=300, # pause after 5 idle minutes
stop_after_idle_seconds=86400, # stop after an idle day
),
),
)
print(sandbox.sandbox_id)
import { Sandboxes } from "pethost/sandboxes";
const sandboxes = new Sandboxes({ token: process.env.PETHOST_TOKEN! });
const sandbox = await sandboxes.createSandbox({
settings: {
lifecycle: { pauseAfterIdleSeconds: 300, stopAfterIdleSeconds: 86400 },
},
});
console.log(sandbox.sandboxId);
client := sandboxes.NewClient(sandboxes.Config{Token: os.Getenv("PETHOST_TOKEN")})
sandbox, err := client.CreateSandbox(ctx, &sandboxes.CreateSandboxRequest{
Settings: &sandboxes.SandboxSettings{
Lifecycle: &sandboxes.Lifecycle{
PauseAfterIdleSeconds: new(uint32(300)),
StopAfterIdleSeconds: new(uint32(86400)),
},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(sandbox.SandboxID)
use pethost::sandboxes::{types::*, Client};
let sandboxes = Client::new(&std::env::var("PETHOST_TOKEN")?);
let sandbox = sandboxes
.create_sandbox(CreateSandboxRequest {
settings: Some(SandboxSettings {
lifecycle: Some(Lifecycle {
pause_after_idle_seconds: Some(300),
stop_after_idle_seconds: Some(86400),
..Default::default()
}),
..Default::default()
}),
..Default::default()
})
.await?;
println!("{}", sandbox.sandbox_id);
pethost sandbox new --pause-after 5m --stop-after 24h
CreateSandbox {"settings": {"lifecycle": {"pause_after_idle_seconds": 300, "stop_after_idle_seconds": 86400}}}
curl https://console.pethost.dev/pethost.sandboxes.v1.SandboxService/CreateSandbox \
-H "Authorization: Bearer $PETHOST_TOKEN" \
-H "Content-Type: application/json" \
-d '{"settings": {"lifecycle": {"pause_after_idle_seconds": 300, "stop_after_idle_seconds": 86400}}}'
Долгая работа: keep_awake
Сборка, прогон тестов или обучение могут идти минутами без единого вызова к песочнице, и таймер паузы поставил бы ее на паузу посреди работы. Запускайте такую команду с keep_awake: пока она идет, песочница не встает на паузу из-за простоя и считается работающей. Задайте и timeout_seconds, чтобы зависшая команда не держала песочницу без сна вечно.
command = sandboxes.run_command(
sandbox.sandbox_id,
command="npm ci && npm test",
keep_awake=True,
timeout_seconds=1800,
wait_seconds=0, # answer once it has started
)
print(command.command_id, command.state.name)
const command = await sandboxes.runCommand({
sandboxId: sandbox.sandboxId,
command: "npm ci && npm test",
keepAwake: true,
timeoutSeconds: 1800,
waitSeconds: 0, // answer once it has started
});
console.log(command.commandId, command.state);
command, err := client.RunCommand(ctx, &sandboxes.RunCommandRequest{
SandboxID: sandbox.SandboxID,
Command: "npm ci && npm test",
KeepAwake: true,
TimeoutSeconds: 1800,
WaitSeconds: new(uint32(0)), // answer once it has started
})
let command = sandboxes
.run_command(RunCommandRequest {
sandbox_id: sandbox.sandbox_id.clone(),
command: "npm ci && npm test".into(),
keep_awake: true,
timeout_seconds: 1800,
wait_seconds: Some(0), // answer once it has started
..Default::default()
})
.await?;
pethost sandbox run k7f3q2xy0a1b2c3d -d --keep-awake --timeout 30m -- 'npm ci && npm test'
Срок жизни песочницы ничем не ограничен: песочница, которую держат без сна, работает и оплачивается, пока ее команда не завершится или пока вы ее не остановите.
Пробуждение остановленной песочницы: wake_when_stopped
По умолчанию остановленная песочница просыпается только через ResumeSandbox. Вызов runtime к ней отвечает FAILED_PRECONDITION со Stopped, а запрос к одному из ее портов отвечает HTTP 503, «stopped: resume it».
С включенным wake_when_stopped остановленная песочница просыпается от вызова, входа по SSH или запроса к порту, как песочница на паузе: примерно за 0,2 с, пока ее диск на сервере, и дольше, когда диск возвращается из объектного хранилища, — примерно 10 с на GiB ее собственных данных. Это подходит проекту, который просыпается время от времени, например эндпоинту вебхука или песочнице, которую ваше приложение вызывает, не возобновляя ее сначала.
Это стоит бюджета, а не денег: vCPU такой песочницы засчитываются в ваш тариф и пока она остановлена, чтобы ей всегда было где проснуться. Включить его для остановленной песочницы не получится, если у рабочего пространства не осталось vCPU, а выключение их освобождает. Песочница, остановленная из-за CRASH, так никогда не просыпается.
Уборка сама собой: delete_after_idle_seconds
Остановленная песочница стоит только своих хранимых байтов, но стоит их каждый месяц. Для песочниц, к которым вы не вернетесь, задайте delete_after_idle_seconds: простояв столько в любом состоянии, песочница удаляется вместе с памятью и диском. Ее тома остаются. Ее запись хранится 30 дней, а события и метрики — сутки. Ваша программа может и сама вызвать DeleteSandbox, закончив работу, и это самый надежный способ.
Когда песочница встает на паузу или останавливается раньше
Песочница может встать на паузу или остановиться раньше, чем говорят ее таймеры, если ее серверу не хватает места:
- Не хватает памяти: работающая песочница, простаивающая 1 мин и дольше, встает на паузу раньше времени. Ее
state_messageговорит «paused early: its server's memory ran short». - Не хватает диска: сервер останавливает песочницы на паузе, которые простаивают дольше всех, «stopped early: its server's disk ran short», а пауза тем временем становится остановкой, «stopped instead of paused».
- Диск кончился: сервер останавливает работающую песочницу, чей диск вырос сильнее всех, с причиной CRASH, «its server ran out of disk space». Ее диск сохраняется.
Песочница, которая не простаивает, никогда не встает на паузу раньше времени из-за памяти.
Что будет дальше: next_state и причины
GetSandbox отвечает с next_state и next_state_time: что жизненный цикл сделает с песочницей дальше, если до того ничего не случится, — PAUSED, STOPPED или DELETED, — и когда. Их нет, пока что-то не дает песочнице уснуть и когда в ее состоянии не идет ни один таймер.
У каждого изменения состояния есть state_reason, и события песочницы показывают те же причины:
| Причина | Что значит |
|---|---|
REQUEST | Об этом попросил вызов. |
IDLE | Таймер или нехватка памяти или диска на ее сервере. |
WAKE | Ее возобновил вызов, вход по SSH или запрос к порту. |
CRASH | Сбой ее ВМ или ее сервера, или она не запустилась. Запустить ее снова может только ResumeSandbox. |
MAINTENANCE | Машина ее сервера перезагрузилась: перед этим песочница встала на паузу, без оплаты, а после снова работает. |
UNPAID | За рабочее пространство нечем платить: оплата. |
Значения для разных задач
Это рекомендации, построенные на правилах выше. Таймеры — в секундах, как их принимает API.
| Задача | Пауза | Остановка | Удаление | wake_when_stopped | keep_awake |
|---|---|---|---|---|---|
| Сессия агента, например Claude Code в облаке | 300, по умолчанию | 0 или 86400 | 0 | Нет | На долгих сборках |
| Песочница на каждого пользователя вашего ИИ-приложения | от 60 до 300 | 1800, по умолчанию | 604800 | Если приложение вызывает ее без ResumeSandbox | Нет |
| Превью, которое спит | 120 | 0 | 2592000 | Нет | Нет |
| Пакетная задача или эвал | 0 | 60 | 600 или DeleteSandbox в конце | Нет | На команде задачи |
Песочница агента, которая никогда не останавливается, сохраняет свои процессы, а день на паузе стоит 30 % дня работы. Превью без таймера остановки просыпается при заходе примерно за 0,2 с, и его dev-сервер там же, где был. Сколько стоит каждый вариант, подсчитано на странице «Оплата».
Если не работает
- Встала на паузу посреди долгой сборки. К ней никто не обращался, а сборка — фоновый процесс. Запускайте сборку с
keep_awake. - Вызов отвечает FAILED_PRECONDITION со Stopped. Песочница остановлена. Вызовите
ResumeSandboxили включитеwake_when_stopped. - Порт отвечает 503, «stopped: resume it». То же самое, только из браузера или curl.
- Вызов отвечает UNAVAILABLE с Restoring. Ее диск возвращается из объектного хранилища, примерно 10 с на GiB. Подождите или вызовите
ResumeSandboxеще раз, чтобы следить за ходом. - Встала на паузу раньше своего таймера. Ее серверу не хватило памяти: об этом говорит
state_message. Она просыпается как обычно при следующем вызове.
Вопросы
Не дает ли фоновый процесс песочнице уснуть?
Нет. Это делают только вызовы, открытые потоки и ссылки, SSH-сессии, запросы к портам, идущие ходы агентов и команды, запущенные с keep_awake. Фоновый процесс встает на паузу вместе с песочницей и продолжает, когда она просыпается.
Как сделать, чтобы песочница никогда не останавливалась?
Задайте stop_after_idle_seconds равным 0. В простое она по-прежнему встает на паузу, сохраняя свои процессы, и просыпается при следующем вызове.
Как держать песочницу работающей все время?
Задайте и pause_after_idle_seconds, и stop_after_idle_seconds равными 0, и она будет работать по цене работы, пока вы не поставите ее на паузу, не остановите или не удалите.
Просыпается ли остановленная песочница, когда я к ней обращаюсь?
Только с включенным wake_when_stopped, и тогда ее vCPU засчитываются в ваш тариф и пока она остановлена. Иначе ее запускает ResumeSandbox.
Удаляются ли простаивающие песочницы автоматически?
По умолчанию нет. Задайте delete_after_idle_seconds или вызовите DeleteSandbox, когда закончите.
Попробуйте Pethost Agent Sandboxes
Пробный период на 7 дней: 1 $ использования и 4 vCPU, нужна карта. Затем тариф от 20 $ в месяц, в который входит столько же использования.