Документация 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
Dev-серверу нужно мгновение, чтобы начать слушать порт, а опрос снаружи тратит вызовы. Запускайте его с wait_for_port: RunCommand отвечает, как только на этом порту кто-то слушает, а команда продолжает работать, так что один вызов запускает сервер и сообщает, что он поднялся. Затем откройте порт публично или дайте своей странице токен для него: порты и превью.
Делайте форки для параллельных попыток
Когда агенту нужно попробовать несколько исправлений или эвалу — начать много запусков из одного подготовленного состояния, сделайте форк песочницы, а не собирайте это состояние заново. ForkSandbox одним вызовом копирует память, процессы и диск в новые песочницы, до 100 штук: копия заняла около 0,25 с. Каждая копия — это запуск, и создаются либо все, либо ни одной. Две вещи стоит знать:
- Переинициализируйте генераторы случайных чисел в копиях. У каждой копии своя случайность ядра, но генераторы, уже работающие в ее процессах (OpenSSL, Python, Node, Go), выдают в каждой копии одни и те же числа, пока их не переинициализировать.
- Том на запись не дает сделать форк, ведь писать в него может только одна песочница. Том подключается только при создании, поэтому в песочнице, которую собираетесь копировать, подключайте его с
read_only.
Стоимость
Пусть песочница агента встает на паузу, а не останавливается
Песочница агента большую часть времени ждет, а остановка завершает ее процессы: dev-сервер, 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 с новым размером перезапускает работающую песочницу в ВМ этого размера примерно за 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 — чтобы обращаться к одной: оно уникально в рабочем пространстве, до 63 символов из a-z, 0-9 и «-», и ListSandboxes с name находит ее ID.
Вопросы
Останавливать простаивающую песочницу или ставить на паузу?
Ставьте на паузу, когда важны ее процессы или она скоро понадобится снова: она проснется примерно за 0,1 с там, где была, за 30 % цены работы. Останавливайте для долгого сна: тогда она стоит только своих хранимых данных.
Как ускорить запуск песочниц?
Сохраните окружение как шаблон, чтобы при запуске ничего не устанавливалось: песочница из него запускается примерно за 0,22 с с вашими пакетами и образами Docker.
Как не пускать API-ключи в песочницу?
Сохраните каждый ключ как секрет рабочего пространства с его хостами и привяжите к нему переменную окружения. Песочница видит заглушку, а прокси исходящего трафика добавляет настоящий ключ в запросы к этим хостам.
Сколько песочниц можно запустить одновременно?
Столько, сколько вмещают vCPU вашего тарифа, работающих или на паузе: 10 песочниц SMALL на тарифе за 20 $, 64 — на тарифе за 100 $. Остановленные песочницы не считаются.
Попробуйте Pethost Agent Sandboxes
Пробный период на 7 дней: 1 $ использования и 4 vCPU, нужна карта. Затем тариф от 20 $ в месяц, в который входит столько же использования.