Українська
Меню документації

Документація Agent Sandboxes · Початок

Підключіть агента до пісочниць через MCP

Оновлено · 5 хв читання

Пісочниці як інструменти вашого агента: додайте MCP-сервер Pethost Agent Sandboxes, https://mcp.pethost.dev/sandboxes, у Claude Code, Codex, Cursor чи Claude, увійдіть у браузері, і агент сам створюватиме, копіюватиме, ставитиме на паузу й видалятиме пісочниці.

Коротко
  • Одна адреса: https://mcp.pethost.dev/sandboxes, streamable HTTP, вхід через OAuth. Жодного ключа вставляти не треба.
  • Робочий простір вибираєте ви: сторінка входу пропонує ваші робочі простори пісочниць, і токен агента відкриває лише ті, які ви виберете.
  • 13 інструментів для робочого простору й запису кожної пісочниці. Команди й файли йдуть на власний сервер пісочниці, до якого агент дістається через ConnectSandbox і CLI pethost або 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 і працює в ній.

Claude Code

Ви кажете: Створи пісочницю, склонуй 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 $ на місяць, який включає стільки ж використання.

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