Português
Menu da documentação

Docs do Agent Sandboxes · Começar

Conecte um agente aos sandboxes por MCP

Atualizado em · 6 min de leitura

Sandboxes como ferramentas do seu agente: adicione o servidor MCP do Pethost Agent Sandboxes, https://mcp.pethost.dev/sandboxes, ao Claude Code, ao Codex, ao Cursor ou ao Claude, entre pelo navegador, e o agente cria, faz fork, pausa e exclui sandboxes sozinho.

Em resumo
  • Um endereço: https://mcp.pethost.dev/sandboxes, HTTP streamable, login por OAuth. Nenhuma chave para colar.
  • Você escolhe o espaço de trabalho: a página de login oferece os seus espaços de trabalho de sandboxes, e o token do agente só alcança os que você escolher.
  • 13 ferramentas para o espaço de trabalho e o registro de cada sandbox. Comandos e arquivos vão para o servidor do próprio sandbox, que o agente alcança com ConnectSandbox e a CLI pethost ou o curl.
  • Separado do App Platform: um conector próprio, para que um agente configurado para um nunca veja as ferramentas do outro.

Step 1: Adicione o servidor ao Claude Code

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

Ou instale o plugin, que traz o servidor e uma skill que diz ao Claude quando e como usar sandboxes: claude plugin marketplace add pethost-dev/plugin, depois claude plugin install pethost-sandboxes@pethost.

Step 2: Entre

No Claude Code, rode /mcp, escolha pethost-sandboxes e faça a autenticação. O navegador abre a página de aprovação do Pethost: entre, escolha o espaço de trabalho de sandboxes que o agente pode usar e clique em Conectar.

Step 3: Peça algo que precise de um computador

“Crie um sandbox, clone este repositório e rode os testes.” O agente lê o espaço de trabalho, cria um sandbox a partir do base e trabalha nele.

Claude Code

Você diz: Crie um sandbox, clone https://github.com/pallets/click e rode os testes.

  • 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

O agente responde: Todos os testes do click passaram em um sandbox novo: 2.628 passaram, 24 foram pulados, 1 xfailed, 0 falharam (código de saída 0 do pytest). … O sandbox vai pausar depois de 5 minutos ocioso e parar depois de 30, mas não é excluído automaticamente. Quer que eu o exclua, ou que o mantenha para mais trabalho?

Codex

O plugin, para a CLI e o app desktop, traz o servidor e a skill: codex plugin marketplace add pethost-dev/plugin, depois codex plugin add pethost-sandboxes@pethost. Você entra pelo navegador, como no Claude Code, e escolhe o espaço de trabalho lá.

Cursor

Adicione o servidor a ~/.cursor/mcp.json, ou a .cursor/mcp.json em um projeto, depois ative-o nas configurações de MCP do Cursor, que iniciam o login:

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

Claude na web e no desktop

Nas configurações do Claude, abra Conectores, adicione um conector personalizado e dê a ele o endereço https://mcp.pethost.dev/sandboxes. O Claude abre a página de login; depois ative o conector em uma conversa.

Qualquer outro agente

Qualquer cliente MCP que fale HTTP streamable e faça login por OAuth aceita o endereço https://mcp.pethost.dev/sandboxes. Hermes Agent: hermes mcp add pethost-sandboxes --url https://mcp.pethost.dev/sandboxes --auth oauth. A skill, para um agente que lê skills: npx skills add pethost-dev/plugin --skill pethost-sandboxes. Um agente que recebe só o servidor lê as instruções dele, que dizem por onde começar.

As ferramentas

As ferramentas do servidor são as chamadas do SandboxService, a metade da API que fica no painel, cada uma com o mesmo nome, os mesmos campos e as mesmas respostas da referência da API:

FerramentaO que faz
GetWorkspaceOs limites, tamanhos e preços do espaço de trabalho, os nomes dos segredos e as chaves SSH.
ListSandboxesOs sandboxes dele, os mais recentes primeiro, por estado, rótulo ou nome.
CreateSandboxUm sandbox a partir de um template, respondido assim que roda.
GetSandboxUm sandbox: o estado e o motivo, as configurações, como alcançá-lo, o uso.
UpdateSandboxO nome, o tamanho, o ciclo de vida, a saída, as portas públicas ou o ambiente.
PauseSandboxPausa o sandbox, com memória e processos guardados.
StopSandboxPara o sandbox, com o disco guardado.
ResumeSandboxInicia de novo um pausado ou parado.
ForkSandboxCopia o sandbox, memória e processos incluídos, para novos sandboxes.
DeleteSandboxExclui o sandbox, com memória e disco, para sempre.
ConnectSandboxO servidor do sandbox, um token para ele e o comando SSH.
CreateTemplateSalva o disco de um sandbox como template.
ListTemplatesOs nossos templates e os do espaço de trabalho.

