Español
Menú de la documentación

Documentación de Agent Sandboxes · Primeros pasos

Conecta un agente a los sandboxes por MCP

Actualizado · 6 min de lectura

Sandboxes como herramientas de tu agente: agrega el servidor MCP de Pethost Agent Sandboxes, https://mcp.pethost.dev/sandboxes, a Claude Code, Codex, Cursor o Claude, inicia sesión en tu navegador, y el agente crea, copia, pausa y elimina sandboxes por su cuenta.

En resumen
  • Una dirección: https://mcp.pethost.dev/sandboxes, Streamable HTTP, inicio de sesión por OAuth. Ninguna clave que pegar.
  • Tú eliges el espacio de trabajo: la página de inicio de sesión ofrece tus espacios de trabajo de sandboxes, y el token del agente solo llega a los que elijas.
  • 13 herramientas para el espacio de trabajo y el registro de cada sandbox. Los comandos y los archivos van al propio servidor del sandbox, al que el agente llega con ConnectSandbox y la CLI pethost o curl.
  • Aparte de App Platform: un conector propio, así que un agente configurado para uno nunca ve las herramientas del otro.

Step 1: Agrega el servidor a Claude Code

claude mcp add --transport http pethost-sandboxes https://mcp.pethost.dev/sandboxes

O instala el plugin, que trae el servidor y una skill que le dice a Claude cuándo y cómo usar los sandboxes: claude plugin marketplace add pethost-dev/plugin, y después claude plugin install pethost-sandboxes@pethost.

Step 2: Inicia sesión

En Claude Code, ejecuta /mcp, elige pethost-sandboxes y autentícate. Tu navegador abre la página de aprobación de Pethost: inicia sesión, elige el espacio de trabajo de sandboxes que puede usar el agente y pulsa Conectar.

Step 3: Pide algo que necesite una máquina

“Crea un sandbox, clona este repositorio y ejecuta sus tests.” El agente lee el espacio de trabajo, crea un sandbox desde base y trabaja en él.

Claude Code

Tú dices: Crea un sandbox, clona https://github.com/pallets/click y ejecuta sus tests.

  • 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

El agente responde: Todos los tests de click pasaron en un sandbox nuevo: 2628 pasados, 24 omitidos, 1 xfailed, 0 fallidos (código de salida de pytest 0). … El sandbox se pausará tras 5 minutos inactivo y se detendrá tras 30, pero no se elimina solo. ¿Lo elimino o lo dejo para más trabajo?

Codex

El plugin, para la CLI y la app de escritorio, trae el servidor y la skill: codex plugin marketplace add pethost-dev/plugin, y después codex plugin add pethost-sandboxes@pethost. Inicias sesión en tu navegador, como con Claude Code, y eliges ahí el espacio de trabajo.

Cursor

Agrega el servidor a ~/.cursor/mcp.json, o a .cursor/mcp.json en un proyecto, y actívalo en los ajustes de MCP de Cursor, que abren el inicio de sesión:

{
  "mcpServers": {
    "pethost-sandboxes": { "url": "https://mcp.pethost.dev/sandboxes" }
  }
}

Claude en la web y en el escritorio

En los ajustes de Claude, abre Conectores, agrega un conector personalizado y dale la dirección https://mcp.pethost.dev/sandboxes. Claude abre la página de inicio de sesión; después activa el conector en una conversación.

Cualquier otro agente

Cualquier cliente MCP que hable Streamable HTTP e inicie sesión por OAuth acepta la dirección https://mcp.pethost.dev/sandboxes. Hermes Agent: hermes mcp add pethost-sandboxes --url https://mcp.pethost.dev/sandboxes --auth oauth. La skill, para un agente que lee skills: npx skills add pethost-dev/plugin --skill pethost-sandboxes. Un agente que solo tiene el servidor lee en su lugar sus instrucciones, que dicen por dónde empezar.

Las herramientas

Las herramientas del servidor son las llamadas de SandboxService, la mitad de la API que es del panel, cada una con el mismo nombre, los mismos campos y las mismas respuestas que en la referencia de la API:

HerramientaQué hace
GetWorkspaceLos límites, tamaños y precios del espacio de trabajo, los nombres de sus secretos y sus claves SSH.
ListSandboxesSus sandboxes, los más recientes primero, por estado, etiqueta o nombre.
CreateSandboxUn sandbox desde una plantilla, que responde una vez en ejecución.
GetSandboxUn sandbox: su estado y por qué, sus ajustes, cómo llegar a él, su uso.
UpdateSandboxSu nombre, tamaño, ciclo de vida, salida, puertos públicos o entorno.
PauseSandboxLo pausa, con la memoria y los procesos conservados.
StopSandboxLo detiene, con su disco conservado.
ResumeSandboxVuelve a iniciar uno en pausa o detenido.
ForkSandboxLo copia, memoria y procesos incluidos, en sandboxes nuevos.
DeleteSandboxLo elimina, con su memoria y su disco, para siempre.
ConnectSandboxEl servidor del sandbox, un token para él y su comando SSH.
CreateTemplateGuarda el disco de un sandbox como plantilla.
ListTemplatesNuestras plantillas y las del espacio de trabajo.

