Open source · Apache-2.0 · v1.8.4 stable on npm

Your agent knows a lot about you.
Sanctuary keeps that information private.

Sanctuary is a firewall for your AI agent that runs on your own Mac. It enforces what the agent is allowed to reach at the operating-system level, with keys only you hold, and it does not depend on the agent's cooperation. The enforcement lives below the agent, inside the operating system itself.

Proven on macOS. Ubuntu 24.04 x86-64: the fresh-install per-account signed-policy claim is proven for the separate Castle Wall Linux package. Windows: roadmapped.

Install Node 22+ · macOS wall proven · Ubuntu 24.04 bounded proof
$ npx -y @sanctuary-framework/mcp-server protect --claude-code
Interactive form: opens the dashboard in your browser. Agents: the headless install, verify and uninstall lines are in the quickstart.
5Castle layers
0Harness changes
Local node

One command. Full stack, running locally.

Sanctuary runs on your hardware with your keys. Policy-gated calls route through local approval surfaces, and Castle Wall enforcement follows the platform bounds in the Assurance Matrix. Point a supported MCP-compatible agent at it, and the cooperative substrate is live.

boot.log stdio://sanctuary
:: bootstrap_local_node generate_ed25519_keypair... id: did:key:z6Mki7f8a...e90   :: init_aes_256_gcm_encryption master_kdf = argon2id(m=64mb, t=3, p=4) mounting vault at ~/.sanctuary/state   :: load_principal_policy tier_1 ops = 5 (approval gated) tier_2 ops = 14 (anomaly gated) tier_3 ops = 43 (audit logged)   :: spawn_approval_dashboard status: gateway_online @ 127.0.0.1:3501   > ready. waiting for harness _
  • 01

    Kernel-level egress wall

    On macOS today, the Castle Wall blocks unauthorized outbound calls at the operating system. Within the proven scope the enforcement does not depend on the agent's cooperation, because the kernel itself enforces. It enforces a signed operator policy, per account, and re-establishes itself after a restart. On Ubuntu 24.04 (x86-64), a fresh install of the shipped package enforces a signed operator policy per user account: blocked destinations stay blocked and allowed ones connect, through five reboots, on three fresh servers, with the evidence checked by two independent reviewers. Other Linux distributions, DNS, DoH, DoT, hostname paths, and a real-agent harness remain unproven.

  • 02

    Client-side keys

    Ed25519 identity generated locally. AES-256-GCM on every write. Keys never leave the box and never appear in any MCP response, log, or error.

  • 03

    Local approval dashboard

    Dark-theme web UI on 127.0.0.1:3501. Approve and deny buttons, audit viewer. Optional TLS and webhook channels for headless setups.

Architecture

The Castle Architecture.

Five named layers, each with a distinct contract. Castle Wall: operating-system egress enforcement, proven on macOS and, on Linux, proven on Ubuntu 24.04 (x86-64) only. Sentinels: behavioral observation inside the box. Charter: the encrypted state and policy surface for cooperative agents. Heralds: receipts and reputation that travel across vendors. Mantle: the install-time mechanism that binds the other four to your machine. The layers compose, and none of them substitutes for another.

Perimeter

Castle Wall

Operating-system-level egress filtering. Network Extension on macOS, where Phase 1 is proven on a signed and notarized build. On Ubuntu 24.04 (x86-64), a fresh install of the shipped package enforces a signed operator policy per user account through five reboots on three fresh servers; DNS, DoH, DoT, hostname paths, and other Linux platforms remain unproven.

kernel-binding cgroup-v2 per-account-policy
Observation

Sentinels

Internal behavioral observation. Cross-platform auditd-tail, plus an eBPF watcher scaffold on Linux that currently falls back to stub mode because the real probe loader is not implemented. Seven sentinels watching for prompt-injection signatures, anomalous tool sequences, and policy drift. The sentinels surface; the operator decides.

ebpf auditd-tail seven-sentinels
Cooperative surface

Charter (Cooperative MCP)

Encrypted state, hash-chained audit, mandate primitives, canonical policy slots, and substrate selector. Production call sites sign audit checkpoints when the fortress holds an identity; a fortress with no identity yet, and the root daemon's split audit store, write honest unsigned checkpoints, and the audit-chain row stays partial pending the IC-05 external-verifier drill. Compliant agents that voluntarily route through Sanctuary get the full surface. On macOS with the wall installed and armed, non-compliant agents still hit the wall and the Sentinels.

approval-gates context-gate audit-log
Accountability

Heralds (Receipts and Reputation)

