Документація Agent Sandboxes · Початок
Підключіть агента до пісочниць через MCP
Пісочниці як інструменти вашого агента: додайте MCP-сервер Pethost Agent Sandboxes, https://mcp.pethost.dev/sandboxes, у Claude Code, Codex, Cursor чи Claude, увійдіть у браузері, і агент сам створюватиме, копіюватиме, ставитиме на паузу й видалятиме пісочниці.
- Одна адреса:
https://mcp.pethost.dev/sandboxes, streamable HTTP, вхід через OAuth. Жодного ключа вставляти не треба. - Робочий простір вибираєте ви: сторінка входу пропонує ваші робочі простори пісочниць, і токен агента відкриває лише ті, які ви виберете.
- 13 інструментів для робочого простору й запису кожної пісочниці. Команди й файли йдуть на власний сервер пісочниці, до якого агент дістається через
ConnectSandboxі CLIpethostабоcurl. - Окремо від App Platform: власний конектор, тож агент, налаштований для одного, ніколи не бачить інструментів іншого.
Step 1: Додайте сервер у Claude Code
claude mcp add --transport http pethost-sandboxes https://mcp.pethost.dev/sandboxes
Або встановіть плагін, що приносить сервер і скіл, який підказує Claude, коли і як користуватися пісочницями: claude plugin marketplace add pethost-dev/plugin, потім claude plugin install pethost-sandboxes@pethost.
Step 2: Увійдіть
У Claude Code виконайте /mcp, виберіть pethost-sandboxes і пройдіть автентифікацію. Браузер відкриє сторінку підтвердження Pethost: увійдіть, виберіть робочий простір пісочниць, яким може користуватися агент, і натисніть «Підключити».
Step 3: Попросіть щось, для чого потрібен комп’ютер
«Створи пісочницю, склонуй цей репозиторій і запусти його тести». Агент читає робочий простір, створює пісочницю з base і працює в ній.
Ви кажете: Створи пісочницю, склонуй https://github.com/pallets/click і запусти його тести.
- CreateSandbox {"name": "click-tests"}
- ConnectSandbox {"sandbox_id": "lelb0x9iq6pvk7t8", "ttl_seconds": 3600}
- Bash curl …/SandboxRuntimeService/RunCommand: git clone -q https://github.com/pallets/click
- Bash curl …/SandboxRuntimeService/RunCommand: python3 -m venv .venv && .venv/bin/pip install -q -e . pytest && .venv/bin/python -m pytest -q
Агент відповідає: Усі тести click пройшли в новій пісочниці: 2628 passed, 24 skipped, 1 xfailed, 0 failed (код виходу pytest 0). … Пісочниця стане на паузу після 5 хв простою і зупиниться після 30, але автоматично не видаляється. Видалити її чи лишити для подальшої роботи?
Codex
Плагін для CLI і десктопного застосунку приносить сервер і скіл: codex plugin marketplace add pethost-dev/plugin, потім codex plugin add pethost-sandboxes@pethost. Ви входите в браузері, як із Claude Code, і там вибираєте робочий простір.
Cursor
Додайте сервер у ~/.cursor/mcp.json або в .cursor/mcp.json проєкту, потім увімкніть його в налаштуваннях MCP у Cursor, які почнуть вхід:
{
"mcpServers": {
"pethost-sandboxes": { "url": "https://mcp.pethost.dev/sandboxes" }
}
}
Claude у вебі й на десктопі
У налаштуваннях Claude відкрийте Connectors, додайте власний конектор і дайте йому адресу https://mcp.pethost.dev/sandboxes. Claude відкриє сторінку входу; потім увімкніть конектор у розмові.
Будь-який інший агент
Будь-який MCP-клієнт, що говорить streamable HTTP і входить через OAuth, приймає адресу https://mcp.pethost.dev/sandboxes. Hermes Agent: hermes mcp add pethost-sandboxes --url https://mcp.pethost.dev/sandboxes --auth oauth. Скіл для агента, що читає скіли: npx skills add pethost-dev/plugin --skill pethost-sandboxes. Агент, якому дали лише сервер, читає натомість його інструкції, де сказано, з чого почати.
Інструменти
Інструменти сервера — це виклики SandboxService, половини API, яку обслуговує панель, кожен із тими самими назвою, полями й відповідями, що й у довіднику API:
| Інструмент | Що робить |
|---|---|
GetWorkspace | Ліміти робочого простору, розміри й ціни, назви його секретів і SSH-ключі. |
ListSandboxes | Його пісочниці, найновіші першими, за станом, міткою чи назвою. |
CreateSandbox | Пісочниця із шаблону; відповідь — щойно вона запрацює. |
GetSandbox | Одна пісочниця: її стан і причина, налаштування, як до неї дістатися, використання. |
UpdateSandbox | Її назва, розмір, життєвий цикл, вихідний трафік, публічні порти чи середовище. |
PauseSandbox | Поставити на паузу, зі збереженими пам’яттю й процесами. |
StopSandbox | Зупинити, зі збереженим диском. |
ResumeSandbox | Знову запустити пісочницю на паузі чи зупинену. |
ForkSandbox | Скопіювати її, разом із пам’яттю й процесами, у нові пісочниці. |
DeleteSandbox | Видалити її, разом із пам’яттю й диском, назавжди. |
ConnectSandbox | Сервер пісочниці, токен для неї та її команда SSH. |
CreateTemplate | Зберегти диск пісочниці як шаблон. |
ListTemplates | Наші шаблони й шаблони робочого простору. |
Команди й файли: на власному сервері пісочниці
На те, що працює в пісочниці, її команди, файли, робочий стіл, посилання й агентів для коду, відповідає сервер, на якому вона працює, і ніколи панель. Тому MCP-сервер на mcp.pethost.dev/sandboxes не має RunCommand: агент викликає ConnectSandbox, що відповідає url сервера, token лише для цієї пісочниці та її ssh_command, а далі працює там сам:
- Через CLI
pethost, якщо в агента є оболонка:pethost sandbox run <id> -- npm test,pethost sandbox cp ./app <id>:app,pethost sandbox shell <id>. - Через
curl: будь-який викликSandboxRuntimeServiceза назвою, у Connect JSON з тими самими назвами полів, що й в інструментів. - Без оболонки агент дає вам
panel_urlпісочниці, де після входу є її термінал і робочий стіл.
curl -s "$URL/pethost.sandboxes.v1.SandboxRuntimeService/RunCommand" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"sandbox_id": "'"$ID"'", "command": "npm test"}'
Токен дає root у цій пісочниці: інструкції сервера й скіл кажуть агентові тримати його в змінній оболонки й ніколи не виводити в розмові.
Токен лише для цього сервера
Вхід дає агентові API-токен Pethost, адресований цьому серверу: він працює на mcp.pethost.dev/sandboxes і в API пісочниць, а MCP-сервер App Platform його відхиляє, як і тут відхиляють токен App Platform. Він відкриває лише вибрані вами робочі простори. «Налаштування» вашого акаунта показують його під іменем агента, разом із тим, що він відкриває, і там його можна відкликати.
Чому це окремий конектор
App Platform і Agent Sandboxes — два продукти з різними інструментами й різним читачем: агентом, що деплоїть ваші застосунки, і агентом, якому потрібні комп’ютери для виконання коду. Кожен має власні сервер, назву, значок, інструменти й токени, тож агент, налаштований для одного, ніколи не читає інструментів іншого й не плутає їх. В акаунт з обома додайте обидва: сервер App Platform — https://mcp.pethost.dev/mcp.
Коли не працює
- Сторінка входу не пропонує жодного робочого простору: вона пропонує лише робочі простори пісочниць. Спершу створіть такий у панелі, вибравши Agent Sandboxes.
- Агент каже, що не ввійшов, або його виклики відповідають 401: токен відкликано, або агент увійшов на сервер App Platform. Увійдіть знову з агента (
/mcpу Claude Code). - Інструмент відповідає
WorkspaceChoice: токен відкриває кілька робочих просторів пісочниць. Скажіть агентові, який саме; він надсилатиме свійworkspaceу кожному виклику. - Агент шукає
RunCommand: це не інструмент цього сервера. Спрямуйте його доConnectSandboxі CLI або встановіть плагін, чий скіл про це каже. RESOURCE_EXHAUSTEDзLimitReached: vCPU робочого простору зайняті його пісочницями, що працюють і на паузі. Попросіть агента видалити ті, які йому більше не потрібні.
Запитання
Яка адреса MCP-сервера?
https://mcp.pethost.dev/sandboxes, streamable HTTP, вхід через OAuth у браузері.
Які агенти працюють із Pethost Agent Sandboxes?
Будь-який агент, що підключає віддалений MCP-сервер: Claude Code, Codex, Cursor, Claude у вебі й на десктопі, Hermes Agent та інші. Claude Code і Codex можуть установити плагін, що додає скіл.
Чи може агент виконувати команди в пісочниці через MCP?
Через власний сервер пісочниці: ConnectSandbox дає його адресу й токен, а агент виконує команди через CLI pethost або curl. Сам MCP-сервер створює, змінює, ставить на паузу, копіює й видаляє пісочниці.
Чи отримує агент мої API-ключі?
Ні. Він отримує токен для робочих просторів, які ви виберете. Ключі моделей і сервісів — це секрети робочого простору, яких ніколи не тримає жодна пісочниця й не містить жодна відповідь інструмента.
Це той самий сервер, що й у Pethost App Platform?
Ні: сервер App Platform — https://mcp.pethost.dev/mcp. Кожен має власні інструменти й токени.
Спробуйте Pethost Agent Sandboxes
Пробний період на 7 днів із використанням на 1 $ і 4 vCPU, потрібна картка. Далі — тариф від 20 $ на місяць, який включає стільки ж використання.