quickstart

Up and running in five commands.

$ git clone https://github.com/nickvd7/vaultrun && cd vaultrun
$ cp .env.example .env        # set MASTER_API_KEY to something strong
$ make up                     # API + Postgres + Redis + dashboard
$ make bootstrap-key          # prints your first vr_... API key
$ curl http://localhost:8080/health
{"status":"ok"}
# dashboard → http://localhost:3000

Prerequisites: Docker, Docker Compose, Go 1.25+.

how it works

One API between your agent and the blast radius.

┌──────────────────────────────────────────────────────────────┐
│  Your AI agent  (Claude, GPT, custom, …)                     │
│                                                              │
│  result = client.run(session_id,                             │
│      command="python", args=["analyze.py"])                  │
└────────────────────────┬─────────────────────────────────────┘
                         │ API key
                         ▼
┌──────────────────────────────────────────────────────────────┐
│  VaultRun API  (your server, your infra)                     │
│                                                              │
│  • isolated Docker container per session                     │
│  • exec API only — no shell injection                        │
│  • path traversal prevention in workspace                    │
│  • HMAC-signed audit trail                                   │
│  • CPU / memory / timeout limits per session                 │
│  • network disabled by default                               │
└──────────────────────────────────────────────────────────────┘

what's in the box

Seven components, one repo.

mcp server

53 tools. Two transports. Any agent.

{
  "mcpServers": {
    "vaultrun": {
      "command": "/path/to/vaultrun-mcp",
      "env": {
        "VAULTRUN_BASE_URL": "http://localhost:8080",
        "VAULTRUN_API_KEY": "vr_your_key"
      }
    }
  }
}

$ MCP_TRANSPORT=http \
  MCP_AUTH_TOKEN=your-secret-token \
  VAULTRUN_BASE_URL=http://localhost:8080 \
  VAULTRUN_API_KEY=vr_your_key \
  ./vaultrun-mcp
# POST /mcp — JSON-RPC 2.0
# Authorization: Bearer your-secret-token

sdks

Five lines to a sandboxed run.

# pip install ./sdk/python
from sandbox_sdk import Client

client = Client("http://localhost:8080",
                api_key="vr_...")
s = client.create_session(
        image="python:3.12-slim")
client.upload_file(s.id, "script.py",
        open("script.py", "rb"))
r = client.run(s.id, command="python",
        args=["script.py"])
print(r.stdout)

import vaultrun "github.com/nickvd7/vaultrun/sdk/go"

client := vaultrun.New(
    "http://localhost:8080", "vr_...")
s, _ := client.CreateSession(ctx,
    vaultrun.CreateSessionOptions{
        Image: "python:3.12-slim"})
client.UploadFile(ctx, s.ID,
    "script.py", scriptContent)
run, _ := client.Run(ctx, s.ID,
    vaultrun.RunOptions{Command: "python",
        Args: []string{"script.py"}})
fmt.Println(*run.Stdout)

security model

Paranoid by default. On purpose.

• No shell execution — commands go through the Docker exec API
• Non-root containers, all capabilities dropped
• Network disabled by default; per-session iptables allowlist
• Path traversal prevention at the workspace layer
• API keys stored as SHA-256 hashes, never plaintext
• HMAC-signed audit trail for every action
• OIDC with PKCE + state validation; SAML XMLDSig verification
• Session cookies: HttpOnly, Secure, HS256-signed
• Rate limiting + security headers on the MCP HTTP transport
• AWS tools require explicit opt-in — no ambient IAM credentials

Full write-up: docs/security.md

open core

Apache 2.0 core. Fork it, ship it, embed it.

The core — API server, sandbox runtime, CLI, MCP server (53 tools), CI runner, dashboard, and both SDKs — is Apache 2.0: run it commercially, modify it, or vendor the Go SDK straight into your agent. Enterprise SSO (OIDC + SAML) ships separately under a commercial license — mail@030.dev. Issues and pull requests welcome.

contact

Questions, enterprise use, security reports?

Drop a message — it lands straight in our inbox. Prefer mail? mail@030.dev. Bugs and feature requests go to GitHub issues.

$ sendmail mail@030.dev
message queued — we'll get back to you soon. ✓