Haldir

Haldir

为调用工具、转移资金和读取机密的 AI Agent 提供限定范围的权限、支出上限、加密保险库，以及可证明未被篡改的审计日志。

这个实时演示展示的就是整个理念。有人悄悄直接在数据库中改写了审计日志的一行。该条目的包含证明不再匹配实时 Merkle 根，判定结果随之翻转。这不是靠监控或差异比较发现的，而是靠计算发现的：根是根据日志的实际内容计算得出的哈希，而更早的签名树头已经固定在你无法控制的地方。

→ 亲自试试。 运行 haldir serve（见下文），然后打开 **http://127.0.0.1:8000/demo**，即可在你自己的机器上运行实例，体验同一个篡改演示。它包含在软件包中，因此无需下载任何内容，也不需要账号。

你将获得

• 限定范围的会话 — 为每个 Agent 设置权限和支出上限，发现异常时可立即撤销。
• 加密保险库 — 使用 AES-256-GCM。你的 Agent 可以请求机密，但模型永远看不到它。每个密文都会记录生成它所用的密钥，因此你可以轮换加密密钥，无需重新输入任何机密，也无需停机。
• 防篡改审计 — 每次调用都会记录到一个带有签名树头的 RFC 6962 Merkle 树中，因此历史记录可以被证明，而不只是被信任。
• 人工审批 — 达到支出阈值时暂停运行，并发送 webhook。

pip install haldir
haldir serve

这会在这台机器上启动一个真正的 Haldir：使用 SQLite，无需 Docker、Postgres 或账号。它会生成加密密钥、应用数据库架构、创建 API 密钥，并将 CLI 指向自身，因此接下来直接运行命令即可：

$ haldir serve

  Haldir is running  http://127.0.0.1:8000
  data: ~/.haldir

  Your API key (saved to the Haldir CLI config):
    hld_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

  Try it:
    haldir overview
    haldir session create --agent my-agent --scopes read

接下来，将任意客户端连接到它：CLI、Python SDK、MCP 客户端，或者在你启动的实例上访问 /docs 阅读 API 参考。需要 Postgres 和容器时，运行 haldir init && haldir dev 即可生成脚手架并启动服务；其余内容请参阅 SELF_HOSTING.md。

适用于 Claude Code、Cursor、LangChain、CrewAI、AutoGen、LlamaIndex 和 Vercel AI SDK，以及任何能够发起 HTTP 调用或使用 MCP 的工具。采用 MIT 许可：可自行托管，也可连接到 haldir.xyz（免费套餐，无需注册）。

实际效果

下面展示 Haldir 的真实样子——没有示意图，没有规格表，只有实际截图。

不使用 Haldir 时，Agent 可以调用任意 API、随意花费，并访问能找到的任何机密——既没有监督，也没有审计追踪。使用 Haldir 后，每项操作都有范围限制、支出上限和不可篡改的日志记录，机密也绝不会离开保险库。

新访客会依次看到以下三项内容：

1. 着陆页 — 深色模式，顶部有实时终端动画，四张产品卡片（Gate、Vault、Watch、Proxy），自托管与云端对比，以及申请设计合作伙伴名额的入口。一个页面就包含首次访问者所需的一切。

2. 云端仪表板 — 登录后看到的页面。左侧边栏可带你前往任意页面——账户、配额、会话、审计、Webhook、审批、合规或设置。账户视图会显示你的租户、套餐、实时计数和按前缀显示的 API 密钥（密钥创建后不会再完整显示，撤销密钥也不需要打开数据库 Shell）。

3. 审计追踪 — 核心功能。可按会话、Agent 或工具筛选。点击任意一行，即可查看完整的 MCP 调用详情：调用了什么工具、请求了哪个上游 API、耗时多久、发送了什么参数，以及返回了什么内容。这正是让整个产品一目了然的功能——你可以准确看到每个 Agent 在何时做了什么，以及具体做法。

下面是标注了重要部分的仪表板：

