Русский
Меню документации

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

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