sandbox-as-a-service-mcp

# 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

```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/v1`. |

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).