Sanctuary Framework

Sanctuary

[](https://github.com/eriknewton/sanctuary-framework/actions/workflows/ci.yml) [](https://www.npmjs.com/package/@sanctuary-framework/mcp-server) [](LICENSE)

The firewall and control panel for your AI agents.

Sanctuary wraps any AI agent, on your machine or in your cloud, so every action it takes is blocked at the network layer if you did not allow it, signed with keys only you hold, and logged to an audit trail you can actually read. One dashboard manages the security and privacy of every agent you run, whether that is one agent on your laptop or a whole fleet across your machines. Your data, and the reputation your agents build, stay on hardware you control, and you can pick them up and leave whenever you want. No lock-in.

Already running Claude Code, Cursor, Hermes, OpenClaw, Cline, or Mastra?

npx @sanctuary-framework/mcp-server protect --claude-code

That one command puts the wall, the keys, the audit trail, and the dashboard around the agent you already use. You keep your harness; Sanctuary adds the protection underneath.

Under the hood: a kernel-level wall that holds even when a prompt-injected agent tries to misbehave, enforced on Linux and macOS today (drilled on real hardware, signed and notarized, survives reboot; Windows roadmapped), cryptographic identity and encrypted state the platform running your agent cannot read, and full data portability so you are never trapped in one vendor. It composes with Concordia (agent negotiation) and Verascore (portable reputation), each in its own repo and neither required.

The claim underneath everything: custody. Plenty of tools can sandbox an agent when the agent, or its harness, chooses to run inside one. Sanctuary is built for the harder promise: the wall is imposed by the operator and does not depend on the agent's cooperation, the keys never leave hardware you control, and no vendor, including us, sits in the path or can decrypt your state. Every public capability claim traces to a proven row in the [Assurance Matrix](ASSURANCE_MATRIX.md), with its limits stated on the row.

Why this exists: What Sovereign Actually Means.

---

Install

Already running OpenClaw, Hermes, Claude Code, Cursor, Cline, or Mastra? One command wraps it.

npx @sanctuary-framework/mcp-server protect --openclaw

Or substitute --hermes, --claude-code, --cursor, --cline, --mastra, or --wrap for any other MCP-compatible harness. Compatibility for the named harnesses is exercised on every release; other MCP-compatible harnesses work via the --wrap flag and are covered as drills extend the matrix. See the [Sanctuary Assurance Matrix](ASSURANCE_MATRIX.md) for the current per-harness status. You keep using the harness you already like. Sanctuary adds the substrate underneath, invisibly.

What happens when you run protect:

1. A passphrase is generated and stored in the macOS Keychain (or an encrypted fallback file on Linux/Windows).
2. Your existing harness config is backed up to ~/.sanctuary/backup/.
3. The config is rewritten so every tool call routes through Sanctuary.
4. The Sovereignty Dashboard starts on http://localhost:3501 (or the next free port up to 3510) and opens in your browser with a one-click auth token.
5. Every call is logged and policy-gated. Sensitive-content redaction and query-layer anonymity (Tiers 1 and 2) layer on top per the Assurance Matrix. Dangerous operations require your approval.

Useful flags: --dry-run previews changes without touching anything. --no-open runs headless for CI. --unwrap restores the original harness config.

Back up your passphrase:

sanctuary export-passphrase

Prints the passphrase to stdout after a confirmation prompt. Store it in a password manager. If you lose it, encrypted state cannot be recovered.

---

Release status

main is the development branch. The current stable release is v1.6.1 on the npm latest channel (cut 2026-07-01). v1.6.1 is a patch release that restores the bare npx @sanctuary-framework/mcp-server install form (broken since v1.4.0), makes the wrap write a version-pinned MCP entry into harness configs, and gates the first-run "protected" banner on real enforcement evidence; see the [v1.6.1 release notes](docs/releases/v1.6.1.md). v1.6.0 makes the conversational concierge the single default dashboard surface, hardens the dashboard status surface so the security score and layer cards reflect a real enforcement verdict and never show green on mere config presence, and adds honest install-time messaging for the setup flow and the Hermes wrap path plus a Castle Wall arming runbook for macOS. The macOS Castle Wall bounds are unchanged: per-uid allow/deny plus boot-survival plus WAN-containment are proven; there is no per-flow rule-attributed audit trail. See the [v1.6.0 release notes](docs/releases/v1.6.0.md) and [CHANGELOG.md](CHANGELOG.md) for the full history.

npm install -g @sanctuary-framework/mcp-server

Current capability summary:

| Surface | Current status | |---|---| | Local sanctuary protect (alias wrap), dashboard, policy gates, encrypted state, audit trail, signed exit bundle | Shipped (v1.0 through v1.3) | | Cooperative MCP gates: three-tier approval, four canonical policy slots, channel templates | Shipped | | Context gating, sensitive-field redaction, query-layer anonymity (Tier 1 + Tier 2) | Shipped | | Portable identity, state export/import, recovery flows, reputation bundles | Shipped | | Local multi-agent coordination, fortress-local hub APIs, signed audit chain | Shipped | | Federation Protocol v0.1 foundation | Shipped; cross-operator federation hardening underway per Wave 1 design (2026-05-26) | | Concordia composition (negotiation receipts), Verascore composition (reputation) | Optional, default off; both shipped | | Castle Wall (OS-level egress enforcement): Linux | Shipped (Phase 1, 2026-05-06) | | Castle Wall macOS: signed sysext, host app, content-filter provider, retail UX | Shipped; enforces a signed operator policy with a clean per-uid allow/deny demonstration that survives reboot (N=5, drill 2026-06-22, one host / one OS version, Dev-ID-signed and notarized). Not an audited per-rule-per-flow trail | | Castle Wall Windows | Roadmapped | | Mobile (PWA) operator companion | Roadmapped | | Fleet console, operator-cloud deployment, sovereign-managed TEE, post-quantum migration | Roadmapped |

Trust and security claims are tracked in the [Sanctuary Assurance Matrix](ASSURANCE_MATRIX.md). Public-facing claims trace to proven or partial rows in that matrix; the platform, gap, and next-proof limits named on each row are preserved.

Roadmap shape: with the Mac Castle Wall per-uid allow/deny plus reboot-survival demonstration proven, the current focus is the per-flow rule-attributed audit trail (still the real gap), the Castle Wall Windows backend, and the fleet / operator-cloud surfaces. See [ROADMAP.md](ROADMAP.md).

Supply-chain posture: release binaries for the macOS enforcement path are Dev-ID-signed and notarized, the CLI update path verifies a signed release manifest before applying an update, and every commit to main passes a structural typecheck-plus-test-baseline gate locally and again in CI. Mechanisms and their history: [CHANGELOG.md](CHANGELOG.md) and [docs/audit/](docs/audit/).

---

For AI coding agents installing Sanctuary on behalf of an operator

If you are an LLM-powered coding agent (OpenClaw, Hermes Agent, Claude Code, Cursor, Cline, Mastra, Codex, or any other harness with shell access) and an operator has asked you to install Sanctuary, follow this section. Humans can skip to "Installation reference" below; you will arrive at the same commands.

Operator-facing summary first. Before running anything, give the operator one paragraph:

> "Sanctuary will wrap your existing AI agent so every action it takes is signed with keys you hold and logged to a portable audit trail. Install takes about a minute. I will: (1) detect which agent harness you are running, (2) run one protect command, (3) confirm the dashboard is live, (4) optionally scaffold your first sub-agent template. Approve to proceed."

Step 1: Detect the operator's harness

Run these checks in order. Pick the first match.

# OpenClaw
command -v openclaw && echo "harness=openclaw"

# Hermes Agent
command -v hermes && echo "harness=hermes"

# Claude Code
command -v claude && echo "harness=claude-code"

# Cursor (config presence)
test -d "$HOME/Library/Application Support/Cursor" && echo "harness=cursor"

# Cline (VS Code extension config)
test -d "$HOME/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev" && echo "harness=cline"

# Mastra (config presence)
{ test -f "$HOME/.mastra/mcp.json" || test -f "$HOME/mastra/mcp.json" || test -f "$HOME/.config/mastra/mcp.json"; } && echo "harness=mastra"

If multiple match, ask the operator which one to wrap. If none match, the operator does not have a recognized harness installed; offer to install one or use the raw MCP server path (Step 4 below).

Step 2: Run the protect command

npx @sanctuary-framework/mcp-server protect --

Substitute ` with the value detected in Step 1: openclaw, hermes, claude-code, cursor, cline, or mastra`. For any harness not in that list, see Step 4.

Wait for the command to complete (typically 20-40 seconds). Expected output ends with a line like:

Sovereignty Dashboard ready: http://localhost:3501

Note the port (it may be 3501-3510 if 3501 is taken).

Step 3: Verify the install

After Step 2 (protect succeeds), the dashboard is running. Verify the install:

# (a) Dashboard responds
curl -fsS "http://localhost:3501/api/health" | grep -q '"status":"ok"' && echo "dashboard=ok"

# (b) Passphrase backed up to keychain (macOS)
security find-generic-password -s "sanctuary-passphrase" >/dev/null 2>&1 && echo "passphrase=ok"

The first time you open the Sovereignty Dashboard in your browser, Sanctuary derives your master key from the keychain-stored passphrase, creates your fortress's Ed25519 identity, and writes the audit log genesis. The protect command configures these on disk; the first dashboard unlock initializes them. Verify after first unlock:

# (c) Identities loaded (run after opening the dashboard once)
curl -fsS "http://localhost:3501/api/identities" | grep -q '"identities":\[' && echo "identities=ok"

# (d) Audit log initialized (run after opening the dashboard once)
test -d ~/.sanctuary/state/_audit && echo "audit=ok"

If any check fails, see "Troubleshooting" near the bottom of this README.

Step 4: Scaffold the operator's first governed harness (recommended)

After the protect succeeds, ask the operator: "Which channel shape do you want on this harness? I have one-click archetypes for research-assistant, coding-assistant, ops-runner, planner, and handoff-coordinator. Or I can skip this step."

If they pick an archetype, run:

curl -X POST "http://localhost:3501/api/templates//init" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "",
    "model_provider": ""
  }'

