Документація 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пісочниці кажуть, що її життєвий цикл зробить далі і коли.
Що вважається активністю
Пісочниця простоює, поки в ній нічого не відбувається. Кожне з цього не дає їй заснути й, завершившись, скидає її годинник простою:
- виклик API середовища виконання (команда, файл, робочий стіл, агент) або один із його потоків, що лишився відкритим;
- відкрите посилання: термінал або перегляд робочого стола наживо в браузері;
- SSH-сесія;
- запит до одного з її портів;
- хід агента, що ще триває;
- команда, запущена з
keep_awake, доки вона не завершиться.
Не рахується процес, що сам працює у фоні: сервер розробки, задача, запущена через 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, ніколи | Пісочниця в будь-якому стані видаляється. |
Коли таймер зупинки спрацьовує не пізніше за таймер паузи, пісочниця RUNNING у простої зупиняється без паузи. Якщо обидва вимкнені, пісочниця працює, доки ви її не поставите на паузу, не зупините чи не видалите.
Задайте життєвий цикл під час створення пісочниці або пізніше через 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: поки вона працює, пісочниця не стає на паузу через простій і рахується як RUNNING. Дайте їй ще й 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
Типово пісочниця 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_stopped | keep_awake |
|---|---|---|---|---|---|
| Сесія агента, як-от Claude Code у хмарі | 300, типово | 0 або 86400 | 0 | Ні | На довгих збірках |
| Пісочниця на кожного користувача вашого ШІ-застосунку | від 60 до 300 | 1800, типово | 604800 | Якщо застосунок робить виклики без ResumeSandbox | Ні |
| Прев’ю, що засинає | 120 | 0 | 2592000 | Ні | Ні |
| Пакетна задача чи оцінювання | 0 | 60 | 600 або 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 $ на місяць, який включає стільки ж використання.