request path

Agent asks. Sandbox runs. Audit sticks.

Illustrated walkthrough using the real API shapes — not a recorded customer run. Click a step, then verify the same trail on your own instance with the curl below.

$ curl -sS -H "Authorization: Bearer $VAULTRUN_API_KEY" \
  "http://localhost:8080/api/v1/audit?session_id=$SESSION_ID"
# → { "audit_logs": [ { "action": "command.finished", "sig": "…" }, … ] }

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

Nine components, one repo.

workflow as asset

Save the plan. Replay it. Own the trail.

Successful agent work should not evaporate into chat history. VaultRun treats reusable tool sequences as first-class missions on your infra — verified, remembered, and cost-aware when you replay.

mission → verify → memory → swarm → cost → yours

mcp server

53 tools. Two transports. Any agent.

Pick your transport, copy the snippet, paste into the agent. Same tools either way.

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

Same API surface — switch language without rewriting the mental model.

# pip install vaultrun-sdk
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)

flowd integration

Local workflows meet isolated execution.

Flowd observes local file workflows, detects patterns, and suggests automations you approve from the terminal. VaultRun runs agent code in Docker sandboxes with an audit trail. Together: observe → suggest → approve locally, then execute risky work in a container.

  flowd (local)                    VaultRun (sandbox)
  observe · detect · suggest    →    create_session · run_command · audit
  flowctl approve                     MCP flowd_* tools (opt-in)

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. Issues and pull requests welcome.

enterprise

SSO for teams that already have an IdP.

VaultRun Enterprise adds OIDC (Authorization Code + PKCE) and SAML 2.0 to the self-hosted API — Okta, Azure AD, Google Workspace, Keycloak, AD FS, OneLogin — with org-aware RBAC and signed dashboard sessions. Eval is free; production needs a license. Requests go through the contact form.

contact

Enterprise, sales, or a walkthrough?

Use the form below for SSO evaluation, licenses, and calls. Bugs & features → GitHub Issues (use the templates). Security → private only: SECURITY.md (not this form, unless intent = security report).

$ send — contact form
message queued — we'll get back to you soon. ✓