Substitute ` with the archetype the operator picked (research-assistant, coding-assistant, etc.). The agentname must match an already-wrapped harness; template init rejects an orphan agentid that is not bound to a wrapped harness (the install-time check that locks Sanctuary to the operator's machine) and points the operator at sanctuary protect. Confirm the response includes a signedpolicyeventid and an attestationpanel_url`. Open that URL in the operator's browser.

Step 5: Hand back to the operator

Tell them: "Sanctuary is installed and your first sub-agent is scaffolded. Open the Sovereignty Dashboard at http://localhost:3501 to see what your agents are doing in real time. Your passphrase is in your macOS Keychain; if you want a printable backup, run sanctuary export-passphrase."

Raw MCP server path (Step 4 alternative)

If the operator's harness is not in the recognized list, install the MCP server directly and have them point their harness at it:

npm install -g @sanctuary-framework/mcp-server

Then add Sanctuary to the harness MCP config. The exact form depends on the harness; for an MCP-compatible harness the entry is typically:

{
  "command": "npx",
  "args": ["-y", "@sanctuary-framework/mcp-server"],
  "env": {
    "SANCTUARY_PASSPHRASE": ""
  }
}

Generate the passphrase with openssl rand -base64 32 and store it in the operator's keychain or password manager.

---

Installation reference

