sandboxrun

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

npx @reneturcios/sandboxrun run "print(6 * 7)"

Or run the container image:

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

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:

npx -y @reneturcios/sandboxrun mcp

MCP client configuration:

{
  "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

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.