vaultrun

README

VaultRun

Self-hosted secure runtime for AI agents. — vaultrun.dev · llms.txt · PyPI

VaultRun lets AI agents safely execute code, query databases, call cloud APIs, and manage files inside isolated Docker sandboxes running on your own infrastructure. No external SaaS. No data leaving your network. Local-first: treat successful agent plans as workflow assets you own (missions, verify checkpoints, sandbox memory, swarm graph, cost-aware replay).

Latest v0.4.5: the audit log is hash-chained and verified as a whole (GET /api/v1/audit/integrity, banner in the dashboard), allowed_hosts needs network_enabled, a command line in command is rejected, the Python and Go SDKs take allowed_hosts and secrets, Costs lists named sessions and marks ended ones, deleting a session takes seconds. v0.4.4: costs are now recorded (CPU and memory allocation, billed every minute), a tampered audit entry is reported as invalid (sig_status), every 500 is logged, the API and CLIs report their version (/health, --version), revoked keys can be deleted, and the dashboard shows dates, key expiry and run commands consistently. v0.4.3: make up generates the audit signing key, make down keeps your sessions (make down-all removes them), the Costs page no longer crashes, quoted command arguments work, and the dashboard gains audit paging/export, sessions search and accessibility fixes. v0.4.1 added: Compose allowed_hosts, working dashboard, verifiable audit signatures, per-key secret allowlist. Since v0.4.0 the API is secure by default and needs VAULTRUN_INSECURE_DEV=true for local use (set in .env.example; make dev-env adds it). Upgrading: new migrations 021 and 022 run automatically and Compose gains a netpolicy service; see the changelog.

v0.3.2: The Docker Compose quickstart (make up → session → command) now works end to end on a clean Linux host and is covered by a CI workflow; the secrets broker works under Compose, and the API returns 400 for invalid limits and unknown images. It also includes a second, cross-feature security pass — twelve more defects found and fixed, including an agent-impersonation channel in multi-agent collaboration, a session-quota bypass via checkpoint forking, and MCP browser tools that had their own unhardened copy of the Python-injection bug v0.3.1 fixed elsewhere. Recommended for every v0.3.0/v0.3.1 deployment; the full analysis is in the security report.

v0.3.1: Security and correctness release for the six v0.3.0 features — eleven defects found and fixed, including Rego and iptables injection through LLM-generated policies, incomplete SSRF filtering, HMAC signatures that did not cover the data they protect, and two features that did not work at all.

v0.3.0: 6 killer features — Session Replay (time-travel debugging), Browser Automation (8 MCP tools), Cost Intelligence (real-time tracking), Natural Language Policies (LLM-powered), Session Templates (marketplace), Multi-Agent Collaboration (WebSocket + Redis). The MCP server speaks both stdio and HTTP (71 tools). Enterprise SSO (OIDC + SAML 2.0) available separately (mail@030.dev). See changelog.

