Sanctuary

你的智能体将比你自己更了解你。确保这始终只属于你们之间。

Sanctuary 是安全、私密 AI 的开源标准：操作系统级强制在 macOS 上已实时可用；Linux 和 Windows 尚未实现实时强制。你的数据始终由你自己的密钥掌控，当前的可移植性边界在保证矩阵中已明确标注。任何智能体，本地或云端，单机或集群。一条命令即可开始。一个仪表盘即可保护全部。

Sanctuary 包裹你机器上或云端的任何 AI 智能体，使所有操作流经策略门禁、平台验证的防护墙、操作者持有的密钥，以及一份你真正能读懂的审计日志。一个仪表盘即可管理你所运行的每一个智能体的安全与隐私，无论是你笔记本电脑上的单个智能体，还是横跨多台机器的整个集群。你的数据，以及你的智能体所建立的信誉，始终保留在你掌控的硬件上，出口包缺口仍开放用于仪表盘导出、跳过的导入计数和轮换密钥导入。

已经在运行 Claude Code、Cursor、Hermes、OpenClaw、Cline 或 Mastra？

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

这一条命令即可为你在用的智能体加上密钥、审计日志、策略门禁和仪表盘。操作系统级防护墙是 macOS 上通过签名应用和扩展路径进行的独立特权武装步骤。请参阅 Castle Wall macOS 安装与武装指南，了解从下载到已验证武装状态的客户路径。你保留你的工具链；Sanctuary 在底层增加保护。

底层原理： macOS 防护墙在真实硬件上经过演练、签名并公证，可经受有值守的重启周期；Linux 强制模块已通过集成验证，但随附的守护进程尚未将其组装为实时内核强制。加密身份和加密状态仍由操作者持有，出口包可移植性为部分实现，因为上述出口包缺口仍然开放。它与 Concordia（智能体协商）和 Verascore（可移植信誉）组合使用，各自独立仓库，且均非必需。

一切主张之下的核心：保管权。 很多工具可以在智能体或其工具链选择在沙箱内运行时对其进行沙箱化。Sanctuary 为更艰难的承诺而生：防护墙由操作者强制实施，不依赖智能体的配合；密钥从不离开你掌控的硬件；没有任何供应商（包括我们）处于路径之中或能解密你的状态。每一项公开能力主张都可追溯到保证矩阵中一条已验证的行，其限制在该行中明确标注。

为何存在： 基础层。

安装

已经在运行 OpenClaw、Hermes、Claude Code、Cursor、Cline 或 Mastra？一条命令即可包裹。

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

或者替换为 --hermes、--claude-code、--cursor、--cline、--mastra，或使用 --wrap <path-to-config> 来包裹任何其他兼容 MCP 的工具链。所列工具链的兼容性在每次发布时都会进行验证；其他兼容 MCP 的工具链可通过 --wrap 标志使用，并随着演练扩展矩阵而覆盖。请参阅 Sanctuary 保证矩阵 了解当前各工具链的状态。你继续使用你喜欢的工具链。Sanctuary 在底层无形地添加基础层。

运行 protect 时会发生什么：

1. 生成一个口令并存储在 macOS 钥匙串中（或在 Linux/Windows 上使用加密的备用文件）。

2. 你现有的工具链配置备份到 ~/.sanctuary/backup/。

3. 配置被重写，使每个工具调用都经由 Sanctuary 路由。

4. Sovereignty 仪表盘在 http://localhost:3501（或下一个空闲端口，最高 3510）启动，并在浏览器中打开，附带一键认证令牌。

5. 每次调用都被记录并受策略门禁控制。敏感内容脱敏和查询层匿名化根据保证矩阵叠加：可识别指纹的头部剥离默认开启，可选的、经同意门控的 PII 重写在数据离开机器之前擦除查询内容，重写的内部分类器固定为本地处理，因此隐私功能永远不会成为出口通道。危险操作需要你的批准。

有用的标志：--dry-run 预览更改而不触碰任何内容。--no-open 以无头模式运行，适用于 CI。--unwrap 恢复原始工具链配置。

备份你的口令：

sanctuary export-passphrase

在确认提示后将口令打印到标准输出。将其存储在密码管理器中。如果丢失，加密状态将无法恢复。

Related MCP server: kevros-mcp

发布状态

main 是开发分支。当前稳定版本为 npm latest 通道上的 v1.7.2。此版本的 macOS Castle Wall 应用作为 Sanctuary-CastleWall.app.zip 附加在 GitHub 发布中，SHA-256 为 0c09842936ffb9d2d65badd6e00638675fbb91756d0efa1ac2eb6d2032ffb736。npm 包安装协作式 Sanctuary 表面；签名 macOS 应用、系统扩展、签名辅助程序和 root 启动服务通过单独的 Castle Wall macOS 安装与武装指南 安装和武装。macOS Castle Wall 边界仍为按 uid 的允许/拒绝加上有值守的启动存活；没有按流程规则归因的审计日志。请参阅 v1.7.2 发布说明、v1.7.1 发布说明 和 CHANGELOG.md 了解完整历史。

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

