---
title: "Connect an agent to sandboxes over MCP | Pethost Agent Sandboxes"
description: "Give Claude Code, Codex, Cursor or Claude sandboxes as tools: add the Pethost Agent Sandboxes MCP server and sign in to a workspace of sandboxes."
---

[Agent Sandboxes docs](https://pethost.dev/docs/sandboxes/) · Start

# Connect an agent to sandboxes over MCP

Updated 22 November 2026 · 6 min read

Sandboxes as tools of your agent: add the Pethost Agent Sandboxes MCP server, `https://mcp.pethost.dev/sandboxes`, to Claude Code, Codex, Cursor or Claude, sign in in your browser, and the agent makes, forks, pauses and deletes sandboxes itself.

**In short**

- **One address:** `https://mcp.pethost.dev/sandboxes`, streamable HTTP, sign-in by OAuth. No key to paste.
- **You choose the workspace:** the sign-in page offers your workspaces of sandboxes, and the agent's token reaches only those you pick.
- **13 tools** for the workspace and each sandbox's record. Commands and files go to the sandbox's own server, which the agent reaches with `ConnectSandbox` and the `pethost` CLI or `curl`.
- **Apart from App Platform:** a connector of its own, so an agent set up for one never sees the other's tools.

### Step 1: Add the server to Claude Code

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

Or install the plugin, which brings the server and a skill that tells Claude when and how to use sandboxes: `claude plugin marketplace add pethost-dev/plugin`, then `claude plugin install pethost-sandboxes@pethost`.

### Step 2: Sign in

In Claude Code, run `/mcp`, pick `pethost-sandboxes` and authenticate. Your browser opens Pethost's approval page: sign in, choose the workspace of sandboxes the agent may use, and press Connect.

### Step 3: Ask for something that needs a computer

“Make a sandbox, clone this repository and run its tests.” The agent reads the workspace, makes a sandbox from `base` and works in it.

Claude Code

**You say:** Make a sandbox, clone https://github.com/pallets/click and run its 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

**The agent answers:** All of click's tests passed in a new sandbox: 2628 passed, 24 skipped, 1 xfailed, 0 failed (pytest exit code 0). … The sandbox will pause after 5 idle minutes and stop after 30, but it isn't deleted automatically. Should I delete it, or keep it for more work?

## Codex

The plugin, for the CLI and the desktop app, brings the server and the skill: `codex plugin marketplace add pethost-dev/plugin`, then `codex plugin add pethost-sandboxes@pethost`. You sign in in your browser, as with Claude Code, and choose the workspace there.

## Cursor

Add the server to `~/.cursor/mcp.json`, or to `.cursor/mcp.json` in a project, then turn it on in Cursor's MCP settings, which start the sign-in:

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

## Claude on the web and on the desktop

In Claude's settings, open Connectors, add a custom connector, and give it the address `https://mcp.pethost.dev/sandboxes`. Claude opens the sign-in page; then turn the connector on in a conversation.

## Any other agent

Any MCP client that speaks streamable HTTP and signs in by OAuth takes the address `https://mcp.pethost.dev/sandboxes`. Hermes Agent: `hermes mcp add pethost-sandboxes --url https://mcp.pethost.dev/sandboxes --auth oauth`. The skill, for an agent that reads skills: `npx skills add pethost-dev/plugin --skill pethost-sandboxes`. An agent given the server alone reads its instructions instead, which say where to start.

## The tools

The server's tools are the calls of `SandboxService`, the panel's half of the API, each with the same name, fields and answers as in the [API reference](https://pethost.dev/docs/sandboxes/api/):

| Tool | What it does |
| --- | --- |
| `GetWorkspace` | The workspace's limits, sizes and prices, its secrets' names and SSH keys. |
| `ListSandboxes` | Its sandboxes, newest first, by state, label or name. |
| `CreateSandbox` | A sandbox from a template, answered once it runs. |
| `GetSandbox` | One sandbox: its state and why, its settings, how to reach it, its usage. |
| `UpdateSandbox` | Its name, size, lifecycle, egress, public ports or environment. |
| `PauseSandbox` | Pause it, memory and processes kept. |
| `StopSandbox` | Stop it, its disk kept. |
| `ResumeSandbox` | Start a paused or stopped one again. |
| `ForkSandbox` | Copy it, memory and processes included, into new sandboxes. |
| `DeleteSandbox` | Delete it, its memory and disk for good. |
| `ConnectSandbox` | The sandbox's server, a token for it and its SSH command. |
| `CreateTemplate` | Save a sandbox's disk as a template. |
| `ListTemplates` | Our templates and the workspace's. |

## Commands and files: at the sandbox's own server

What runs inside a sandbox, its commands, files, desktop, links and coding agents, is answered by the server the sandbox runs on, never by the panel. So the MCP server at `mcp.pethost.dev/sandboxes` lists no `RunCommand`: the agent calls `ConnectSandbox`, which answers the server's `url`, a `token` for that one sandbox and its `ssh_command`, and then works there itself:

- **With the `pethost` CLI,** where the agent has a shell: `pethost sandbox run <id> -- npm test`, `pethost sandbox cp ./app <id>:app`, `pethost sandbox shell <id>`.
- **With `curl`,** any call of `SandboxRuntimeService` by its name, in Connect JSON with the field names the tools use.
- **Without a shell,** the agent gives you the sandbox's `panel_url`, where its terminal and desktop are, once you sign in.

```
curl -s "$URL/pethost.sandboxes.v1.SandboxRuntimeService/RunCommand" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"sandbox_id": "'"$ID"'", "command": "npm test"}'
```

The token is root in that sandbox: the server's instructions and the skill tell the agent to keep it in a shell variable and never to print it in the conversation.

## A token for this server alone

The sign-in gives the agent a Pethost API token whose audience is this server: it works at `mcp.pethost.dev/sandboxes` and at the sandboxes' API, and is refused at App Platform's MCP server, as App Platform's token is refused here. It reaches only the workspaces you picked. Your account's Settings lists it under the agent's name, with what it reaches, and revokes it.

## Why it is a connector of its own

App Platform and Agent Sandboxes are two products with different tools and a different reader in mind: an agent that deploys your apps, and an agent that needs computers to run code on. Each has its own server, name, icon, tools and tokens, so an agent set up for one never reads, or confuses, the other's. An account with both adds both: App Platform's is `https://mcp.pethost.dev/mcp`.

## When it does not work

- **The sign-in page offers no workspace:** it offers workspaces of sandboxes alone. Make one in the console first, choosing Agent Sandboxes.
- **The agent says it is not signed in, or its calls answer 401:** the token was revoked, or the agent signed in to App Platform's server. Sign in again from the agent (`/mcp` in Claude Code).
- **A tool answers `WorkspaceChoice`:** the token reaches several workspaces of sandboxes. Tell the agent which one; it sends its `workspace` in every call.
- **The agent looks for `RunCommand`:** it is not a tool of this server. Point it at `ConnectSandbox` and the CLI, or install the plugin, whose skill says so.
- **`RESOURCE_EXHAUSTED` with `LimitReached`:** the workspace's vCPUs are held by its running and paused sandboxes. Ask the agent to delete the ones it no longer needs.

## Questions

### What is the MCP server's address?

`https://mcp.pethost.dev/sandboxes`, streamable HTTP, signed in by OAuth in your browser.

### Which agents work with Pethost Agent Sandboxes?

Any agent that takes a remote MCP server: Claude Code, Codex, Cursor, Claude on the web and desktop, Hermes Agent and others. Claude Code and Codex can install the plugin, which adds a skill.

### Can the agent run commands in a sandbox over MCP?

Through the sandbox's own server: `ConnectSandbox` gives its address and a token, and the agent runs commands with the `pethost` CLI or `curl`. The MCP server itself makes, changes, pauses, forks and deletes sandboxes.

### Does the agent get my API keys?

No. It gets a token for the workspaces you pick. Keys for models and services are workspace secrets, which no sandbox and no tool answer ever holds.

### Is it the same server as Pethost App Platform's?

No: App Platform's is `https://mcp.pethost.dev/mcp`. Each has its own tools and tokens.

[PreviousQuickstart: your first sandbox](https://pethost.dev/docs/sandboxes/quickstart/) [NextSandbox lifecycle: auto-pause, auto-stop and idle](https://pethost.dev/docs/sandboxes/lifecycle/)

## Try Pethost Agent Sandboxes

A 7-day trial with $1 of usage and 4 vCPUs, with a card. Then a plan from $20 a month, which includes as much usage.

[Start the trial](https://console.pethost.dev/)

Pethost · Stephan Gomer · NIP 1133096755

Pethost

- [Templates](https://pethost.dev/templates/)
- [About](https://pethost.dev/about/)
- [Docs](https://pethost.dev/docs/)
- [Blog](https://pethost.dev/blog/)
- [API](https://pethost.dev/docs/api/)
- [CLI](https://pethost.dev/docs/cli/)
- [Plugin](https://github.com/pethost-dev/plugin)
- [Terms](https://pethost.dev/terms/)
- [Privacy](https://pethost.dev/privacy/)
- [Refunds](https://pethost.dev/refunds/)
- [support@pethost.dev](mailto:support@pethost.dev)

Databases

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

Agent Sandboxes

- [Sandboxes](https://pethost.dev/sandboxes/)
- [Pricing](https://pethost.dev/sandboxes/#pricing)
- [Docs](https://pethost.dev/docs/sandboxes/)
- [API](https://pethost.dev/docs/sandboxes/api/)

Comparisons

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

Alternatives

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