┌──────────────────────────────────────────────────────────────┐
│  Your AI Agent  (Claude, GPT-4o, 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                               │
└──────────────────────────────────────────────────────────────┘

Quickstart

Prerequisites: Docker, Docker Compose, curl and jq (Go 1.25+ only if you build outside Docker)

git clone https://github.com/nickvd7/vaultrun
cd vaultrun
cp .env.example .env        # set MASTER_API_KEY, POSTGRES_PASSWORD and AUDIT_HMAC_KEY (openssl rand -hex 32)
make up                     # detects the Docker GID, then starts API + Postgres + Redis + dashboard
make bootstrap-key          # prints your first vr_... API key
curl http://localhost:8080/health

Open http://localhost:3000 for the dashboard.

What's included

Component	Description
API server (cmd/api)	Gin-based REST API — sessions, runs, files, audit
CLI (cmd/cli)	vaultrun command-line tool
MCP server (sdk/mcp)	71-tool MCP server (stdio + HTTP, +6 Flowd when enabled)
CI runner (cmd/ci-runner)	GitHub webhook → sandbox CI + Slack/Teams notify
Local gateway (cmd/local)	OpenAI-compat action plane for Ollama / LM Studio / vLLM → VaultRun tools (docs · recipes)
Dashboard (apps/frontend)	Next.js management UI
Go SDK (sdk/go)	Typed Go client
Python SDK (sdk/python)	Python client — pip install vaultrun-sdk

🚀 Killer Features (6/6 Complete)

VaultRun includes production-ready features that make it the AI agent platform:

✅ Session Replay & Time-Travel Debugging

Record every command execution with full state snapshots. Jump back to any moment, reproduce bugs exactly, test "what if" scenarios. HMAC-signed checkpoints prevent tampering. (docs)

✅ Browser Automation Layer

Headless Chromium with Playwright pre-installed. 8 MCP tools for web scraping, E2E testing, PDF generation. SSRF protection blocks private IPs + cloud metadata. (docs)

✅ Cost Intelligence Dashboard

Real-time cost tracking per session with HMAC-signed metrics. Budget alerts, idle detection, top spenders. Immutable cost records via DB trigger. (docs)

✅ Natural Language Policy Engine

Write "Allow github.com and pypi.org, max 2 CPU" → get OPA policies, iptables rules, Docker constraints. LLM-powered (OpenAI), 4 templates included, 20+ examples. (docs)

✅ Session Templates Marketplace

Pre-configured environments (Python Data Science, Node.js API, Web Scraping, Rust Dev). One-click session creation with resource limits, network policies, env vars. (docs)

✅ Multi-Agent Collaboration

Multiple agents in one session via WebSocket + Redis. Real-time presence, agent-to-agent messaging, file version tracking. Max 4 agents/session (configurable). (docs)

Progress: 100% (6/6 features shipped) — Security tested ✅ (report)

Architecture

vaultrun/
├── cmd/
│   ├── api/          Go API server (Gin)
│   ├── cli/          Go CLI (vaultrun)
│   └── ci-runner/    GitHub webhook CI runner
├── internal/
│   ├── auth/         API key hashing + validation
│   ├── audit/        HMAC-signed event logger
│   ├── docker/       Container + exec management
│   ├── workspace/    File vault, path traversal prevention
│   ├── runner/       Command execution orchestration
│   ├── db/           Postgres queries (sqlx)
│   ├── policy/       Pluggable policy hook (OPA-ready)
│   └── config/       Environment-based configuration
├── apps/
│   └── frontend/     Next.js dashboard (React + Tailwind)
├── sdk/
│   ├── go/           Go SDK
│   ├── python/       Python SDK
│   └── mcp/          MCP server (53 tools)
├── migrations/       SQL migrations (golang-migrate)
├── deployments/      Docker Compose + Dockerfiles
├── docs/             Architecture, security, API reference
└── examples/         Usage examples

MCP Server (71 tools)

The MCP server exposes every VaultRun capability as a Model Context Protocol tool, including browser automation, memory, verification, task control, and optional Flowd integration (+6 tools). Add it to Claude Desktop, Claude Code, or any MCP-compatible platform in seconds.

Stdio transport (Claude Desktop / Claude Code)

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

Build the binary: go build -o vaultrun-mcp ./sdk/mcp/

HTTP transport (OpenAI / OpenRouter / custom)

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

Tool categories

Category	Tools
Sandbox	create_session, list_sessions, get_session, delete_session, run_command, upload_file, read_file, list_files, delete_file, get_run, list_runs, get_session_stats, get_session_logs
Images	list_images, pull_image
Snapshots	create_snapshot, list_snapshots
Artifacts	create_artifact, list_artifacts, list_audit_logs
GitHub	run_github_repo, github_post_comment
Filesystem	fs_read_file, fs_write_file, fs_list_dir, fs_delete_file
S3	s3_list_buckets, s3_list_objects, s3_get_object, s3_put_object, s3_delete_object, s3_head_object
SSM	ssm_get_parameter, ssm_put_parameter, ssm_delete_parameter, ssm_list_parameters
Secrets Manager	sm_get_secret, sm_list_secrets
Lambda	lambda_list_functions, lambda_invoke
SQLite	sqlite_query, sqlite_execute, sqlite_schema
PostgreSQL	pg_query, pg_execute, pg_schema
MongoDB	mongo_find, mongo_insert_one, mongo_update, mongo_delete, mongo_aggregate, mongo_collections, mongo_generate_mongoose

Full documentation: sdk/mcp/README.md

GitHub CI Runner

Runs PR test suites inside VaultRun sandboxes triggered by GitHub webhooks.

GITHUB_TOKEN=ghp_...               \
GITHUB_WEBHOOK_SECRET=your-secret  \
VAULTRUN_BASE_URL=http://vaultrun  \
VAULTRUN_API_KEY=vr_...            \
SLACK_WEBHOOK_URL=https://...      \   # optional
TEAMS_WEBHOOK_URL=https://...      \   # optional
NOTIFY_ON_SUCCESS=false            \   # suppress green noise
CI_TEST_COMMANDS='[["make","test"]]' \ # default
./ci-runner

• Webhook endpoint: POST /webhook (HMAC-SHA256 validated)
• Health check: GET /healthz
• Results posted as a PR comment + commit status (vaultrun-ci)
• Slack Block Kit and Teams Adaptive Card 1.4 payloads

REST API Reference

All endpoints require X-API-Key or Authorization: Bearer <key>.

Sessions

POST   /api/v1/sessions          Create a new session
GET    /api/v1/sessions          List active sessions
GET    /api/v1/sessions/:id      Get session details
DELETE /api/v1/sessions/:id      Delete session + container + workspace

Create session body:

{
  "name": "my-session",
  "image": "python:3.12-slim",
  "network_enabled": false,
  "cpu_limit": 1.0,
  "memory_limit_mb": 512,
  "timeout_seconds": 300
}

Command Execution

POST /api/v1/sessions/:id/run     Execute a command
GET  /api/v1/sessions/:id/runs    List runs for a session
GET  /api/v1/runs/:id             Get run details

Execute command body:

{ "command": "python", "args": ["script.py"], "timeout_seconds": 30 }

Response:

{
  "id": "uuid",
  "status": "completed",
  "exit_code": 0,
  "stdout": "...",
  "stderr": "",
  "duration_ms": 412
}

File Vault

POST /api/v1/sessions/:id/files          Upload file (multipart)
GET  /api/v1/sessions/:id/files          List files
GET  /api/v1/sessions/:id/files/*path    Download file

Audit Logs

GET /api/v1/audit?session_id=...    List audit logs

Key Management

POST /api/v1/keys    Create API key (requires master key)
GET  /api/v1/keys    List API keys

Full OpenAPI spec: docs/openapi.yaml

CLI

export VAULTRUN_API_URL=http://localhost:8080
export VAULTRUN_API_KEY=vr_...

vaultrun session create --image python:3.12-slim --cpu 0.5 --mem 256
vaultrun session list
vaultrun file upload <session-id> ./script.py
vaultrun run <session-id> -- python script.py
vaultrun logs <run-id>
vaultrun session delete <id>

Python SDK

from vaultrun_sdk import Client

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

Install: pip install vaultrun-sdk

Go SDK

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

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

SSO / Authentication

VaultRun supports three authentication methods:

Method	How	Use case	Edition
API key	X-API-Key: vr_… header	Agents, SDKs, CI	Core (Apache 2.0)
OIDC	Browser redirect to IdP → session cookie	Dashboard users via Okta/Azure AD/Google	Enterprise
SAML 2.0	Browser redirect to IdP → session cookie	Enterprise IdPs (Okta, AD FS, OneLogin)	Enterprise

SSO logins auto-provision a VaultRun API key and issue a signed session cookie. OIDC and SAML do not grant master-key privileges.

SSO ships as VaultRun Enterprise in a separate repository and is compiled into the API server as an overlay (go build -tags enterprise). A core build refuses to start when OIDC_*/SAML_* env vars are set, so misconfigured deployments fail loudly.

How to get Enterprise

Pick a path on vaultrun.dev/#enterprise — every request is emailed to mail@030.dev:

1. Evaluate — free for development and testing; request evaluation access
2. License — production SSO; include org, IdP, instances/seats, and timeline
3. Talk to us — procurement, support, or custom terms

See docs/sso-setup.md for a step-by-step setup guide (IdP registration, certificates, testing, troubleshooting), or docs/configuration.md for the environment variable reference.

Security

See docs/security.md for the full security model.

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

Configuration

All configuration is via environment variables. See .env.example and docs/configuration.md.

API server (required):

Variable	Default	Description
PORT	8080	API server port
DATABASE_URL	—	Postgres DSN (required)
MASTER_API_KEY	—	Bootstrap key (use once, then disable)

SSO (optional):

Variable	Description
OIDC_ISSUER_URL	Enable OIDC — e.g. https://accounts.google.com
SAML_IDP_METADATA_URL	Enable SAML — URL of the IdP's metadata XML
SSO_SESSION_SECRET	Required when SSO is enabled — openssl rand -hex 32

Multi-region (optional):

Variable	Description
REGION	Region tag included in /health responses
DATABASE_READ_URL	Read-replica DSN for list/get queries

MCP server (MCP_TRANSPORT=http extras):

Variable	Default	Description
MCP_TRANSPORT	stdio	stdio or http
MCP_AUTH_TOKEN	—	Bearer token (required for HTTP)
MCP_PORT	:8090	Listen address for HTTP transport
MCP_SQLITE_PATH	—	Path to SQLite database file
MCP_PG_DSN	—	PostgreSQL connection string
MCP_MONGO_URI	—	MongoDB connection URI

Development

make test               # unit tests
make test-integration   # integration tests (requires running stack)
make fmt vet            # format + vet
make build              # build API + CLI binaries
make lint               # golangci-lint

# MCP server
go test ./sdk/mcp/...
go build -o vaultrun-mcp ./sdk/mcp/

# CI runner
go test ./cmd/ci-runner/...
go build -o ci-runner ./cmd/ci-runner/

Support & feedback

Topic	Channel
Bugs & feature requests (open core)	GitHub Issues
Security vulnerabilities	Private only — see SECURITY.md
Enterprise / SSO / licensing	vaultrun.dev/#contact → mail@030.dev

Please use the issue templates (version, component, repro steps). Do not put secrets in issues.

Changelog

See CHANGELOG.md for the version history.

License

VaultRun is open core:

• Everything in this repository is licensed under Apache 2.0 — see LICENSE.
• VaultRun Enterprise (SSO: OIDC + SAML 2.0) lives in a separate repository under the VaultRun Enterprise License.

Enterprise licensing & support: vaultrun.dev/#enterprise → emails mail@030.dev