Sanctuary

Your Agent. Your Machine. Your Keys.

Sanctuary wraps any AI agent harness in a substrate that protects you at the kernel, signs every action with keys you hold, and keeps the data and reputation your agents accumulate on your hardware. Whether you run one agent or a fleet, the substrate stays yours.

Sovereignty used to be embodied. In the physical world, your body provided the perimeter, the custody, the memory, and the audit trail by default. When you act through an AI agent, the substrate around the agent has to do that job, and almost always doesn't. Sanctuary is what does. The same architecture serves any sovereign acting through agents: a person, a company, eventually an agent itself.

Today: cryptographic identity you hold, kernel-level enforcement that holds even when the agent doesn't cooperate (Linux proven; macOS in flight), and a portable audit trail that travels across machines and vendors. In scope: the Sovereign Data Warehouse (your working data, query history, and document corpus on your substrate, not a vendor's silo) and federation across your own machines.

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

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

Install

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

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

Or substitute --hermes, --claude-code, --cursor, --cline, or --wrap <path-to-config> 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 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.

Related MCP server: kevros-mcp

Release status

main is the development branch. The current stable release is v1.3.3 on the npm latest channel (shipped 2026-05-26). v1.3.3 lands Castle Wall macOS Phase 2.5 retail UX, the Track 4A server-to-sysext IPC integration, and the Track 4A.2 sysext socket-path discovery file. See the v1.3.3 release notes and CHANGELOG.md for the full history.

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

Current capability summary:

Trust and security claims are tracked in the Sanctuary Assurance Matrix. 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: the current focus is closing the Mac Castle Wall thesis-gate (sysext rebuild + Track 4A drill PASS on Mini1) so the structural-enforcement claim is honest on both Linux and macOS. After that, Wave 1 (API parity + CLI MVP + federation-ready API) and the Castle Wall Windows backend. See ROADMAP.md.

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, 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"

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 --<harness>

Substitute <harness> with the value detected in Step 1: openclaw, hermes, claude-code, cursor, or cline. 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/<template-name>/init" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "<already-wrapped-agent-id>",
    "model_provider": "<xai|anthropic|openai|mistral>"
  }'

Substitute <template-name> with the archetype the operator picked (research-assistant, coding-assistant, etc.). The agent_name must match an already-wrapped harness; template init rejects an orphan agent_id 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 signed_policy_event_id and an attestation_panel_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": ["@sanctuary-framework/mcp-server"],
  "env": {
    "SANCTUARY_PASSPHRASE": "<generated-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":["@sanctuary-framework/mcp-server"],"env":{"SANCTUARY_PASSPHRASE":"your-passphrase-here"}}'

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

# Claude Code
claude mcp add sanctuary -- npx @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. Detects problems and tells you exactly what to fix. 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:

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 <your-template>.

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. Local mode is shipping today; operator-cloud and sovereign-managed TEE modes are roadmap surfaces that build on the same federation and policy foundations.

The operator holds the keys in every mode. The sovereign-managed mode will require hardware attestation before it is treated as shipped.

The Castle Architecture

Sanctuary installs the substrate sovereignty used to come with. Architecturally it ships as five named mechanisms.

Castle Wall: the perimeter. What the world cannot cross without your consent. OS-level egress enforcement at the operator-external boundary. The kernel itself blocks unauthorized cross-boundary calls. Even prompt-injected agents cannot bypass. Linux backend shipped (Phase 1, 2026-05-06). macOS backend (signed system extension + content-filter provider) shipped in v1.3.3; active enforcement code on main awaiting end-to-end Mini1 drill PASS. Windows on the roadmap.

Sentinels: the nerves. What surfaces what's happening to your awareness. Internal observation via process introspection and behavioral baselining. Anomalies surface through the menubar or notifications. Observation, not enforcement.

Charter: the will. What you train your agent to choose voluntarily. The additive cooperative MCP surface for compliant agents. Operator-rooted cryptographic identity (Ed25519 signing, Argon2id passphrase unlock, per-purpose HKDF subkeys). Per-agent encrypted state at rest (AES-256-GCM). Three-tier Principal Policy gates with channel-template binding. Signed audit chain with rollback detection.

Heralds: the voice. How you speak to and are recognized by other sovereigns. Optional composition surface (Concordia for structured negotiation, Verascore for portable reputation). Receipts and reputation attestations assemble into a single audit trail that travels with the agent across machines. Default off; both compositions are optional.