左侧边栏可带你前往任何位置。编号标记指向你实际会用到的部分：租户和套餐、实时计数，以及按前缀显示的 API 密钥——撤销按钮就在旁边，因此终止 Agent 的访问权限不必打开数据库 Shell。

亲自试用

这些内容都随软件包一同提供，并由 haldir serve 提供服务，因此无需账户，也无需部署，便可在你的机器上运行：

→ 防篡改演示，位于 /demo/tamper——就是上方 GIF 中的演示。改写一条真实日志记录，观察包含证明与 Merkle 根不再匹配。这里没有任何模拟内容；使用的就是 API 随附的同一套 Merkle 代码。

→ 演练场，位于 /demo——通过四个步骤走完顺利流程（创建密钥、开启受限会话、检查权限、写入审计追踪），然后尝试三种破坏方式：超出支出上限、在执行期间撤销会话，以及在撤销后继续操作。在步骤 03 中选择一个从未获授的范围，既能看到拒绝，也能看到批准。

→ 图库，位于 /gallery——本页所有截图都集中在此，适合更愿意看而不是读的你。

想运行点什么，又不想安装任何东西？ 我们提供一个单文件演示二进制文件——无需 Python，也无需克隆仓库——以及一个随软件包提供的三探针测试夹具。两者都列在 DEMO.md 中：运行什么、会看到什么，以及每个探针旨在发现什么问题。

API 的其他内容

完整参考文档可在你所运行实例的 /docs 和 /openapi.json 中查看。下文包括 Python 快速入门、性能数据和合规性映射。

你也可以使用托管版本 haldir.xyz——免费套餐，无需注册。haldir serve 是目前可用的方式；如果你本来就不需要云端服务，优先使用它。

---

两种运行方式

两种方式，产品相同。

	可自托管	云端（haldir.xyz）
价格	永久免费	免费套餐 + 付费方案
由你运行	API + Postgres	无需运行任何内容
适合	受监管、隔离网络、“必须拥有数据”	“只要能用就行”

云端套餐免费起步，无需注册。我们正在招募 5 位设计合作伙伴——30 天、完整访问权限，可直接联系创始人：[email protected]。

5 分钟自托管

git clone https://github.com/ExposureGuard/haldir.git
cd haldir
cp .env.example .env
python3 -c 'import base64, os; print(base64.urlsafe_b64encode(os.urandom(32)).decode())'
# paste the output into .env as HALDIR_ENCRYPTION_KEY, then:
docker compose up -d
curl http://localhost:8000/healthz

完整的自托管指南：SELF_HOSTING.md

云端（无需设置）

pip install haldir

就是这样——指向 https://haldir.xyz，免费套餐无需注册。

---

CLI

安装一次，即可在终端中驱动整个平台：

$ haldir overview

  Haldir tenant overview
  acct_xyz123  ·  tier free  ·  2026-09-30T18:42:11+00:00

  Status     ● ok
  API calls    4,217 / 10,000  ████████░░░░░░░░░░░░   42.2%
  Spend      $ 47.30 this month
  Sessions         3 active  ·  1/1 agents
  Vault            8 secrets  ·  62 accesses this month
  Audit        1,847 entries  ·  0 flagged (7d)  ·  chain ✓
  Webhooks         2 registered  ·  541 deliveries (24h)  ·  99.82% success
  Approvals        1 pending

pip install haldir
haldir login                           # one-time; stashes API key
haldir overview --watch                # top-style live dashboard
haldir status                          # green/yellow/red component pills
haldir ready                           # exits 0/1, perfect for CI
haldir audit trail --agent my-bot      # the last N entries
haldir audit export --format=jsonl --out audit-2026-04.jsonl
haldir audit verify                    # hash chain integrity check
haldir webhooks deliveries             # last 20 retry attempts
haldir migrate up                      # apply pending schema migrations

haldir --help 会列出所有命令，CLI.md 是完整参考文档——说明每个命令的功能、所需标志，以及哪些命令支持 --json（并非所有命令都支持；文档会注明）。

---

为什么选择 Haldir