Comandos e arquivos: no servidor do próprio sandbox

O que roda dentro de um sandbox, os comandos, os arquivos, o desktop, os links e os agentes de código, é respondido pelo servidor em que o sandbox roda, nunca pelo painel. Por isso o servidor MCP em mcp.pethost.dev/sandboxes não lista RunCommand: o agente chama ConnectSandbox, que responde com a url do servidor, um token só para aquele sandbox e o ssh_command, e então trabalha lá sozinho:

  • Com a CLI pethost, onde o agente tem um shell: pethost sandbox run <id> -- npm test, pethost sandbox cp ./app <id>:app, pethost sandbox shell <id>.
  • Com o curl, qualquer chamada do SandboxRuntimeService pelo nome, em Connect JSON com os nomes de campo que as ferramentas usam.
  • Sem shell, o agente passa a você o panel_url do sandbox, onde ficam o terminal e o desktop dele, depois que você entra.
curl -s "$URL/pethost.sandboxes.v1.SandboxRuntimeService/RunCommand" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"sandbox_id": "'"$ID"'", "command": "npm test"}'

O token é root naquele sandbox: as instruções do servidor e a skill dizem ao agente que o guarde em uma variável do shell e nunca o imprima na conversa.

Um token só para este servidor

O login dá ao agente um token de API do Pethost cujo público é este servidor: ele funciona em mcp.pethost.dev/sandboxes e na API de sandboxes, e é recusado no servidor MCP do App Platform, assim como o token do App Platform é recusado aqui. Ele só alcança os espaços de trabalho que você escolheu. As Configurações da sua conta o listam sob o nome do agente, com o que ele alcança, e o revogam.

Por que é um conector próprio

O App Platform e o Agent Sandboxes são dois produtos com ferramentas diferentes e um leitor diferente em mente: um agente que faz deploy dos seus apps, e um agente que precisa de computadores para rodar código. Cada um tem servidor, nome, ícone, ferramentas e tokens próprios, para que um agente configurado para um nunca leia, nem confunda, os do outro. Uma conta com os dois adiciona os dois: o do App Platform é https://mcp.pethost.dev/mcp.

Quando não funciona

  • A página de login não oferece nenhum espaço de trabalho: ela oferece só espaços de trabalho de sandboxes. Crie um no painel antes, escolhendo Agent Sandboxes.
  • O agente diz que não está logado, ou as chamadas dele respondem 401: o token foi revogado, ou o agente entrou no servidor do App Platform. Entre de novo pelo agente (/mcp no Claude Code).
  • Uma ferramenta responde WorkspaceChoice: o token alcança vários espaços de trabalho de sandboxes. Diga ao agente qual; ele envia o workspace em toda chamada.
  • O agente procura RunCommand: não é uma ferramenta deste servidor. Indique a ele ConnectSandbox e a CLI, ou instale o plugin, cuja skill diz isso.
  • RESOURCE_EXHAUSTED com LimitReached: as vCPUs do espaço de trabalho estão ocupadas pelos sandboxes rodando e pausados. Peça ao agente que exclua os que não precisa mais.

Perguntas

Qual é o endereço do servidor MCP?

https://mcp.pethost.dev/sandboxes, HTTP streamable, com login por OAuth no seu navegador.

Quais agentes funcionam com o Pethost Agent Sandboxes?

Qualquer agente que aceite um servidor MCP remoto: Claude Code, Codex, Cursor, Claude na web e no desktop, Hermes Agent e outros. O Claude Code e o Codex podem instalar o plugin, que adiciona uma skill.

O agente pode rodar comandos em um sandbox por MCP?

Pelo servidor do próprio sandbox: ConnectSandbox dá o endereço e um token, e o agente roda comandos com a CLI pethost ou o curl. O próprio servidor MCP cria, altera, pausa, faz fork e exclui sandboxes.

O agente recebe as minhas chaves de API?

Não. Ele recebe um token para os espaços de trabalho que você escolher. As chaves de modelos e serviços são segredos do espaço de trabalho, que nenhum sandbox e nenhuma resposta de ferramenta jamais guardam.

É o mesmo servidor do Pethost App Platform?

Não: o do App Platform é https://mcp.pethost.dev/mcp. Cada um tem as próprias ferramentas e os próprios tokens.

Experimente o Pethost Agent Sandboxes

Um teste grátis de 7 dias com US$ 1 de uso e 4 vCPUs; é preciso um cartão. Depois, um plano a partir de US$ 20 por mês, que inclui esse mesmo valor em uso.

Começar o teste grátis