Русский
Начать

Agent Sandboxes Команды, файлы и терминал

Песочница для выполнения кода ИИ-агентов

Ваша модель пишет код, песочница его запускает, и вывод возвращается в том же вызове. Команды, файлы и терминалы — один API, на который отвечает сервер, где работает песочница, а не панель.

Выполнение кода за один вызов

Каждая песочница — микроВМ Firecracker с собственным ядром Linux и root внутри, которая запускается из нашего шаблона base примерно за 0,15 с: Ubuntu 24.04 с инструментами сборки, Python 3, Node.js 22 и Docker. run_command выполняет команду через bash -lc от имени user, у которого есть sudo, или от имени root, в любой указанной папке. Вызов ждет завершения команды до 45 секунд и возвращает ее код выхода и последние 32 KiB ее stdout и stderr.

Три поля меняют то, чего ждет вызов:

  • wait_for_port отвечает, как только кто-то начинает слушать порт, а команда продолжает работать: npm run dev и 5173.
  • wait_seconds=0 отвечает, как только команда запустилась. get_command снова ждет ее, а watch_command отдает ее вывод потоком: сначала последние 64 KiB, потом вживую.
  • timeout_seconds завершает команду, которая работает слишком долго. Без него команду завершает только stop_command: SIGTERM, а через 10 с SIGKILL.

Каждый ответ сообщает, сколько байтов команда уже записала; передайте это число обратно, и следующий ответ будет содержать только новое. С request_id повтор в течение 24 часов ничего не запускает заново и возвращает то же, что ответил первый вызов. list_commands показывает, что работает сейчас, включая команды, набранные по SSH, а последние 100 завершившихся хранятся.

from pethost.sandboxes import FileChange, Sandboxes, TextEdit

sandboxes = Sandboxes()  # читает PETHOST_TOKEN
box = sandboxes.create_sandbox()
code = "x = 1\nprint(x * 42)\n"
sandboxes.write_files(box.sandbox_id, changes=[FileChange(path="app.py", text=code)])
out = sandboxes.run_command(box.sandbox_id, command="python3 app.py", timeout_seconds=30)
print(out.exit_code, out.stdout)  # 0 42

edit = TextEdit(old_text="x = 1", new_text="x = 2")
sandboxes.write_files(box.sandbox_id, changes=[FileChange(path="app.py", edit=edit)])
server = sandboxes.run_command(box.sandbox_id, command="python3 -m http.server 8000",
                               wait_for_port=8000)
print(server.state.name)  # RUNNING: вызов ответил, как только порт 8000 начали слушать
pethost sandbox new --name tests --size small
pethost sandbox cp ./app tests:/home/user/app
pethost sandbox run tests --cwd /home/user/app -- python3 -m unittest
pethost sandbox open tests --terminal

Файлы: пакеты изменений и точные правки

write_files принимает список изменений и выполняет их по порядку: записать текст или байты файла, заменить текст, который встречается в нем ровно один раз, переместить, удалить, создать папку, задать права. Недостающие родительские папки создаются. Он останавливается на первом изменении, которое не удалось, и сообщает, на каком, с причиной, на которую может реагировать код, например что заменяемого текста нет. Так правка попадает только туда, где есть ее текст. Запрос несет до 17 MiB.

read_file читает до 1 MiB с любого смещения, list_files показывает содержимое папки на любую глубину, а watch_files потоком отдает каждое изменение внутри нее. Файл любого размера передается по ссылке из create_link: URL для скачивания отдает файл или папку в виде .tar, URL для загрузки принимает PUT. Каждая ссылка работает один раз.

Терминал в браузере

create_link с терминалом дает страницу, где запущен bash или команда вроде claude, и WebSocket по тому же URL, который передает ее байты, — для терминала внутри вашего собственного продукта. По умолчанию ссылка живет час, максимум — сутки.

Что работает внутри

Docker работает в каждой песочнице: dockerd запускается при первом подключении к его сокету и хранит образы на диске песочницы, поэтому они переживают остановку и переносятся шаблоном. Остальное ставится через apt, с sudo.

Вызовы идут прямо на сервер песочницы, который SDK находит сам. Первая команда после создания отвечает за 29–48 ms. На сервере с 74 песочницами, каждая из которых собирала проект на JavaScript и ждала между сборками, как это делает агент, простая команда занимала 6 ms (28 ms на 95-м перцентиле).

Ограничения и цены

ЧтоОграничение
Одновременных вызовов на песочницу64; write_files считается за 16
Запрос1 MiB; write_files — 17 MiB
Ответоколо 64 KiB; read_file — 1 MiB; любой размер — по ссылке
Вывод в ответепоследние 32 KiB stdout и столько же stderr

У команд, файлов и ссылок нет собственной цены: вы платите за секунды работы песочницы, от 0,018 $ в час для SMALL (2 vCPU, 4 GiB) до 0,144 $ для XLARGE (16 vCPU, 32 GiB), каждый запуск округляется вверх до секунды, минимум 10 с. После 5 минут простоя она встает на паузу за 30% от этой цены. Как устроена посекундная оплата.

Сравнение с другими

На 21 ноября 2026 года E2B брал 0,1656 $ в час за песочницу на 2 vCPU и 4 GiB, как и Daytona; SMALL в Pethost, того же размера, стоит 0,018 $. Сессии E2B длились до 1 часа на тарифе Hobby и до 24 часов на Pro, у Vercel Sandbox — 45 минут на Hobby и 24 часа на Pro. У песочницы Pethost нет ограничения на срок жизни.

Читать документацию

Вопросы

Какие языки можно запускать в песочнице для выполнения кода?

Все, что работает в Linux. Python 3 и Node.js 22 установлены, Docker работает, а остальное ставится через apt. Сохраните песочницу со своими инструментами как шаблон, и новые песочницы будут запускаться уже с ними.

Сколько может работать команда?

Сколько нужно: один вызов ждет до 45 секунд, потом вы читаете ее вывод или получаете его потоком. После 5 минут простоя песочница встает на паузу вместе с командой в памяти, и та продолжает работу при следующем вызове. Команда, запущенная с keep_awake, работает без перерыва, как и команда, за которой вы следите через watch_command.

Есть ли у кода доступ в интернет?

Да, по TCP: по умолчанию песочница может подключаться куда угодно. Список разрешенных адресов сужает это до доменов, IP и портов, которые вы назовете. UDP из песочницы не выходит.

Как передавать большие файлы?

По ссылке для скачивания или загрузки, любого размера, или через scp по SSH.

По теме

Дайте агенту компьютер за 0,15 с

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