当前能力摘要：

信任与安全主张在 Sanctuary 保证矩阵 中跟踪。公开主张追溯到该矩阵中的 proven 或 partial 行；每行中标注的平台、缺口和下一步证明限制均予以保留。

Roadmap shape: with the Mac Castle Wall per-uid allow/deny plus attended 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.

Supply-chain posture: release binaries for the macOS enforcement path are Dev-ID-signed and notarized, the CLI authenticates update availability with a signed release manifest before showing signed-channel advice, and every commit to main passes a structural typecheck-plus-test-baseline gate locally and again in CI. Sanctuary does not currently download or apply updates for the operator. Mechanisms and their history: CHANGELOG.md and docs/audit/.

For AI coding agents installing Sanctuary on behalf of an operator

Do not translate the manual Castle Wall reference into a pile of shell commands. Use the resumable observed-state contract:

sanctuary install --profile memory --harness claude-code --json

For the full macOS sovereignty surface, use Hermes:

sanctuary install --profile full --harness hermes --json

Execute only an agent_action argument vector, then rerun the same planner. Stop on human_action and guide the operator through the named Apple consent, exact privileged command, or private custody step. Never execute a human action on the operator's behalf. Stop on blocked and report the missing trust input rather than improvising. Installation is mechanically finished only at complete.

The operator, not the agent, performs three things: Apple consent, bounded privilege authorization, and private recovery custody. In particular, never read the staged recovery file, run sanctuary export-passphrase, capture secret output, or ask the operator to paste recovery material into chat. The passphrase stays in the platform credential store; --agent-guided stages the recovery key outside the fortress without printing it.

The memory profile is the sovereign encrypted-memory/cooperative-policy rung. The full profile adds the signed macOS app, dedicated Hermes account, boot service, content filter, and observed live enforcement. The full planner does not download an enforcement binary or guess its provenance; a verified signed release artifact or explicitly supplied drill candidate must already be installed. See Agent-guided installation for the contract and cold-install acceptance criterion.

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:

Sanctuary ships channel-shape governance templates (policy, egress, budgets, retention) instead of 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 remains the custody root in every mode. Commodity operator-cloud mode does not put the cloud provider outside the runtime trust boundary; sovereign-managed mode requires hardware attestation before it is treated as shipped.

The Castle Architecture

Sanctuary installs the protections your body used to provide by default: a perimeter, custody, memory, and a record of what happened. Everything it protects for you together is your Sanctuary: each machine is a rampart the Castle Wall holds, each fortress is a keep inside those walls, and each agent is a resident of exactly one keep. The unit never blurs: one agent, one account, one fortress, one master key. 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. macOS enforces a signed operator policy with a proven per-uid allow/deny demonstration that survives attended reboot cycles, captured on a real host (drills 2026-06-11 through 2026-06-22, boot survival 5 of 5 on a Dev-ID-signed and notarized binary): agent egress to a non-allowlisted address blocked, allowlisted egress allowed, operator egress unaffected, and enforcement live again after every attended reboot. Linux ships no egress enforcement: the tested nftables, cgroup, and NFQUEUE modules are not wired into the shipped daemon boot path, and the Assurance Matrix row is not_implemented. The macOS proof is one host and one OS version, not an audited per-rule-per-flow trail. 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. Hash-chained audit with rollback detection. Production audit checkpoints are currently unsigned until IC-05 closes. Open defect: IC-05.

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 can be exported through current paths; the full exit guarantee remains partial while the remaining exit-bundle gaps are open. 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.

Working on the code? The TypeScript server has an orientation map at server/src/README.md - a 56-module index of what each module owns, the confusable-name disambiguations, and the frozen surfaces a refactor must never change. Start there, then see CONTRIBUTING.md.

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:

• 身份。 你的智能体拥有一把你拥有的密钥。没有任何提供商可以冒充你或撤销你的智能体。你无需征得任何人的许可即可证明该智能体属于你。

• 数据。 你的智能体状态针对运行它的提供商进行加密。平台能看到发出的调用；它看不到你输入的生活。你的对话、你的记忆和你的计划始终属于你。

• 可移植性。 你的智能体的记忆、声誉和承诺可通过当前的导出路径迁移，但导出包缺口仍然存在，涉及仪表板导出、跳过的导入计数器以及轮换密钥导入。

• 可证明性。 你的智能体所做的事情可通过哈希链审计条目和签名回执表面来证明。生产环境审计检查点目前未签名。

