Документація Agent Sandboxes · Основи
Найкращі практики для Pethost Agent Sandboxes
Кілька рішень визначають, як швидко стартують ваші пісочниці, скільки вони коштують, поки чекають, і до чого може дістатися агент усередині. Кожна практика нижче — це правило, число за ним і поля, що його втілюють. Більшість із них — налаштування, яке ви робите один раз.
- Швидкість: збережіть своє середовище як шаблон, запускайте сервери з
wait_for_portі копіюйте пісочницю для паралельних спроб. - Вартість: дайте пісочниці агента ставати на паузу замість зупинки, видаляйте пакетні пісочниці, коли вони закінчили, і починайте з малого.
- Надійність: позначайте довгі команди
keep_awake, повторюйте виклики зrequest_id, транслюйте замість опитування й тримайте в томах те, що має пережити пісочницю. - Безпека: прив’язуйте API-ключі як секрети, звужуйте вихідний трафік для чужого коду й вважайте все, що повертає пісочниця, даними.
- Порядок: ставте мітки на кожну пісочницю й шукайте їх за мітками.
Швидкість
Збережіть своє середовище як шаблон
Встановлення залежностей під час кожного запуску щоразу коштує тих самих хвилин. Встановіть їх один раз у пісочниці, потім збережіть її диск через CreateTemplate: разом із пакетами, кешами збирання й образами Docker. Пісочниця з вашого шаблону запускається приблизно за 0,22 с з усім на місці, на будь-якому сервері: перша на кожному сервері звантажує версію, приблизно 10 с на GiB, а наступні стартують із її копії. Не тримайте секретів у файлах, які зберігаєте, бо їх отримає кожна пісочниця із шаблону, і робіть нову версію, коли змінюються залежності: my-app стартує з найновішої, my-app@3 — саме з цієї.
Запускайте сервери з wait_for_port
Серверу розробки треба трохи часу, щоб почати слухати порт, а опитувати його ззовні — марнувати виклики. Запускайте його з wait_for_port: RunCommand відповідає, щойно щось слухає цей порт, а команда працює далі, тож один виклик запускає сервер і каже, що він піднявся. Потім відкрийте порт публічно або дайте своїй сторінці токен для нього: порти й прев’ю.
Копіюйте пісочницю для паралельних спроб
Коли агент має спробувати кілька виправлень або оцінювання має стартувати багато прогонів з одного підготовленого стану, скопіюйте пісочницю замість того, щоб відтворювати цей стан. ForkSandbox одним викликом робить до 100 нових пісочниць із пам’яттю, процесами й диском вихідної: копія займала приблизно 0,25 с. Кожна копія — це запуск, і створюються всі або жодна. Дві речі, які варто знати:
- Перезасівайте генератори випадкових чисел у копіях. Кожна копія має власну випадковість ядра, але генератори, що вже працюють у її процесах (OpenSSL, Python, Node, Go), дають ті самі числа в кожній копії, доки їх не перезасіяти.
- Том для читання й запису не дає скопіювати пісочницю, бо писати в нього може лише одна пісочниця. Том монтується лише під час створення, тож у пісочниці, яку збираєтеся копіювати, монтуйте його з
read_only.
Вартість
Дайте пісочниці агента ставати на паузу, а не зупинятися
Пісочниця агента здебільшого чекає, а зупинка завершує її процеси: сервер розробки, REPL, відкритий браузер. Лишіть таймер паузи, а таймер зупинки збільште або вимкніть (stop_after_idle_seconds 0). На паузі пісочниця коштує 30% ціни роботи й прокидається від наступного виклику приблизно за 0,1 с, з усім там, де було. Пісочниця DEFAULT, що працює 2 год на добу, а решту часу на паузі, коштує приблизно 9,42 $ на місяць проти 26,28 $, якщо працює весь час.
Сесія агентаНа паузі між ходами, ніколи не зупиняється
- працює
- пауза
- працює
- пауза
Пісочниця користувача у вашому застосункуСтає на паузу, а через пів години зупиняється
- працює
- пауза
- зупинена
Прев’ю, що засинаєПрокидається від кожного відвідування
- пауза
- працює
- пауза
- працює
- пауза
Пакетна задачаПрацює, потім видаляється
- працює
- зупинена
- видалена
- RUNNING
- PAUSED
- STOPPED
- DELETED
Видаляйте пакетні пісочниці, коли вони закінчили
Пісочниця для однієї задачі, прогону тестів чи випадку оцінювання не має нічого коштувати, коли задача закінчилася. Викликайте DeleteSandbox наприкінці й задайте delete_after_idle_seconds як страховку для задачі, що впаде раніше. Вимкніть таймер паузи й дайте короткий таймер зупинки, щоб пісочниця задачі в простої швидко зникала. Забута зупинена пісочниця коштує 0,03 $ за GiB на місяць, щомісяця. Запуски безкоштовні, тож свіжа пісочниця на кожну задачу коштує лише своїх секунд: 1 000 прогонів по 40 с на SMALL коштують 0,20 $.
Починайте з малого й змінюйте розмір, коли треба
Розмір — це його vCPU, пам’ять і диск, і з кожним наступним розміром ціна подвоюється. Почніть із SMALL, 0,018 $ на годину, і стежте за GetSandboxMetrics. Коли задачі треба більше, UpdateSandbox з новим розміром перезапускає пісочницю RUNNING у ВМ цього розміру, зі збереженими файлами, приблизно за 283 ms: її процеси завершуються, тож змінюйте розмір між задачами. Додайте grow_disk, щоб збільшити диск до диска нового розміру; диск ніколи не зменшується, тож пісочниця зі збільшеним диском не може повернутися до меншого розміру.
Надійність
Позначайте довгі команди keep_awake
Збірка чи набір тестів можуть працювати хвилинами без жодного виклику в пісочницю, і таймер паузи поставив би її на паузу посеред роботи. Запускайте таку команду з keep_awake і з timeout_seconds, щоб команда, яка зависла, не тримала пісочницю запущеною назавжди. Серверу не треба ні того, ні іншого: запит до його порту будить пісочницю. Подробиці — у розділі життєвий цикл і простій.
Повторюйте виклики з request_id
Мережа може загубити відповідь на виклик, який свою роботу зробив. Виклик, що щось створює, приймає request_id: повтор із тим самим id протягом 24 год відповідає тим, що зробив перший виклик, і нічого не робить знову. Його приймають CreateSandbox, ForkSandbox, CreateTemplate, CreateVolume, RunCommand і PromptAgent. Створюйте його один раз на кожну дію, зберігайте й надсилайте знову під час кожного повтору. Одне застереження: пісочниця тримає id того, що в ній виконується, на своєму диску, тож зупинена пісочниця могла втратити id своїх останніх секунд, і повтор такої команди виконає її знову.
import uuid
from pethost.sandboxes import Label, Sandboxes
sandboxes = Sandboxes() # The token: PETHOST_TOKEN.
request_id = str(uuid.uuid4()) # Keep it: a retry sends the same one.
sandbox = sandboxes.create_sandbox(
template="my-app",
labels=[Label(key="user", value="42"), Label(key="job", value="nightly-evals")],
request_id=request_id,
)
import { Sandboxes } from "pethost/sandboxes";
const sandboxes = new Sandboxes({ token: process.env.PETHOST_TOKEN! });
const requestId = crypto.randomUUID(); // Keep it: a retry sends the same one.
const sandbox = await sandboxes.createSandbox({
template: "my-app",
labels: [{ key: "user", value: "42" }, { key: "job", value: "nightly-evals" }],
requestId,
});
requestID := rand.Text() // crypto/rand. Keep it: a retry sends the same one.
sandbox, err := client.CreateSandbox(ctx, &sandboxes.CreateSandboxRequest{
Template: "my-app",
Labels: []sandboxes.Label{{Key: "user", Value: "42"}, {Key: "job", Value: "nightly-evals"}},
RequestID: requestID,
})
let request_id = uuid::Uuid::new_v4().to_string(); // Keep it: a retry sends the same one.
let sandbox = sandboxes
.create_sandbox(CreateSandboxRequest {
template: "my-app".into(),
labels: vec![
Label { key: "user".into(), value: "42".into() },
Label { key: "job".into(), value: "nightly-evals".into() },
],
request_id: request_id.clone(),
..Default::default()
})
.await?;
CreateSandbox {"template": "my-app", "labels": [{"key": "user", "value": "42"}], "request_id": "b7e1c2d4-0f3a-4c55-9a7e-2d1f6c8e9a10"}
curl https://console.pethost.dev/pethost.sandboxes.v1.SandboxService/CreateSandbox \
-H "Authorization: Bearer $PETHOST_TOKEN" \
-H "Content-Type: application/json" \
-d '{"template": "my-app", "labels": [{"key": "user", "value": "42"}], "request_id": "b7e1c2d4-0f3a-4c55-9a7e-2d1f6c8e9a10"}'
Транслюйте замість опитування
Опитування команди чи пісочниці щоразу коштує виклику й однаково дізнається пізно. Виклик, що чекає, чекає за вас: RunCommand, GetCommand, PromptAgent і GetAgentTurn чекають до 45 с (wait_seconds) і відповідають, щойно робота закінчиться. Щоб стежити за роботою, поки вона йде, транслюйте її: WatchCommand — вивід команди, WatchConversation — повідомлення агента й виклики інструментів, WatchSandboxEvents — життєвий цикл пісочниці, команди й з’єднання.
Використовуйте томи лише для того, що має пережити пісочницю
Том — це диск поза будь-якою пісочницею, змонтований за шляхом: набори даних, кеші, спільні для багатьох пісочниць, файли бази даних. Він лежить на диску одного сервера й нікуди не копіюється, тож якщо цей сервер утрачено, утрачено й том. Пісочниця, що його монтує, не може переїхати на інший сервер, а монтування для читання й запису не дає її копіювати. Більшості робіт том не потрібен: власний диск пісочниці переживає паузи й зупинки, а шаблон переносить файли в нові пісочниці. Те, що не можна втратити, надсилайте ще й у власне сховище.
Безпека
Прив’язуйте API-ключі як секрети
Ключ у звичайній змінній середовища може прочитати кожен процес у пісочниці й агент, що виведе своє середовище. Натомість збережіть його як секрет робочого простору, із хостами, для яких він призначений (SetSecret: anthropic, api.anthropic.com), і прив’яжіть до нього змінну (ANTHROPIC_API_KEY, секрет anthropic). Тоді змінна містить заглушку, phs_…, а проксі вихідного трафіку підставляє справжній ключ у заголовки HTTPS-запитів лише до цих хостів. Нове значення одразу працює в кожній пісочниці, що його прив’язує: секрети й вихідний трафік.
Звужуйте вихідний трафік для чужого коду
Типово пісочниця може підключатися куди завгодно. Для коду, якому ви не довіряєте, перелічіть, куди йому можна (egress.allow): домен, як-от pypi.org, його піддомени через *.github.com (без самого github.com), IP або CIDR, кожен із портом, якщо це не 80 і 443, як github.com:22 для git по SSH. deny має перевагу над allow. DNS пісочниці відповідає лише на імена, які дозволяє список, і з пісочниці виходять лише TCP і DNS: ні UDP, ні ping. Зміна діє одразу й закриває з’єднання, яких більше не дозволяє.
Вважайте те, що повертає пісочниця, даними
Вивід команд, вміст файлів, повідомлення агента, скриншоти й сторінки, які завантажує браузер, походять від програм та з інтернету. Коли їх читає модель, вони є даними, а не інструкціями: README чи вебсторінка може містити текст, написаний, щоб керувати агентом. Тримайте цю межу у своїх промптах і не давайте пісочниці, що виконує неперевірену роботу, більше секретів і ширшого вихідного трафіку, ніж потрібно для роботи.
Порядок
Ставте мітку на кожну пісочницю
Мітка — це ваші ключ і значення: user=42, job=nightly-evals, run=7f3a. Міток у пісочниці може бути до 32, а ListSandboxes перелічує пісочниці, що мають усі названі вами мітки. Тож ваш застосунок знаходить пісочниці користувача без власної таблиці, задача прибирання знаходить залишки прогону, а панель показує, чия кожна пісочниця. Мітка — щоб знаходити багато; name — щоб звертатися до однієї: унікальна в робочому просторі, з a-z, 0-9 і «-», не довша за 63 символи, а ListSandboxes з name знаходить її id.
Запитання
Пісочницю в простої краще зупинити чи поставити на паузу?
Ставте на паузу, коли її процеси важливі або вона скоро знадобиться знову: вона прокинеться приблизно за 0,1 с там, де була, за 30% ціни роботи. Зупиняйте для довгого сну: тоді вона коштує лише своїх збережених даних.
Як зробити, щоб пісочниці стартували швидше?
Збережіть своє середовище як шаблон, щоб під час запуску нічого не встановлювалося: пісочниця з нього запускається приблизно за 0,22 с з вашими пакетами й образами Docker.
Як не пускати API-ключі в пісочницю?
Збережіть кожен ключ як секрет робочого простору з його хостами й прив’яжіть до нього змінну середовища. Пісочниця бачить заглушку, а проксі вихідного трафіку додає справжній ключ до запитів до цих хостів.
Скільки пісочниць можна запускати одночасно?
Стільки, скільки вміщують vCPU вашого тарифу, і тих, що працюють, і на паузі: 10 SMALL на тарифі за 20 $, 64 на тарифі за 100 $. Зупинені пісочниці не рахуються.
Спробуйте Pethost Agent Sandboxes
Пробний період на 7 днів із використанням на 1 $ і 4 vCPU, потрібна картка. Далі — тариф від 20 $ на місяць, який включає стільки ж використання.