AI Agent 正在调用 API、花费资金并访问凭据，却完全无人监管。Haldir 正是缺失的那一层：

没有 Haldir	有 Haldir
Agent 拥有无限访问权限	具备权限的限定范围会话
密钥以明文形式存储在环境变量中	使用 AES-256-GCM 加密的保险库
没有支出上限	按会话执行预算限制
没有操作记录	不可篡改且可验证的审计记录
没有人类监管	带 Webhook 的审批工作流
Agent 直接调用工具	代理拦截并强制执行

右侧的所有功能都由一个进程实现，位于你的工具前面。你的 Agent 保留现有的工具调用；Haldir 会先响应：

---

快速入门（Python）

from haldir import HaldirClient

# The key and URL that `haldir serve` printed above.
h = HaldirClient(api_key="hld_xxx", base_url="http://127.0.0.1:8000")

# Create a governed agent session
session = h.create_session("my-agent", scopes=["read", "spend:50"])

# Store secrets agents never see directly
h.store_secret("stripe_key", "sk_live_xxx")

# Retrieve with scope enforcement
key = h.get_secret("stripe_key", session_id=session["session_id"])

# Authorize payments against budget
h.authorize_payment(session["session_id"], 29.99)

# Every action is logged
h.log_action(session["session_id"], tool="stripe", action="charge", cost_usd=29.99)

# Revoke when done
h.revoke_session(session["session_id"])

底层通过四次 HTTP 调用完成——签发密钥、开启会话、检查权限、写入审计链：

---

产品

Gate — Agent 身份与身份验证

具备权限、支出上限和 TTL 的限定范围会话。没有会话 = 无法访问。

curl -X POST https://haldir.xyz/v1/sessions \
  -H "Authorization: Bearer hld_xxx" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "my-bot", "scopes": ["read", "browse", "spend:50"], "ttl": 3600}'

Vault — 加密密钥与支付

AES 加密存储。Agent 请求访问；Vault 检查会话范围。支持按会话预算进行支付授权。

curl -X POST https://haldir.xyz/v1/secrets \
  -H "Authorization: Bearer hld_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "api_key", "value": "sk_live_xxx", "scope_required": "read"}'

Watch — 审计跟踪与合规

记录每项操作的不可变日志。异常检测。成本跟踪。合规性导出。

curl https://haldir.xyz/v1/audit?agent_id=my-bot \
  -H "Authorization: Bearer hld_xxx"

Proxy — 强制执行层

位于 Agent 与 MCP 服务之间。每次工具调用都会被拦截、授权并记录。支持策略执行：允许列表、拒绝列表、支出上限、速率限制、时间窗口。

# Register an upstream MCP server
curl -X POST https://haldir.xyz/v1/proxy/upstreams \
  -H "Authorization: Bearer hld_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "myserver", "url": "https://my-mcp-server.com/mcp"}'

# Call through the proxy — governance enforced
curl -X POST https://haldir.xyz/v1/proxy/call \
  -H "Authorization: Bearer hld_xxx" \
  -H "Content-Type: application/json" \
  -d '{"tool": "scan_domain", "arguments": {"domain": "example.com"}, "session_id": "ses_xxx"}'

Approvals — 人机协同

暂停 Agent 执行，供人工审核。Webhook 通知。可通过仪表板或 API 批准或拒绝。

# Require approval for spend over $100
curl -X POST https://haldir.xyz/v1/approvals/rules \
  -H "Authorization: Bearer hld_xxx" \
  -H "Content-Type: application/json" \
  -d '{"type": "spend_over", "threshold": 100}'

---

MCP 服务

Haldir 可作为 MCP 服务使用，提供 19 个工具，适用于 Claude、Cursor、Windsurf 以及任何兼容 MCP 的 AI：

{
  "mcpServers": {
    "haldir": {
      "command": "haldir-mcp",
      "env": {
        "HALDIR_API_KEY": "hld_xxx"
      }
    }
  }
}

MCP 工具（上述进程会注册全部 19 个工具）：