Mantle: the unique-substrate-binding. What makes this install yours, not someone else's. Install-time check that locks Sanctuary to the operator's machine at install time and rejects orphan agent identifiers that are not bound to a wrapped harness.

Today: Ed25519 signing, Argon2id passphrase unlock, and per-purpose HKDF subkeys. Crypto-agility: every audit entry embeds a scheme identifier so hybrid post-quantum signing (Ed25519 + ML-DSA / FIPS 204) can land without breaking historical receipts. Hardware-backed secure elements are on the roadmap.

The rights you hold by default

The substrate enforces rights that normally only ship to enterprises with dedicated identity and security teams. What they mean for you:

• Identity. Your agent has a key you own. No provider can impersonate you or revoke your agent. You can prove the agent is yours without asking anyone's permission.

• Data. Your agent's state is encrypted against the provider running it. The platform sees the calls going out; it does not see your life going in. Your conversations, your memory, and your plans stay yours.

• Portability. Your agent's memory, reputation, and commitments travel with you. If a provider goes bad, raises prices, or shuts down, you leave without losing what you built.

• Attestation. What your agent did is provable. To you, to a third party, to a court if it comes to that. The audit log is signed, append-only, and portable.

• Exit. Nothing you build up is locked to a platform that can revoke it. Keys, state, reputation, and commitments are yours to move, copy, or keep offline.

Sanctuary ships the rights substrate. Access (compute, devices, bandwidth, literacy) belongs to civic-infrastructure partners (public libraries, legal-aid organizations, labor unions, public-interest tech groups, community colleges) who host agentic AI on behalf of users who do not self-host. The partner provides access; Sanctuary provides rights. The two compose; they do not substitute.

Works with

Sanctuary wraps MCP-compatible harnesses. The named harnesses below are exercised on every release; other MCP-compatible harnesses work via the --wrap flag or direct MCP config and gain release-tested coverage as drills extend the Assurance Matrix.

• OpenClaw (sanctuary protect --openclaw)

• Hermes Agent (sanctuary protect --hermes)

• Claude Code (sanctuary protect --claude-code)

• Cursor (sanctuary protect --cursor)

• Cline (sanctuary protect --cline)

• Mastra, LangGraph, and custom harnesses (sanctuary protect --wrap <path>)

• Any other MCP-compatible harness via direct MCP config

Composes with Concordia Protocol

When your agent needs to negotiate or make deals, Concordia Protocol adds structured negotiation with binding commitments. Sanctuary also composes with Verascore for portable agent reputation.

Sanctuary never requires Concordia, and Concordia never requires Sanctuary. They compose powerfully when both are deployed: Concordia commitment receipts flow through Sanctuary envelopes, and reputation attestations assemble into a single audit trail. Each ships, runs, and wins on its own. This is a structural commitment, not a tagline. Neither repo imports the other.

Install both if you want the full stack:

npx @sanctuary-framework/mcp-server
pip install concordia-protocol

Open standards

Sanctuary composes with the existing open ecosystem.

• Identity: W3C DIDs, KERI, Verifiable Credentials.

• Execution: Trusted Execution Environments (Intel TDX, AMD SEV-SNP, ARM CCA) on the v2 roadmap.

• Cryptography: Ed25519 today; NIST Post-Quantum Cryptography (ML-DSA / FIPS 204, ML-KEM / FIPS 203) on the migration path; hybrid signing planned after the local sovereignty harness is complete.

• Settlement: x402 (Coinbase micropayments), AP2 (Google Agent Payments Protocol), ACP.

Troubleshooting

For AI coding agents handling install failures, here are the common cases.

Install Step 3 (a) "dashboard=ok" check fails:

• Wait 10 seconds and retry. Dashboard takes a moment to bind on first launch.

• If still failing, check lsof -i :3501-3510 to confirm the dashboard chose a port. The protect output line Sovereignty Dashboard ready: http://localhost:<port> is authoritative; use that port.

Install Step 3 (b) "passphrase=ok" check fails on macOS:

• The protect command may have failed to write to the Keychain (typically a permissions prompt the operator dismissed). Rerun the protect command and approve the Keychain prompt when it appears.

Install Step 3 (b) on Linux or Windows:

• The keychain check is macOS-specific. On Linux, Sanctuary uses Secret Service when available and falls back to an encrypted file at ~/.sanctuary/passphrase.enc. Windows Credential Manager support is queued on the v1.0.x patch track. Test the fallback with test -f ~/.sanctuary/passphrase.enc && echo "passphrase=ok".

Install Step 3 (c) "identities=ok" check fails:

• Confirm protect completed without error. If it did, check ~/.sanctuary/identities/ for .enc files. If absent, the protect command exited early; rerun with --dry-run to see what it would do, then without to retry.

Install Step 3 (d) "audit=ok" check fails:

• Confirm ~/.sanctuary/ exists and is writable by the current user. If it doesn't exist, the protect did not complete; rerun.

• Audit entries are stored encrypted under ~/.sanctuary/state/_audit/, not as plaintext JSONL. Use audit_export_siem when you need a decrypted export.

sanctuary CLI not found after npm install -g:

• Confirm npm bin -g is on the PATH. On macOS with nvm, this typically lives at ~/.nvm/versions/node/<version>/bin/.

Existing harness config overwritten:

• The original is at ~/.sanctuary/backup/config-backup-<timestamp>.json. Restore with sanctuary protect --unwrap from the same fortress/storage context.

For anything not on this list, run sovereignty_audit and surface the report to the operator.

Going deeper

Three audiences, three pointers each.

Operator track: what this feels like to use.

• "What Sovereign Actually Means": the plain-English version.

• "Local ≠ Sovereign": why running on your laptop isn't enough on its own.

• sanctuaryprotocol.ai: ongoing posts in the same voice.

Developer track: how it works.

• CLAUDE.md: complete architecture, security invariants, and threat model.

• SHR_SPEC.md: Sovereignty Health Report format.

• federation-v0.1-hard-gate-walkthrough.md: federation protocol v0.1 design record.

• DID_ENCODING.md: agent DID encoding (base58btc-compliant did:key with legacy base64url migration notes).

• security audit: structured review artifacts and remediation history.

Standards / research track: where this composes.

• Sanctuary Agent Contract (v0.1 spec, W3C AIVS track, shipping).

• Concordia composition (receipts, negotiation, binding commitments; see the Concordia repo).

• Verascore composition (portable agent reputation; see the Verascore repo).

Interop note: agent DIDs

Sanctuary identifies agents with a did:key-style DID derived from the agent's Ed25519 public key, encoded as base58btc under the z multibase prefix per the W3C did:key specification (PR #268). Historical identities created before the base58btc migration may still use the legacy base64url encoding locally; see docs/DID_ENCODING.md for migration notes, the byte layout, and JavaScript and Python decoder snippets with a round-trip verification test.

Contributing

Sanctuary is developed in the open. We welcome:

• Implementation experience. Build against the tools, tell us what works and what doesn't.

• Threat modeling feedback. Security reviews and gap analysis.

• Framework integrations. Bring Sanctuary to other harnesses and agent platforms.

• Open issues and discussions. We take feedback seriously.

See CONTRIBUTING.md for details.

Local development

On first clone, install the pre-commit hook:

cd server
npm install
npm run install-hooks

install-hooks copies .githooks/pre-commit into .git/hooks/pre-commit and makes it executable. The hook runs two gates on every git commit:

1. Typecheck. npm run typecheck must pass with zero TypeScript errors.

2. Test baseline guard. npm test must pass; vitest output must not contain any transform/collection error; the number of test files vitest loaded must equal the number of *.test.ts files under server/test/; the passing-test count must be at least the integer in .test-baseline at repo root.

The second gate defends against a failure class documented in docs/audit/commit-4ac95830-postmortem.md: a parse/transform error silently dropping test files during vitest collection, causing the passing count to look lower without vitest reporting a hard failure.

Total hook runtime: approximately 21 seconds on a modern Mac. Emergency bypass: SKIP_TEST_BASELINE=1 git commit ... (logged to .test-baseline-overrides.log for audit).

The same two gates run in CI via .github/workflows/test-baseline-guard.yml on every PR and push to main. See docs/audit/branch-protection-setup.md for the branch-protection runbook that makes the CI check a hard merge gate.

License

• Code: Apache License 2.0

• Specification: CC-BY-4.0

Use it, build on it, extend it.

Created by Erik Newton.