• 退出。 密钥、状态、声誉和承诺均可通过已发布的路径由你移动、复制或离线保存，但在剩余的导出包缺口关闭之前，完整退出保证仅部分生效。

Sanctuary 提供权利基础层。访问权（计算、设备、带宽、读写能力）属于公民基础设施合作伙伴（公共图书馆、法律援助组织、工会、公益技术团体、社区学院），他们代表不自托管用户托管智能体 AI。合作伙伴提供访问权；Sanctuary 提供权利。两者互补，而非相互替代。

兼容的工具

Sanctuary 封装 MCP 兼容的运行时。以下列出的具名运行时在每次发布时都会经过测试；其他 MCP 兼容运行时可通过 --wrap 标志或直接 MCP 配置使用，并随着演练扩展保障矩阵而获得发布测试覆盖。

• OpenClaw（sanctuary protect --openclaw）

• Hermes Agent（sanctuary protect --hermes）

• Claude Code（sanctuary protect --claude-code）

• Cursor（sanctuary protect --cursor）

• Cline（sanctuary protect --cline）

• Mastra（sanctuary protect --mastra）

• LangGraph 和自定义运行时（sanctuary protect --wrap <path>）

• 任何其他 MCP 兼容运行时，通过直接 MCP 配置

与 Concordia 协议组合

当你的智能体需要谈判或达成交易时，Concordia 协议可增加具有约束力承诺的结构化谈判。Sanctuary 还可与 Verascore 组合，实现可移植的智能体声誉。

Sanctuary 从不要求 Concordia，Concordia 也从不要求 Sanctuary。 当两者同时部署时，它们能产生强大的组合效果：Concordia 承诺回执通过 Sanctuary 信封流转，声誉证明汇总为单一审计轨迹。各自独立发布、独立运行、独立取胜。结构性承诺体现在仓库本身。两个仓库互不导入。

如果你想要完整技术栈，请同时安装两者：

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

开放标准

Sanctuary 与现有开放生态系统组合。

• 身份： W3C DID、KERI、可验证凭证。

• 执行： 可信执行环境（Intel TDX、AMD SEV-SNP、ARM CCA）列入 v2 路线图。

• 密码学： 目前使用 Ed25519；NIST 后量子密码学（ML-DSA / FIPS 204、ML-KEM / FIPS 203）在迁移路径上；混合签名计划在本地主权运行时完成后实施。

• 结算： x402（Coinbase 微支付）、AP2（Google 智能体支付协议）、ACP。

故障排查

针对处理安装失败的 AI 编码智能体，以下是常见情况。

安装步骤 3 (a) “dashboard=ok”检查失败：

• 等待 10 秒后重试。仪表板首次启动时需要一点时间绑定端口。

• 如果仍然失败，请检查 lsof -i :3501-3510 以确认仪表板选择了哪个端口。protect 输出行 Sovereignty Dashboard ready: http://localhost:<port> 是权威信息；请使用该端口。

安装步骤 3 (b) “passphrase=ok”检查在 macOS 上失败：

• protect 命令可能未能写入钥匙串（通常是操作员忽略了权限提示）。重新运行 protect 命令，并在出现钥匙串提示时批准。

安装步骤 3 (b) 在 Linux 或 Windows 上：

• 钥匙串检查是 macOS 特有的。在 Linux 上，Sanctuary 在可用时使用 Secret Service，否则回退到 ~/.sanctuary/passphrase.enc 的加密文件。Windows 凭据管理器支持已排入补丁轨道。使用 test -f ~/.sanctuary/passphrase.enc && echo "passphrase=ok" 测试回退方案。

安装步骤 3 (c) “identities=ok”检查失败：

• 确认 protect 已完成且无错误。如果已完成，请检查 ~/.sanctuary/identities/ 中是否有 .enc 文件。如果没有，说明 protect 命令提前退出；使用 --dry-run 重新运行以查看它将执行的操作，然后不带该标志重试。

安装步骤 3 (d) “audit=ok”检查失败：

• 确认 ~/.sanctuary/ 存在且当前用户可写。如果不存在，说明 protect 未完成；请重新运行。

• 审计条目以加密形式存储在 ~/.sanctuary/state/_audit/ 下，而非明文 JSONL。需要解密导出时请使用 audit_export_siem。

npm install -g 后找不到 sanctuary CLI：

• 确认 npm bin -g 在 PATH 中。在 macOS 上使用 nvm 时，通常位于 ~/.nvm/versions/node/<version>/bin/。

承载信任的写入被冻结，或出现 custody_rollback_suspected 审计发现：

