# sandbox-as-a-service-mcp

An [MCP](https://modelcontextprotocol.io) server that gives an agent a real Linux virtual machine it
can break.

Eleven tools: create a sandbox, run shell commands in it, write and read files, list what a run
produced, expose a port on a public preview URL, extend the lifetime, destroy it, and check what it
all cost.

Each sandbox is a dedicated VM with its own kernel — not a container sharing a host with other
people's code. It is never reused between accounts and is destroyed when it expires, whether or not
anything remembered to ask.

## Use it

Maintained by the operator of [Sandbox as a Service](https://sandbox-as-a-service.com).

### Hosted MCP (no local package)

For a client that supports Streamable HTTP, connect to:

```text
https://sandbox-as-a-service.com/v1/mcp
```

Send your own API key on each request as `Authorization: Bearer <your-api-key>`
or `x-api-key: <your-api-key>`. Get it at
[Dashboard → API keys](https://sandbox-as-a-service.com/dashboard/keys).
Never put an API key in the URL or share one through a registry.

The hosted server exposes **12 tools**: the eleven account/execution tools below
plus `get_service_info`. Anonymous `initialize`, `tools/list`, and
`get_service_info` work for free hosted discovery; account and execution calls
still require your key. The local stdio server (including the current downloadable
`mcp.tgz` v1.1.0) exposes the eleven account/execution tools. Use the hosted endpoint
for keyless service information. A GET-only check is not a connection test: this
endpoint uses MCP POST requests and SSE responses.

On [Smithery](https://smithery.ai/servers/florian-standhartinger/sandbox-as-a-service),
set `apiKey` to your own raw key; it maps to the `x-api-key` header.
[Connection documentation](https://sandbox-as-a-service.com/docs/mcp).

### Local stdio (current hosted package)

```bash
AAS_API_KEY=aas_sk_... npx -y https://sandbox-as-a-service.com/mcp.tgz
```

Get a key at [sandbox-as-a-service.com](https://sandbox-as-a-service.com) — new accounts start with
free credit and no card.

### Claude Desktop / Claude Code

```json
{
  "mcpServers": {
    "sandbox": {
      "command": "npx",
      "args": ["-y", "https://sandbox-as-a-service.com/mcp.tgz"],
      "env": { "AAS_API_KEY": "aas_sk_..." }
    }
  }
}
```

## The tools

| Tool | What it does |
|---|---|
| `create_sandbox` | Creates a VM and returns its id once it is ready. |
| `run_command` | Runs a shell command as an unprivileged user. Returns stdout, stderr, exit code. |
| `write_file` | Writes a file. Content travels out of band, so quotes and binary survive. |
| `read_file` | Reads a file back — how an agent gets at what its code produced. |
| `list_files` | Lists a directory tree, so an agent can find what a run produced. |
| `expose_port` | Gives a server inside the sandbox a public https URL to share. |
| `get_sandbox` | Status, size and expiry. |
| `list_sandboxes` | Everything on the account, newest first — useful for finding strays. |
| `extend_sandbox` | Pushes the expiry out when a job outgrows its timeout. |
| `destroy_sandbox` | Destroys it and stops billing. |
| `get_usage` | Remaining credit and recent usage. |

## Notes for agents

- Code runs as an unprivileged user. There is no `sudo`, so `apt-get` will not work; use
  `pip install --user --break-system-packages` or `npm install`, both of which do.
- `run_command` waits for the command to finish. Start a server with `&` or it will hold the call
  open until the timeout.
- A sandbox is destroyed when its timeout expires whether or not `destroy_sandbox` is called, so a
  forgotten sandbox costs minutes, not money forever. Calling it anyway returns the minutes you were
  not going to use.

## Environment

| Variable | |
|---|---|
| `AAS_API_KEY` | Required. Your API key. |
| `AAS_BASE_URL` | Optional. Defaults to `https://sandbox-as-a-service.com`. Use the origin only, without `/v1`; the client adds that API prefix. |

MIT licensed. The service it talks to is at
[sandbox-as-a-service.com](https://sandbox-as-a-service.com);
[docs](https://sandbox-as-a-service.com/docs/mcp).