治理	防篡改	审批与合规
haldir_create_session	haldir_verify_audit_chain	haldir_request_approval
haldir_get_session	haldir_get_tree_head	haldir_get_approval_status
haldir_check_permission	haldir_get_inclusion_proof	haldir_compliance_score
haldir_revoke_session	haldir_get_consistency_proof	haldir_build_evidence_pack
haldir_store_secret	haldir_log_audit_action	haldir_authorize_payment
haldir_get_secret	haldir_query_audit_trail
haldir_list_secrets	haldir_get_spend

工具目录只有一个。stdio 服务（haldir-mcp，或 haldir mcp serve）会注册全部 19 个工具；托管的 POST /mcp 端点则使用相同名称实现其中 10 个工具。在两种形式中，工具名称的含义相同，因此针对其中一种编写的客户端也适用于另一种。

MCP HTTP 端点： POST https://haldir.xyz/mcp

---

性能

Haldir 的速度足以在每次 Agent 工具调用的关键路径中运行，同时不会成为瓶颈。

单机 HTTP 吞吐量（gunicorn 4 个工作进程、32 个并发客户端、经过调优的 SQLite 后端，每个请求都经过完整的中间件堆栈——身份验证、验证、幂等性、指标、结构化日志记录）：

端点	RPS	p50	p95	p99
GET /healthz	1,638	19.1 ms	32.5 ms	41.6 ms
GET /v1/status	1,382	22.2 ms	30.8 ms	45.4 ms
GET /v1/sessions/:id	903	29.2 ms	95.5 ms	172.1 ms
POST /v1/sessions（创建）	1,142	27.7 ms	35.2 ms	39.9 ms
POST /v1/audit（哈希链）	1,092	28.7 ms	37.6 ms	52.6 ms

硬件：第 12 代 Intel Core i3-1215U（8 核、8 GB RAM）。SQLite 配置为 WAL + synchronous=NORMAL + 256 MiB mmap + 内存临时存储——与未经调优的路径相比，会话查询 p99 降低了 52 %。Postgres 部署（可通过 HALDIR_PG_POOL_MIN/MAX 配置连接池）还能进一步降低 p99；通过 DATABASE_URL=postgresql://... 启用。

基础操作开销（纯 Python，无 I/O）：

基础操作	p50	说明
Vault.store_secret（AES-256-GCM 加密 + AAD）	< 10 µs	内存中执行，不写入数据库
Vault.get_secret（AES-256-GCM 解密 + AAD）	< 10 µs	内存中执行
AuditEntry.compute_hash（对载荷计算 SHA-256）	< 10 µs
Gate.check_permission（通过 REST）	~50-120 ms	网络 + 数据库往返，前置 Cloudflare
Watch.log_action（通过 REST）	~50-150 ms	包含链查询 + 数据库写入
完整的受治理工具封装（检查 + 记录）	~100-250 ms

Agent 通常需要等待 500-3000 ms 以获取大模型补全，并需要等待 100-1000 ms 以获取上游 API 调用结果，因此 Haldir 的开销微不足道。可在本地复现：

# Concurrent HTTP throughput (launches a local gunicorn, ~60s total)
python bench/bench_http.py --duration 10 --concurrency 32 --workers 4

# Primitive cost only (no API key needed)
python bench/bench_primitives.py --local

# End-to-end against the hosted service
export HALDIR_API_KEY=hld_...
python bench/bench_primitives.py

---

合规性

一个端点可生成可供审计的控制证明包，涵盖八个部分，每个部分均对应一项 SOC2 信任服务准则：

haldir compliance evidence --since 2026-01-01 --out evidence-q1-2026.md

#	部分	SOC2
1	身份（租户、订阅、期限）	—
2	访问控制（API 密钥 + 每个密钥的作用域）	CC6.1
3	加密（AES-256-GCM、AAD 绑定）	CC6.7
4	审计跟踪（条目数、哈希链）	CC7.2
5	支出治理（每个会话的限额）	CC5.2
6	人工审批（请求／决策生命周期）	CC8.1
7	出站告警（Webhook 投递率）	CC7.3
8	文档签名（SHA-256 自哈希）	—

该证明包会自行签名：对第 1 至 7 部分的规范 JSON 计算 SHA-256。审计员收到归档的证明包后，可以重新调用 /v1/compliance/evidence/manifest，确认摘要匹配——证明文档在签发后未被修改。

用于上传至证据存储库的 JSON，以及用于“向审计员展示”的 Markdown，均由同一个 /v1/compliance/evidence 端点生成。

---

保留与删除

默认情况下，审计数据会永久保留。如果策略另有要求，你可以设置保留期限并据此清理——而且清理过程仍可验证：

haldir retention set 90      # keep 90 days (0 = forever)
haldir retention show        # what a prune would remove, before running it
haldir retention prune --yes

审计日志是哈希链，因此，直接删除旧条目会导致剩余链条指向一个已不存在的哈希值——使原本有效的审计跟踪无法通过验证。为此，系统会在删除任何内容之前，对整个日志生成一个签名树头（Signed Tree Head），并记录最后一条已删除条目的哈希，作为跨越边界的链接。

因此，清理过程并非悄无声息。haldir audit verify 仍会通过验证，并报告删除了哪些内容，以及与这些内容对应的签名 Merkle 根——这样，面对审计员时就能坦诚说明：“此点之前的条目已依据保留策略删除，这是它们当时生成的根。” 如果无法生成这一承诺，则不会删除任何内容。

---

API 参考

完整文档见 haldir.xyz/docs — 完整的 OpenAPI 3.1 规范见 haldir.xyz/openapi.json。

主要端点（完整接口列表请参阅规范）：

端点	方法	描述
/v1/keys	POST	创建 API 密钥
/v1/sessions	POST	创建 Agent 会话
/v1/sessions/:id	GET/DEL	获取 / 撤销会话
/v1/sessions/:id/check	POST	检查权限
/v1/secrets	POST/GET/DEL	存储 / 列出 / 删除密钥
/v1/payments/authorize	POST	授权付款
/v1/audit	POST/GET	记录 / 查询操作
/v1/audit/spend	GET	支出摘要
/v1/audit/retention	GET/PUT	读取 / 设置保留期限
/v1/audit/retention/prune	POST	修剪至保留期限（需要 confirm）
/v1/audit/retention/checkpoints	GET	修剪历史记录 + 已签名承诺
/v1/approvals/rules	POST	添加审批规则
/v1/approvals/request	POST	请求审批
/v1/approvals/:id/approve	POST	批准
/v1/approvals/:id/deny	POST	拒绝
/v1/webhooks	POST/GET	注册 / 列出 Webhook
/v1/proxy/upstreams	POST	注册上游 MCP 服务
/v1/proxy/call	POST	通过代理调用
/v1/usage	GET	使用情况统计
/v1/metrics	GET	平台指标

---

Agent 发现

Haldir 可通过所有主流协议发现：

URL	协议
haldir.xyz/openapi.json	OpenAPI 3.1
haldir.xyz/llms.txt	可供大模型读取的文档
haldir.xyz/.well-known/ai-plugin.json	ChatGPT 插件
haldir.xyz/.well-known/mcp/server-card.json	MCP 发现
haldir.xyz/mcp	MCP JSON-RPC
smithery.ai/server/haldir/haldir	Smithery 注册表
pypi.org/project/haldir	PyPI

---

招募设计合作伙伴

现已上线： haldir.xyz · API 文档 · OpenAPI 规范 · Smithery

我们正在招募 5 位设计合作伙伴 — 免费使用 30 天，全面开放访问，并可直接联系创始人。如果你正在将 AI Agent 部署到生产环境，请发送邮件至 [email protected]。

---

许可证

MIT

---

链接

• 网站： haldir.xyz
• API 文档： haldir.xyz/docs
• Smithery： 在 Smithery 上查看
• PyPI： haldir
• OpenAPI： haldir.xyz/openapi.json