• Sanctuary 注意到堡垒看起来比其存续的托管证据所显示的时间更旧，而这从内部看正是恢复的样子。Time Machine 恢复、备份恢复、dotfile 同步或克隆到新机器都会触发此情况，而且你可能并非有意为之（迁移助手或同步工具也算）。服务器继续运行；只有承载信任的写入被暂停，直到你确认恢复。请按照 Castle Wall macOS 安装指南的“恢复与还原”部分操作：运行 sanctuary restore-attest 并输入堡垒口令以记录恢复并解冻写入。

• 如果你没有恢复任何内容，请将此冻结视为可疑情况，并在证明之前轮换主密钥。

现有运行时配置被覆盖：

• 原始文件位于 ~/.sanctuary/backup/config-backup-<timestamp>-<surface-tag><ext>（surface 标签是配置文件路径的短十六进制哈希，扩展名与源配置一致：大多数运行时为 .json；Hermes 封装两个表面并备份两者，主配置 ~/.hermes/cli-config.json 为 .json，辅助配置 ~/.hermes/config.yaml 为 .yaml）。早期版本写入的备份使用旧的 config-backup-<timestamp>.json 名称，仍可恢复。使用 sanctuary protect --unwrap 从相同的堡垒/存储上下文中恢复。

对于此列表未涵盖的任何问题，请运行 sovereignty_audit 并将报告提交给操作员。

深入了解

三类受众，各三个指引。

操作员路线： 使用体验。

• “What Sovereign Actually Means”：通俗易懂的版本。

• “Local ≠ Sovereign”：为什么仅在你的笔记本电脑上运行本身并不足够。

• sanctuaryprotocol.ai：以相同风格持续发布的文章。

开发者路线： 工作原理。

• CLAUDE.md：完整架构、安全不变量和威胁模型。

• SHR_SPEC.md：主权健康报告格式。

• federation-v0.1-hard-gate-walkthrough.md：联邦协议 v0.1 设计记录。

• DID_ENCODING.md：智能体 DID 编码（符合 base58btc 的 did:key，附旧版 base64url 迁移说明）。

• 安全审计：结构化审查工件和修复历史。

标准/研究路线： 组合方向。

• Sanctuary 智能体合约（v0.1 规范，W3C AIVS 轨道，已发布）。

• Concordia 组合（回执、谈判、约束性承诺；参见 Concordia 仓库）。

• Verascore 组合（可移植智能体声誉；参见 Verascore 仓库）。

互操作说明：智能体 DID

Sanctuary 使用从智能体 Ed25519 公钥派生的 did:key 风格 DID 来标识智能体，按照 W3C did:key 规范（PR #268）以 z 多基前缀下的 base58btc 编码。在 base58btc 迁移之前创建的历史身份可能仍会在本地使用旧版 base64url 编码；有关迁移说明、字节布局以及带往返验证测试的 JavaScript 和 Python 解码器代码片段，请参见 docs/DID_ENCODING.md。

贡献

Sanctuary 是开放开发的。我们欢迎：

• 实现经验。 基于这些工具进行构建，告诉我们哪些有效、哪些无效。

• 威胁建模反馈。 安全审查和差距分析。

• 框架集成。 将 Sanctuary 带到其他运行时和智能体平台。

• 开放问题和讨论。 我们认真对待反馈。

详情请参见 CONTRIBUTING.md。

本地开发

首次克隆后，安装 pre-commit 钩子：

cd server
npm install
npm run install-hooks

install-hooks 将 .githooks/pre-commit 复制到 .git/hooks/pre-commit 并使其可执行。该钩子在每次 git commit 时运行两道关卡：

1. 类型检查。 npm run typecheck 必须通过，且零 TypeScript 错误。

2. 测试基线守卫。 npm test 必须通过；vitest 输出不得包含任何转换/收集错误；vitest 加载的测试文件数必须等于 server/test/ 下的 *.test.ts 文件数；通过的测试数必须至少为仓库根目录 .test-baseline 中的整数。

第二道关卡防御的是 docs/audit/commit-4ac95830-postmortem.md 中记录的一类故障：解析/转换错误在 vitest 收集期间静默丢弃测试文件，导致通过数看起来更低而 vitest 未报告硬性失败。

钩子总运行时间：在现代 Mac 上约为 21 秒。紧急绕过：SKIP_TEST_BASELINE=1 git commit ...（记录到 .test-baseline-overrides.log 以供审计）。

同样的两道关卡在 CI 中通过 .github/workflows/test-baseline-guard.yml 在每次 PR 和推送到 main 时运行。分支保护运行手册请参见 docs/audit/branch-protection-setup.md，该手册使 CI 检查成为硬性合并关卡。

许可证

• 代码： Apache License 2.0

• 规范： CC-BY-4.0

使用它，基于它构建，扩展它。

由 Erik Newton 创建。