---
title: "Conecte um agente aos sandboxes por MCP | Pethost Agent Sandboxes"
description: "Dê sandboxes como ferramentas ao Claude Code, Codex, Cursor ou Claude: adicione o servidor MCP do Pethost Agent Sandboxes e escolha um espaço de trabalho."
---

[Docs do Agent Sandboxes](https://pethost.dev/pt/docs/sandboxes/) · Começar

# Conecte um agente aos sandboxes por MCP

Atualizado em 22 de novembro de 2026 · 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](https://pethost.dev/docs/sandboxes/api/):

| Ferramenta | O que faz |
| --- | --- |
| `GetWorkspace` | Os limites, tamanhos e preços do espaço de trabalho, os nomes dos segredos e as chaves SSH. |
| `ListSandboxes` | Os sandboxes dele, os mais recentes primeiro, por estado, rótulo ou nome. |
| `CreateSandbox` | Um sandbox a partir de um template, respondido assim que roda. |
| `GetSandbox` | Um sandbox: o estado e o motivo, as configurações, como alcançá-lo, o uso. |
| `UpdateSandbox` | O nome, o tamanho, o ciclo de vida, a saída, as portas públicas ou o ambiente. |
| `PauseSandbox` | Pausa o sandbox, com memória e processos guardados. |
| `StopSandbox` | Para o sandbox, com o disco guardado. |
| `ResumeSandbox` | Inicia de novo um pausado ou parado. |
| `ForkSandbox` | Copia o sandbox, memória e processos incluídos, para novos sandboxes. |
| `DeleteSandbox` | Exclui o sandbox, com memória e disco, para sempre. |
| `ConnectSandbox` | O servidor do sandbox, um token para ele e o comando SSH. |
| `CreateTemplate` | Salva o disco de um sandbox como template. |
| `ListTemplates` | Os 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.

[AnteriorInício rápido: o seu primeiro sandbox](https://pethost.dev/pt/docs/sandboxes/quickstart/) [PróximaCiclo de vida do sandbox: pausa automática, parada automática e ociosidade](https://pethost.dev/pt/docs/sandboxes/lifecycle/)

## 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](https://console.pethost.dev/)

Pethost · Stephan Gomer · NIP 1133096755

Pethost

- [Templates](https://pethost.dev/pt/templates/)
- [Sobre nós](https://pethost.dev/about/)
- [Docs](https://pethost.dev/docs/)
- [Blog](https://pethost.dev/pt/blog/)
- [API](https://pethost.dev/docs/api/)
- [CLI](https://pethost.dev/docs/cli/)
- [Plugin](https://github.com/pethost-dev/plugin)
- [Termos](https://pethost.dev/terms/)
- [Privacidade](https://pethost.dev/privacy/)
- [Reembolsos](https://pethost.dev/refunds/)
- [support@pethost.dev](mailto:support@pethost.dev)

Bancos de dados

- [Postgres](https://pethost.dev/pt/postgres/)
- [Valkey](https://pethost.dev/pt/valkey/)

Agent Sandboxes

- [Sandboxes](https://pethost.dev/pt/sandboxes/)
- [Preços](https://pethost.dev/pt/sandboxes/#pricing)
- [Docs](https://pethost.dev/pt/docs/sandboxes/)
- [API](https://pethost.dev/docs/sandboxes/api/)

Comparativos

- [Coolify vs Dokploy vs CapRover vs Dokku](https://pethost.dev/pt/blog/coolify-vs-dokploy-vs-caprover-vs-dokku/)
- [Coolify Cloud vs Dokploy Cloud](https://pethost.dev/pt/blog/coolify-cloud-vs-dokploy-cloud/)
- [Preços Railway vs Render vs Fly.io](https://pethost.dev/pt/blog/railway-vs-render-vs-fly-io-pricing/)
- [Hospedagem gerenciada de Docker Compose](https://pethost.dev/pt/blog/managed-docker-compose-hosting/)

Alternativas

- [Alternativas ao Railway](https://pethost.dev/pt/blog/railway-alternatives/)
- [Alternativas ao Heroku](https://pethost.dev/pt/blog/heroku-alternatives/)
- [Alternativas ao Dokploy](https://pethost.dev/pt/blog/dokploy-alternatives/)
- [Alternativas ao Coolify](https://pethost.dev/pt/blog/coolify-alternatives/)
- [Alternativas ao Render](https://pethost.dev/pt/blog/render-alternatives/)
- [Alternativas ao Sliplane](https://pethost.dev/pt/blog/sliplane-alternatives/)
