createSessionLABSCO SUMMARY
Fast enough to sit in the hot path, and it publishes the numbers.
The primitives are cheap — secret encrypt and decrypt and audit hash computation all measured under 10 microseconds in-process — while a full governed-tool envelope over REST lands around 100-250 ms, against the 500-3000 ms an agent already waits on a model completion. That framing is the argument: the overhead disappears into noise the agent was already producing. The audit chain signs itself, so an archived compliance pack can be re-verified against the live manifest.
What it is
An open-source control plane for AI agents, with an MCP server as one of its faces. It issues scoped sessions, holds secrets encrypted with AES-256-GCM, authorizes spend against per-session budgets, and writes every action into a tamper-evident audit chain. Self-host it with Docker Compose; the MCP server itself comes from the pip package.
What you get
- Agent sessions with scopes, spend limits and a TTL, revocable at any time, plus permission checks against them —
createSession,getSession,revokeSession,checkPermission - Secret storage and scoped retrieval, so credentials are fetched under a session's authority rather than sitting in the model's context —
storeSecret,getSecret - Payment authorization against a session's budget —
authorizePayment - The audit side: log an action, query the trail, and read spend totals —
logAction,getAuditTrail,getSpend - Beyond MCP: a proxy that registers upstream MCP servers and intercepts every call for policy enforcement, human approval rules that pause execution for review, and a compliance evidence pack covering eight sections mapped to SOC2 criteria
- A CLI over the whole platform — a live overview,
haldir readyfor CI, audit tail and export, andhaldir audit verifyfor hash chain integrity
Requirements
An API key (hld_…) as HALDIR_API_KEY: after installing, run haldir login once and it stashes one; the README pairs this route with Haldir's cloud at haldir.xyz. Install with pip install haldir — the package is haldir (version 0.3.0) — and the MCP entry point is the haldir-mcp command over stdio. Self-hosting needs Docker Compose, an API service plus Postgres, and a base64 32-byte HALDIR_ENCRYPTION_KEY in .env; Postgres is enabled with DATABASE_URL. MIT licensed.
Setup effort
One command plus a key — pip install haldir, then supply credentials
USE CASES
01
Giving an agent an expiring, bounded identity
Create a session with the scopes and spend cap it needs and a TTL, then revoke it when the run is over.
02
Keeping API keys out of the model's context
Store the secret once, then have the agent request it under a session whose scope is checked before the value is released.
03
Stopping an agent from overspending
Authorize each payment against the session budget, and read the running spend total rather than discovering it on the invoice.
04
Answering "what did the agent actually do?"
Log every action as it happens and query the trail afterwards by agent, with the hash chain making silent edits detectable.
10 tools
Listed in project docs. Your client may show a different list.
getSessionrevokeSessioncheckPermissionstoreSecretgetSecretauthorizePaymentlogActiongetAuditTrailgetSpendBEFORE YOU INSTALL
What to know first
Tools you get
10 tools named in the project's documentation.
Requires
- haldir-mcp on PATH
- HALDIR_API_KEY in your environment
Where it runs
All 3 documented clients run the server on your machine.
INSTALLATION
Connect your client
Server setup
TERMINAL
pip install haldirMCP Clients
Claude Desktop, Cursor, Any MCP client
JSON
{
"mcpServers": {
"haldir": {
"command": "haldir-mcp",
"env": {
"HALDIR_API_KEY": "<YOUR_HALDIR_API_KEY>"
}
}
}
}<YOUR_HALDIR_API_KEY> is your Haldir API key: after pip install haldir, run haldir login once and it stashes one (the README pairs pip install haldir with Haldir's cloud at haldir.xyz). A self-hosted Haldir (Docker Compose) creates keys through its own POST /v1/keys endpoint.
