Документация 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 откройте «Коннекторы», добавьте свой коннектор и укажите адрес 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 $ в месяц, в который входит столько же использования.