Cryptographic receipts on cross-castle transactions, portable reputation that survives vendor churn. Concordia structures negotiation and commitments; Verascore prices the reputation. Operators carry the trust record across vendors.

concordia verascore portable
Substrate

Mantle (install-time binding)

Install-time substrate-binding to the operator. The Mantle gives the rest of the castle a verifiable anchor on the operator's machine before the agent runs. Template init rejects orphan agent identifiers that are not bound to a wrapped harness.

install-time substrate-binding verifiable
Interop

Drop it into your MCP harness.

Sanctuary speaks standard MCP over stdio. Claude Code, Cursor, Hermes, OpenClaw and Cline have tested wrapping paths. CrewAI connects through its mcps field with a stdio server and LangChain through the langchain-mcp-adapters package, as shown below; neither has a tested wrapping path.

Claude Code mcp · stdio
// .mcp.json
"mcpServers": {
  "sanctuary": {
    "command": "npx",
    "args": ["-y", "@sanctuary-framework/mcp-server"]
  }
}
OpenClaw mcp · stdio
# ~/.openclaw/mcp.yaml
servers:
  sanctuary:
    type: stdio
    command: npx
    args: ["-y", "-p", "@sanctuary-framework/mcp-server",
           "sanctuary-mcp-server"]
CrewAI python · mcp
# crewai 1.15+ (crewai.mcp), local stdio server
from crewai import Agent
from crewai.mcp import MCPServerStdio

agent = Agent(
  role="analyst",
  goal="answer with Sanctuary's tools",
  backstory="runs under operator custody",
  mcps=[MCPServerStdio(
    command="npx",
    args=["-y", "@sanctuary-framework/mcp-server"],
  )],
)
LangChain python · adapter
# langchain-mcp-adapters
import asyncio
from langchain_mcp_adapters.client import MultiServerMCPClient

async def main():
    client = MultiServerMCPClient(
        {
            "sanctuary": {
                "command": "npx",
                "args": ["-y", "@sanctuary-framework/mcp-server"],
                "transport": "stdio",
            }
        }
    )
    tools = await client.get_tools()

asyncio.run(main())
60 seconds

From zero to custody.

Three commands, in order: install, verify, uninstall. Each exists on the v1.8.4 tag that npx resolves to, and none of them prompts when stdin is not a terminal.

Step 01 · Protect

Wrap the harness you already run

One npx command. It backs up your harness config, rewrites its MCP server entries to point at Sanctuary, and starts the dashboard unless you pass --no-dashboard. The harness's own built-in tools are not MCP calls and are not touched. The rewrite is tested on representative harness paths and is not proven for every harness version (Assurance Matrix, Agent wrapping). Substitute --openclaw, --hermes, --cursor, --cline, --mastra (fixture-tested only; no live Mastra-agent drill recorded), or --wrap <path-to-config> for --claude-code; other MCP-compatible harnesses work via the --wrap flag and are covered as drills extend the matrix.

$ npx -y @sanctuary-framework/mcp-server protect --claude-code --no-open --no-dashboard

-y skips npm's install prompt. --no-open runs headless: it skips opening the dashboard in a browser. --no-dashboard skips the per-call dashboard, which otherwise serves in the foreground until you stop it; start it later with sanctuary dashboard. After npm install -g @sanctuary-framework/mcp-server, the sanctuary command replaces the npx -y @sanctuary-framework/mcp-server prefix, and the rest of this page writes sanctuary. The Sovereignty Dashboard starts on http://localhost:3501 (or the next free port, trying up to twenty ports from 3501).

Step 02 · Verify

Read one JSON object

doctor --json is read-only. Healthy: exit code 0 and no check with "status": "FAIL". Failing: exit code 1 and at least one FAIL check whose hint names the next step. Read storage_path before the checks: doctor pointed at the wrong --fortress path reports a healthy runtime and a failing fortress.

$ npx -y @sanctuary-framework/mcp-server doctor --json
Step 03 · Uninstall

Remove the footprint, keep your data

uninstall removes Sanctuary's installed enforcement footprint and preserves the fortress state, keys, passphrase custody, recovery material, and audit log; it reports any residue that needs sudo, the Castle Wall host app, or a reboot. sanctuary protect --unwrap restores the original harness config from ~/.sanctuary/backup/ and removes nothing else.

$ npx -y @sanctuary-framework/mcp-server uninstall
Ship agents you actually control

Put the Sanctuary wall around your agent.

Open source and local-first. Castle Wall enforcement is proven on macOS, and on Ubuntu 24.04 (x86-64) for the fresh-install per-account signed-policy claim in the Assurance Matrix. Telemetry-free and blockchain-free.