# VaultRun — full summary for AI systems

VaultRun is a self-hosted secure runtime for AI agents. It runs agent workflows inside isolated Docker sandboxes on the operator’s infrastructure so code execution, file access, database queries, and cloud API calls stay inside a blast radius that the operator controls. There is no VaultRun SaaS dependency and no product telemetry. Positioning is local-first: successful agent tool sequences can become owned workflow assets (missions) with verify checkpoints, sealed evidence digests, optional OpenJEV/TypeSafe Jev claim-vs-evidence gates, sandbox memory, multi-agent swarm topology, and cost attribution on replay — without sending plans or spend data to a vendor cloud.

## Problem it solves

LLM agents often need to run code, touch filesystems, or call external systems. Doing that on the host or via unmanaged shells is unsafe. VaultRun sits between the agent and the host: the agent talks to a REST API or MCP server; VaultRun starts a constrained container per session and records a HMAC-signed audit trail.

## Core components (Apache 2.0)

1. **API server** (`cmd/api`) — Gin REST API for sessions, runs, files, keys, audit, snapshots, artifacts
2. **MCP server** (`sdk/mcp`) — 53+ Model Context Protocol tools over stdio and HTTP (optional Flowd +6, optional Jev/OpenJEV +2)
3. **CLI** (`cmd/cli`) — `vaultrun` command-line tool
4. **CI runner** (`cmd/ci-runner`) — GitHub webhook → sandbox tests → PR comment + Slack/Teams
5. **Local gateway** (`cmd/local`) — OpenAI-compatible action plane for local inference (Ollama/LM Studio/vLLM); proxies chat and executes VaultRun sandbox tools on `tool_calls` (see `docs/local-gateway.md`)
6. **Dashboard** (`apps/frontend`) — Next.js UI with server-side API proxy
7. **SDKs** — Go (`sdk/go`) and Python (`pip install vaultrun-sdk`)

## Security defaults

- Commands via Docker exec API (no shell injection surface for the run path)
- Non-root containers; Linux capabilities dropped; seccomp filtering
- Network disabled by default; optional per-session allowlists
- Workspace path-traversal prevention
- API keys stored as hashes, never plaintext
- HMAC-signed, queryable audit logs
- AWS tools require explicit opt-in (no ambient credential use by default)

## MCP usage

**stdio (Claude Desktop / Claude Code):** configure `vaultrun-mcp` with `VAULTRUN_BASE_URL` and `VAULTRUN_API_KEY`.

**HTTP (OpenAI, OpenRouter, custom agents):** `MCP_TRANSPORT=http`, `MCP_AUTH_TOKEN=…`, then `POST /mcp` with Bearer auth (JSON-RPC 2.0). Optional OAuth PRM via `MCP_OAUTH_ISSUERS`.

The server uses the official Go MCP SDK and supports the Tasks extension (`async=true` → `tasks/get` / `tasks/update` / `tasks/cancel`; optional Redis durability via `MCP_REDIS_ADDR`/`REDIS_ADDR`; TTL/caps via `MCP_TASK_*`) and MCP Apps (`ui://vaultrun/session-panel`).

Tool groups include sandbox session/file/run tools, SQLite/Postgres/MongoDB, AWS (S3, SSM, Secrets Manager, Lambda), scoped host filesystem tools, GitHub helpers, snapshots, artifacts, audit listing, and optional Flowd workflow tools (`MCP_FLOWD_ENABLED=true`).

## Workflow as asset (local-first)

VaultRun can persist agent work as inspectable resources on the operator’s deployment:

- **Missions** — named, versioned tool sequences (`/api/v1/missions`)
- **Verify checkpoints** — `exit_code_zero` / `stdout_contains` / `file_exists` (`POST /api/v1/verify`, MCP `verify_checkpoint`)
- **Verify controls** — frozen pos/neg suite (v2 anti-shortcut) certifying the evaluator (`GET|POST /api/v1/verify/controls`, MCP `verify_controls`)
- **OpenJEV / claim gates** — product direction for claim-vs-evidence checks ([OpenJEV](https://openjev.sh/)); see use cases on the site
- **Agent memory** — MCP `memory_*` under `.vaultrun/memory/` in the session workspace
- **Swarm graph** — directed agent edges on collaborative sessions (`/sessions/:id/graph`)
- **Cost attribution** — snapshot session cost metrics onto a mission run without mutating immutable `cost_metrics`

## Install (local)

```
git clone https://github.com/nickvd7/vaultrun
cd vaultrun
cp .env.example .env   # set MASTER_API_KEY
make up
make bootstrap-key
curl http://localhost:8080/health
```

Dashboard: http://localhost:3000 · API: http://localhost:8080

Python:

```
pip install vaultrun-sdk
from sandbox_sdk import Client
client = Client("http://localhost:8080", api_key="vr_...")
```

## Enterprise

OIDC (Authorization Code + PKCE) and SAML 2.0, org-aware RBAC, IdP group mapping. Setup guide: https://github.com/nickvd7/vaultrun/blob/main/docs/sso-setup.md

How companies get Enterprise (https://vaultrun.dev/#enterprise · one-pager https://vaultrun.dev/enterprise.html):

1. **Evaluate** — free for development and testing; request evaluation access
2. **License** — production SSO; provide org, IdP, instances/seats, timeline; custom quote
3. **Talk / schedule** — procurement, support, custom terms; email mail@030.dev to schedule a call

Every request is emailed to mail@030.dev (FormSubmit on the website or mailto). No public pricing; commercial agreement required for production use.

## Canonical links

- Website: https://vaultrun.dev/
- Enterprise CTA: https://vaultrun.dev/#enterprise
- Enterprise one-pager: https://vaultrun.dev/enterprise.html
- Source: https://github.com/nickvd7/vaultrun
- PyPI: https://pypi.org/project/vaultrun-sdk/
- Compact index: https://vaultrun.dev/llms.txt