Українська
Почати

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

Пісочниця для виконання коду ШІ-агентів

Ваша модель пише код, пісочниця його виконує, а вивід повертається в тому самому виклику. Команди, файли й термінали — це один API, і відповідає на нього сервер, на якому працює пісочниця, а не панель.

Виконання коду одним викликом

Кожна пісочниця — це microVM 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 с

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