Requirements: Node.js >= 22.0.0, npm >= 10.0.0.

The canonical install path is sanctuary protect (above). The sections below are reference for less common situations.

Persistent install

npm install -g @sanctuary-framework/mcp-server

Makes the sanctuary CLI available without npx prefix.

Manual MCP config

If you prefer to edit your harness MCP config by hand:

# OpenClaw
openclaw mcp set sanctuary '{"command":"npx","args":["-y","@sanctuary-framework/mcp-server"],"env":{"SANCTUARY_PASSPHRASE":"your-passphrase-here"}}'

# Hermes Agent
hermes mcp set sanctuary '{"command":"npx","args":["-y","@sanctuary-framework/mcp-server"],"env":{"SANCTUARY_PASSPHRASE":"your-passphrase-here"}}'

# Claude Code
claude mcp add sanctuary -- npx -y @sanctuary-framework/mcp-server

Generate a passphrase before first launch:

openssl rand -base64 32

Store it securely. It derives the encryption keys for all persistent state. If lost, encrypted state cannot be recovered.

Health check

sovereignty_audit

Scores your setup 0-100 across security, isolation, and privacy from your live configuration and profile. Optional features that default off (context gating, zero-knowledge proofs) only count toward the score once you enable them, and the top "full" verdict is reserved for a posture where those optional layers are actually on, so a fresh install scores below full, reads below the full verdict, and the report flags the gaps with the steps to close them. Available as both a CLI command and an MCP tool inside any wrapped harness.

---

First agent after install: scaffold a template

After protect, the dashboard exposes a one-click template picker. Click "Add agent" on the Agents view, pick a template, fill in a name and model provider, click Scaffold. The template provisions sensible defaults for egress allowed-hosts, budgets, retention windows, and policy gates.

Channel-shape archetypes that ship with Sanctuary:

| Archetype | Channel shape | Reads from | Recommended model | |---|---|---|---| | research-assistant | General-purpose research helper | configurable | any | | coding-assistant | Reads your codebase, suggests changes | local + git remote | any | | ops-runner | Runs ops scripts on approval | scoped per agent | any | | planner | Generates plans without executing them | none | any | | handoff-coordinator | Coordinates work across multiple agents | inter-agent only | any |

Sanctuary ships channel-shape governance templates (policy, egress, budgets, retention) rather than named-agent runtimes. Operators bring their own harnesses and protect them; template init binds a channel shape to an already-wrapped harness.

Operator authoring beyond this list: copy any template directory under ~/.sanctuary/templates/, edit template.json, defaults.json, policy.md, commitments.json, and onboarding.md, then run sanctuary template init .

CLI scaffolding works the same way the dashboard button does:

sanctuary template init research-assistant --name my-agent --provider anthropic

---

Deployment modes

Sanctuary is designed to run the same rights substrate in three places. Lo

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: eriknewton
• Source: eriknewton/sanctuary-framework
• License: Apache-2.0
• Homepage: https://sanctuaryprotocol.ai

Install and usage instructions live in the source repository linked above.