Українська
Меню документації

Документація 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 пісочниці кажуть, що її життєвий цикл зробить далі і коли.

Що вважається активністю

Пісочниця простоює, поки в ній нічого не відбувається. Кожне з цього не дає їй заснути й, завершившись, скидає її годинник простою:

  • виклик API середовища виконання (команда, файл, робочий стіл, агент) або один із його потоків, що лишився відкритим;
  • відкрите посилання: термінал або перегляд робочого стола наживо в браузері;
  • SSH-сесія;
  • запит до одного з її портів;
  • хід агента, що ще триває;
  • команда, запущена з keep_awake, доки вона не завершиться.

Не рахується процес, що сам працює у фоні: сервер розробки, задача, запущена через 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, ніколиПісочниця в будь-якому стані видаляється.

Коли таймер зупинки спрацьовує не пізніше за таймер паузи, пісочниця RUNNING у простої зупиняється без паузи. Якщо обидва вимкнені, пісочниця працює, доки ви її не поставите на паузу, не зупините чи не видалите.

Задайте життєвий цикл під час створення пісочниці або пізніше через 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: поки вона працює, пісочниця не стає на паузу через простій і рахується як RUNNING. Дайте їй ще й 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

Типово пісочниця STOPPED прокидається лише через ResumeSandbox. Виклик середовища виконання в неї відповідає 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, коли закінчить, і це найнадійніший спосіб.

Коли пісочниця стає на паузу чи зупиняється раніше

Пісочниця може стати на паузу чи зупинитися раніше, ніж кажуть її таймери, коли її серверу бракує місця:

  • Бракує пам’яті: пісочниця RUNNING, що простоює 1 хв або довше, достроково стає на паузу. Її state_message каже «paused early: its server's memory ran short».
  • Бракує диска: сервер зупиняє пісочниці PAUSED, що простоюють найдовше, «stopped early: its server's disk ran short», а пауза тим часом стає зупинкою, «stopped instead of paused».
  • Диск закінчився: сервер зупиняє пісочницю RUNNING, чий диск виріс найбільше, з причиною 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 с, і його сервер розробки там, де був. Оплата рахує, скільки коштує кожен варіант.

Коли не працює

  • Вона стала на паузу посеред довгої збірки. У неї ніхто не робив викликів, а збірка — фоновий процес. Запускайте збірку з keep_awake.
  • Виклик відповідає FAILED_PRECONDITION зі Stopped. Пісочниця 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 $ на місяць, який включає стільки ж використання.

Почати пробний період