Comandos y archivos: en el propio servidor del sandbox

Lo que se ejecuta dentro de un sandbox, sus comandos, archivos, escritorio, enlaces y agentes de programación, lo responde el servidor en el que se ejecuta el sandbox, nunca el panel. Por eso el servidor MCP de mcp.pethost.dev/sandboxes no tiene RunCommand: el agente llama a ConnectSandbox, que responde la url del servidor, un token solo para ese sandbox y su ssh_command, y después trabaja ahí por su cuenta:

  • Con la CLI pethost, donde el agente tiene una shell: pethost sandbox run <id> -- npm test, pethost sandbox cp ./app <id>:app, pethost sandbox shell <id>.
  • Con curl, cualquier llamada de SandboxRuntimeService por su nombre, en JSON de Connect con los nombres de campo que usan las herramientas.
  • Sin shell, el agente te da el panel_url del sandbox, donde están su terminal y su escritorio, una vez que inicias sesión.
curl -s "$URL/pethost.sandboxes.v1.SandboxRuntimeService/RunCommand" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"sandbox_id": "'"$ID"'", "command": "npm test"}'

El token es root en ese sandbox: las instrucciones del servidor y la skill le dicen al agente que lo guarde en una variable de la shell y que nunca lo imprima en la conversación.

Un token solo para este servidor

El inicio de sesión le da al agente un token de API de Pethost cuya audiencia es este servidor: funciona en mcp.pethost.dev/sandboxes y en la API de los sandboxes, y se rechaza en el servidor MCP de App Platform, igual que el token de App Platform se rechaza aquí. Solo llega a los espacios de trabajo que elegiste. Los Ajustes de tu cuenta lo listan con el nombre del agente, con lo que alcanza, y lo revocan.

Por qué es un conector propio

App Platform y Agent Sandboxes son dos productos con herramientas distintas y pensados para un lector distinto: un agente que despliega tus apps, y un agente que necesita máquinas en las que ejecutar código. Cada uno tiene su propio servidor, nombre, icono, herramientas y tokens, así que un agente configurado para uno nunca lee las del otro, ni las confunde. Una cuenta con los dos agrega los dos: el de App Platform es https://mcp.pethost.dev/mcp.

Cuando no funciona

  • La página de inicio de sesión no ofrece ningún espacio de trabajo: solo ofrece espacios de trabajo de sandboxes. Crea antes uno en el panel, eligiendo Agent Sandboxes.
  • El agente dice que no tiene la sesión iniciada, o sus llamadas responden 401: el token se revocó, o el agente inició sesión en el servidor de App Platform. Vuelve a iniciar sesión desde el agente (/mcp en Claude Code).
  • Una herramienta responde WorkspaceChoice: el token llega a varios espacios de trabajo de sandboxes. Dile al agente cuál; enviará su workspace en cada llamada.
  • El agente busca RunCommand: no es una herramienta de este servidor. Indícale ConnectSandbox y la CLI, o instala el plugin, cuya skill lo dice.
  • RESOURCE_EXHAUSTED con LimitReached: las vCPU del espacio de trabajo las ocupan sus sandboxes en ejecución y en pausa. Pide al agente que elimine los que ya no necesita.

Preguntas

¿Cuál es la dirección del servidor MCP?

https://mcp.pethost.dev/sandboxes, Streamable HTTP, con inicio de sesión por OAuth en tu navegador.

¿Qué agentes funcionan con Pethost Agent Sandboxes?

Cualquier agente que acepte un servidor MCP remoto: Claude Code, Codex, Cursor, Claude en la web y en el escritorio, Hermes Agent y otros. Claude Code y Codex pueden instalar el plugin, que agrega una skill.

¿Puede el agente ejecutar comandos en un sandbox por MCP?

A través del propio servidor del sandbox: ConnectSandbox da su dirección y un token, y el agente ejecuta comandos con la CLI pethost o curl. El propio servidor MCP crea, cambia, pausa, copia y elimina sandboxes.

¿El agente recibe mis claves de API?

No. Recibe un token para los espacios de trabajo que elijas. Las claves de modelos y servicios son secretos del espacio de trabajo, que ningún sandbox ni ninguna respuesta de herramienta tienen nunca.

¿Es el mismo servidor que el de Pethost App Platform?

No: el de App Platform es https://mcp.pethost.dev/mcp. Cada uno tiene sus propias herramientas y tokens.

Prueba Pethost Agent Sandboxes

Una prueba gratis de 7 días con 1 US$ de uso y 4 vCPU, con tarjeta. Después, un plan desde 20 US$ al mes, que incluye ese mismo importe en uso.

Empezar la prueba gratis