Haldir

Haldir

Scoped permissions, spend caps, an encrypted vault, and an audit log that can prove it wasn't edited — for AI agents that call tools, move money, and read secrets.

[tests] [PyPI] [License: MIT] [GitHub Stars]

[A live Haldir audit log being tampered with: a past entry is rewritten, the inclusion proof stops matching the live Merkle root, and the verdict flips to 'Tamper detected']

That loop is the whole idea, running live. Someone rewrites a row in the audit log — silently, straight in the database. The entry's inclusion proof no longer matches the live Merkle root, and the verdict flips. Not caught by monitoring, not caught by a diff: caught by arithmetic, because the root is a hash of what the log actually contains and the earlier Signed Tree Head is already pinned somewhere you don't control.

→ Try it yourself. Run haldir serve (below) and open http://127.0.0.1:8000/demo — the same tamper demo, against an instance on your own machine. It ships inside the package, so there is nothing to download and no account involved.

What you get

• Scoped sessions — permissions and spend caps per agent, revocable the moment something looks wrong.
• Encrypted vault — AES-256-GCM. Your agent asks for a secret; the model never sees it. Every ciphertext records which key made it, so you can rotate the encryption key without re-entering a single secret — and without downtime.
• Tamper-evident audit — every call logged into an RFC 6962 Merkle tree with signed tree heads, so history can be proven, not just trusted.
• Human approvals — pause a run on a spend threshold and get a webhook.

pip install haldirhaldir serve

That starts a real Haldir on this machine — SQLite, no Docker, no Postgres, no account. It generates an encryption key, applies the schema, mints an API key, and points the CLI at itself, so the next command just works:

$ 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

From there, point anything at it — the CLI, the Python SDK, an MCP client — or read the API reference at /docs on the instance you started. When you want Postgres and containers, haldir init && haldir dev scaffolds and runs that instead; SELF_HOSTING.md covers the rest.

Works with Claude Code, Cursor, LangChain, CrewAI, AutoGen, LlamaIndex and the Vercel AI SDK — anything that can make an HTTP call or speak MCP. MIT licensed: self-host it, or point at haldir.xyz (free tier, no signup).

See it in action

Here's what Haldir actually looks like — no diagrams, no spec sheets, just screenshots of the real thing.

[Without Haldir vs with Haldir: no oversight vs scoped sessions, spend limits, secrets hidden, immutable audit trail]

Without Haldir, an agent calls whatever API it wants, spends whatever it wants, and accesses whatever secret it finds — with zero oversight and zero audit trail. With Haldir, every action is scoped, spend-limited, logged immutably, and secrets never leave the vault.

Here's the three things you'd see as a new visitor, in order:

[Quick tour: landing page, cloud dashboard, audit trail]

1. Landing page — dark mode, live terminal animation at the top, four product cards (Gate, Vault, Watch, Proxy), a self-host vs cloud comparison, and a call to claim a design partner spot. One page, everything a first-time visitor needs.

