sandboxrun
README.md
# sandboxrun
sandboxrun gives an agent a safe place to run code it just wrote.
Hand it a snippet and it comes back with what the snippet printed,
the values it produced, and any error it hit — all executed inside a
short-lived E2B sandbox, never on your own machine. It runs from the
command line or as an MCP server for agents.
An E2B API key is required. Put it in the `E2B_API_KEY` environment
variable; the key is sent to the API as the `X-API-Key` header and
never appears in output. When the variable is missing, every run
fails with an error that names it.
## Install
```bash
npx @reneturcios/sandboxrun run "print(6 * 7)"
```
Or run the container image:
```bash
docker run -i -e E2B_API_KEY ghcr.io/cloudcorprecords/sandboxrun
```
The container defaults to the MCP server (see below). Pass CLI
arguments to use it as a CLI instead.
## CLI
```bash
export E2B_API_KEY="your E2B API key"
# Run a snippet inline
sandboxrun run "print('hello from the sandbox')"
# Run a file's contents
sandboxrun run --file analysis.py
# Machine-readable output
sandboxrun run "import math; print(math.pi)" --json
sandboxrun --version
```
Exit codes: `0` on success, `1` when a run fails (including a
missing `E2B_API_KEY`, an API error, or an error raised by the code
itself), `2` for usage errors.
## MCP server
One bin serves both faces. The `mcp` subcommand starts a stdio MCP
server:
```bash
npx -y @reneturcios/sandboxrun mcp
```
MCP client configuration:
```json
{
"mcpServers": {
"sandboxrun": {
"command": "npx",
"args": ["-y", "@reneturcios/sandboxrun", "mcp"],
"env": { "E2B_API_KEY": "your E2B API key" }
}
}
}
```
### Tools
| Tool | Input | What it returns |
| --- | --- | --- |
| `run_code` | `code` (string, required) | The execution as a text block: the sandbox id, printed output, structured results, log lines, and any error the code raised. Code uses Jupyter notebook syntax. |
The documented E2B MCP server exposes this single tool, and
sandboxrun exposes exactly that tool — nothing extra.
Under the hood each call creates a fresh sandbox from the
code-interpreter template (`POST https://api.e2b.app/sandboxes`) and
then executes the code in it. The upstream SDK talks to the
sandbox's Jupyter kernel over a websocket channel; this rebuild
shapes the execution as a REST request behind the same seam and
records that transport simplification in its build report.
## Development
```bash
npm install
npm run build # tsc -> dist/
npm test # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev # run the CLI from source via tsx
```
## License
MIT — see `LICENSE`.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessOutdated data