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

Документация Agent Sandboxes · Основы

Жизненный цикл песочницы: автопауза, автоостановка и простой

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

Песочница, которую вы оставили в покое, встает на паузу через 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, вотчер. Когда песочница встает на паузу, такой процесс замирает на месте и продолжает оттуда, когда песочница просыпается. Серверу больше ничего не нужно: запрос к его порту будит песочницу.

Шкала по умолчанию

  1. 0 минПоследняя активность: песочница работает.
  2. 5 минPAUSED: память и процессы хранятся на ее сервере, за 30 % цены.
  3. 30 минSTOPPED: диск хранится, процессы завершены, 0,03 $ за GiB в месяц.
  4. НикогдаУдаляется только вами или своим таймером удаления.
Часы простоя начинают отсчет заново при каждой активности: вызов на 4-й минуте откладывает паузу до 9-й.

Три таймера

У lifecycle песочницы три таймера, каждый — число секунд на одних и тех же часах простоя, каждый выключается значением 0:

ПолеПо умолчаниюЧто происходит
pause_after_idle_seconds300Песочница в RUNNING переходит в PAUSED.
stop_after_idle_seconds1 800Песочница в RUNNING или PAUSED переходит в STOPPED.
delete_after_idle_seconds0, никогдаПесочница в любом состоянии удаляется.

Если таймер остановки срабатывает не позже таймера паузы, простаивающая работающая песочница останавливается, минуя паузу. Если выключены оба, песочница работает, пока вы не поставите ее на паузу, не остановите или не удалите.

Жизненный цикл задается при создании песочницы или позже через UpdateSandbox. Жизненный цикл — одна группа настроек: отправленная группа заменяет всю группу песочницы, а пропущенный таймер получает значение по умолчанию. Поэтому отправляйте все таймеры, которые хотите задать. Каждый ответ несет действующие настройки с заполненными значениями по умолчанию, так что прочитанное можно отправить обратно как есть.

Python
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)
TypeScript
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);
Go
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)
Rust
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);
CLI
pethost sandbox new --pause-after 5m --stop-after 24h
MCP
CreateSandbox {"settings": {"lifecycle": {"pause_after_idle_seconds": 300, "stop_after_idle_seconds": 86400}}}
HTTP
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, чтобы зависшая команда не держала песочницу без сна вечно.

Python
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)
TypeScript
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);
Go
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
})
Rust
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?;
CLI
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_stoppedkeep_awake
Сессия агента, например Claude Code в облаке300, по умолчанию0 или 864000НетНа долгих сборках
Песочница на каждого пользователя вашего ИИ-приложенияот 60 до 3001800, по умолчанию604800Если приложение вызывает ее без ResumeSandboxНет
Превью, которое спит12002592000НетНет
Пакетная задача или эвал060600 или 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 $ в месяц, в который входит столько же использования.

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