2. Cloud dashboard — this is what you see after signing in. A sidebar on the left takes you to any page — account, quotas, sessions, audit, webhooks, approvals, compliance, or settings. The account view shows your tenant, tier, live counts, and API keys by prefix (the full key is never shown again after it's minted, and revoking one never involves a database shell).

3. Audit trail — the killer feature. Filter by session, agent, or tool. Click any row to see the full MCP call details: what tool was called, what upstream API it hit, how long it took, what arguments it sent, and what it returned. This is the one thing that makes the whole product click — you can see exactly what every agent did, when, and with what.

Here's the dashboard with the important parts labeled:

[Cloud dashboard with annotations: sidebar, stat cards, sessions table, audit table]

The sidebar on the left takes you anywhere. The numbered markers point at the parts you'll actually use: your tenant and tier, the live counts, and your API keys by prefix — with the revoke button right there, so ending an agent's access never means opening a database shell.

Play with it yourself

All of these ship inside the package and are served by haldir serve, so they work on your machine with no account and nothing to deploy:

→ The tamper demo at /demo/tamper — the one in the GIF above. Rewrite a real log row and watch the inclusion proof stop matching the Merkle root. Nothing is simulated; it is the same Merkle code the API ships.

→ The playground at /demo — four steps walk the happy path (mint a key, open a scoped session, check a permission, write to the audit trail), then three try to break it: spend past the cap, revoke the session mid-flight, and act after revocation. Pick a scope that was never granted in step 03 to see a denial as well as an approval.

→ The gallery at /gallery — every screenshot on this page in one place, if you'd rather look than read.

Want something to run without installing anything? There is a one-file demo binary — no Python, no clone — and a three-probe fixture that ships with the package. Both are in DEMO.md: what to run, what you'll see, and what each probe is built to catch.

The rest of the API

The full reference is at /docs and /openapi.json on whichever instance you are running. Below: the Python quickstart, performance numbers, and compliance mapping.

There is a hosted option at haldir.xyz — free tier, no signup. haldir serve is the path that works today, and the one to reach for if the cloud is not what you want anyway.

Two ways to run

Same product either way.

The cloud tier is free to start and needs no signup. We're taking 5 design partners — 30 days, full access, direct line to the founder: [email protected].

Self-host in 5 minutes

git clone https://github.com/ExposureGuard/haldir.gitcd haldircp .env.example .envpython3 -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 -dcurl http://localhost:8000/healthz

Full self-hosting guide: SELF_HOSTING.md

Cloud (no setup)

pip install haldir

That's it — point at https://haldir.xyz, no signup for the free tier.

CLI

Install once, drive the whole platform from the terminal:

$ 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 haldirhaldir login                           # one-time; stashes API keyhaldir overview --watch                # top-style live dashboardhaldir status                          # green/yellow/red component pillshaldir ready                           # exits 0/1, perfect for CIhaldir audit trail --agent my-bot      # the last N entrieshaldir audit export --format=jsonl --out audit-2026-04.jsonlhaldir audit verify                    # hash chain integrity checkhaldir webhooks deliveries             # last 20 retry attemptshaldir migrate up                      # apply pending schema migrations

haldir --help lists every command and CLI.md is the full reference — what each one does, the flags it takes, and which commands support --json (not all of them do; the reference says which).

Why Haldir

AI agents are calling APIs, spending money, and accessing credentials with zero oversight. Haldir is the missing layer:

Everything on the right is one process in front of your tools. Your agent keeps its existing tool calls; Haldir answers first:

[Haldir architecture: Agent → Proxy → (Gate/Vault/Watch/Policy) → Upstream APIs]

Quick Start (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 sessionsession = h.create_session("my-agent", scopes=["read", "spend:50"])
# Store secrets agents never see directlyh.store_secret("stripe_key", "sk_live_xxx")
# Retrieve with scope enforcementkey = h.get_secret("stripe_key", session_id=session["session_id"])
# Authorize payments against budgeth.authorize_payment(session["session_id"], 29.99)
# Every action is loggedh.log_action(session["session_id"], tool="stripe", action="charge", cost_usd=29.99)
# Revoke when doneh.revoke_session(session["session_id"])

Under the hood that's four HTTP calls — mint a key, open a session, check a permission, write to the audit chain:

[Haldir quickstart: install, create a scoped session, check permission, log the action to the hash-chained audit trail]

Products

Gate — Agent Identity & Auth

Scoped sessions with permissions, spend limits, and TTL. No session = no access.

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 — Encrypted Secrets & Payments

AES-encrypted storage. Agents request access; Vault checks session scope. Payment authorization with per-session budgets.

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 — Audit Trail & Compliance

Immutable log for every action. Anomaly detection. Cost tracking. Compliance exports.

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

Proxy — Enforcement Layer

Sits between agents and MCP servers. Every tool call is intercepted, authorized, and logged. Supports policy enforcement: allow lists, deny lists, spend limits, rate limits, time windows.

# Register an upstream MCP servercurl -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 enforcedcurl -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 — Human-in-the-Loop

Pause agent execution for human review. Webhook notifications. Approve or deny from dashboard or API.

# Require approval for spend over $100curl -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 Server

Haldir is available as an MCP server with 19 tools for Claude, Cursor, Windsurf, and any MCP-compatible AI:

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

MCP Tools (the process above registers all 19):

There is one tool catalog. The stdio server (haldir-mcp, or haldir mcp serve) registers all 19; the hosted POST /mcp endpoint implements a 10-tool subset under the same names. A name means the same thing on both surfaces, so a client written against one works against the other.

MCP HTTP Endpoint: POST https://haldir.xyz/mcp

Performance

Haldir is fast enough to sit in the hot path of every agent tool call without becoming the bottleneck.

Single-box HTTP throughput (gunicorn 4 workers, 32 concurrent clients, tuned SQLite backend, every request goes through the full middleware stack — auth, validation, idempotency, metrics, structured logging):

Hardware: 12th-gen Intel Core i3-1215U (8 cores, 8 GB RAM). SQLite is configured with WAL + synchronous=NORMAL + 256 MiB mmap + in-memory temp store — the session-lookup p99 dropped by 52 % versus the untuned path. Postgres deployments (configurable pool via HALDIR_PG_POOL_MIN/MAX) flatten the p99 further still; enable via DATABASE_URL=postgresql://....

Primitive cost (pure-Python, no I/O):

Agents typically wait 500-3000 ms for an LLM completion and 100-1000 ms for an upstream API call, so Haldir's overhead sits inside the noise. Reproduce locally:

# 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 serviceexport HALDIR_API_KEY=hld_...python bench/bench_primitives.py

Compliance

One endpoint produces an auditor-ready proof-of-control pack covering eight sections, each anchored to a SOC2 trust services criterion:

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

The pack signs itself: a SHA-256 over the canonical JSON of sections 1-7. An auditor receiving an archived pack can re-call /v1/compliance/evidence/manifest and confirm the digest matches — proof the document was not modified after issuance.

JSON for evidence-locker upload, Markdown for the "show this to the auditor" moment, both from the same /v1/compliance/evidence endpoint.

Retention and deletion

Audit data is kept forever by default. When a policy requires otherwise, you can set a window and prune to it — and the prune stays provable:

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

The audit log is a hash chain, so deleting old entries naively leaves the surviving chain pointing at a hash that no longer exists — which would turn a working audit trail into one that fails verification. Instead, a Signed Tree Head is taken over the log before anything is removed, and the hash of the last deleted entry is recorded as the link across the boundary.

The result is that pruning is not silent. haldir audit verify still passes, and reports what was removed along with the signed Merkle root that commits to it — so the honest answer to an auditor is "entries before this point were deleted under a retention policy, and here is the root they produced at the time." If that commitment cannot be produced, nothing is deleted.

API Reference

Full docs at haldir.xyz/docs — the complete OpenAPI 3.1 spec is at haldir.xyz/openapi.json.

Key endpoints (see the spec for the full surface):

Agent Discovery

Haldir is discoverable through every major protocol:

Design partners wanted

Live now: haldir.xyz · API Docs · OpenAPI Spec · Smithery

We're taking 5 design partners — 30 days free, full access, direct line to the founder. If you're shipping AI agents to production, email [email protected].

License

MIT

Links

• Website: haldir.xyz
• API Docs: haldir.xyz/docs
• Smithery: View on Smithery
• PyPI: haldir
• OpenAPI: haldir.xyz/openapi.json