Haldir

Identidad, secretos y auditoría para agentes de IA. El modo proxy intercepta cada llamada de herramienta MCP.

Documentación

Haldir

Permisos con alcance, límites de gasto, una bóveda cifrada y un registro de auditoría que puede demostrar que no fue editado — para agentes de IA que llaman herramientas, mueven dinero y leen secretos.

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'

Ese bucle es toda la idea, ejecutándose en vivo. Alguien reescribe una fila en el registro de auditoría — silenciosamente, directo en la base de datos. La prueba de inclusión de la entrada ya no coincide con la raíz Merkle en vivo, y el veredicto cambia. No detectado por monitoreo, no detectado por un diff: detectado por aritmética, porque la raíz es un hash de lo que el registro realmente contiene y el Árbol de Cabecera Firmado anterior ya está anclado en algún lugar que no controlas.

→ Pruébalo tú mismo. Ejecuta haldir serve (abajo) y abre http://127.0.0.1:8000/demo — la misma demo de manipulación, contra una instancia en tu propia máquina. Viene incluida dentro del paquete, así que no hay nada que descargar ni cuenta involucrada.

Lo que obtienes

Sesiones con alcance — permisos y límites de gasto por agente, revocables en el momento en que algo parece sospechoso.
Bóveda cifrada — AES-256-GCM. Tu agente solicita un secreto; el modelo nunca lo ve. Cada texto cifrado registra qué clave lo creó, para que puedas rotar la clave de cifrado sin volver a ingresar un solo secreto — y sin tiempo de inactividad.
Auditoría a prueba de manipulación — cada llamada registrada en un árbol Merkle RFC 6962 con cabeceras de árbol firmadas, para que el historial pueda ser probado, no solo confiado.
Aprobaciones humanas — pausa una ejecución al alcanzar un umbral de gasto y recibe un webhook.

pip install haldir
haldir serve

Eso inicia un Haldir real en esta máquina — SQLite, sin Docker, sin Postgres, sin cuenta. Genera una clave de cifrado, aplica el esquema, acuña una clave API y apunta la CLI hacia sí mismo, para que el siguiente comando simplemente funcione:

$ 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

Desde ahí, apunta cualquier cosa hacia él — la CLI, el SDK de Python, un cliente MCP — o lee la referencia de API en /docs en la instancia que iniciaste. Cuando quieras Postgres y contenedores, haldir init && haldir dev prepara y ejecuta eso en su lugar; SELF_HOSTING.md cubre el resto.

Funciona con Claude Code, Cursor, LangChain, CrewAI, AutoGen, LlamaIndex y el SDK de IA de Vercel — cualquier cosa que pueda hacer una llamada HTTP o hablar MCP. Licencia MIT: auto-alójalo, o apunta a haldir.xyz (nivel gratuito, sin registro).

Míralo en acción

Así es como se ve Haldir realmente — sin diagramas, sin hojas de especificaciones, solo capturas de pantalla de lo real.

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

Sin Haldir, un agente llama a cualquier API que quiera, gasta lo que quiera y accede a cualquier secreto que encuentre — con cero supervisión y cero rastro de auditoría. Con Haldir, cada acción está limitada por alcance, limitada en gasto, registrada de forma inmutable, y los secretos nunca salen de la bóveda.

Estas son las tres cosas que verías como visitante nuevo, en orden:

Quick tour: landing page, cloud dashboard, audit trail

Página de inicio — modo oscuro, animación de terminal en vivo en la parte superior, cuatro tarjetas de producto (Gate, Vault, Watch, Proxy), una comparación entre auto-alojamiento y nube, y una llamada para reclamar un lugar como socio de diseño. Una página, todo lo que un visitante por primera vez necesita.
Panel de control en la nube — esto es lo que ves después de iniciar sesión. Una barra lateral a la izquierda te lleva a cualquier página — cuenta, cuotas, sesiones, auditoría, webhooks, aprobaciones, cumplimiento o configuración. La vista de cuenta muestra tu inquilino, nivel, conteos en vivo y claves API por prefijo (la clave completa nunca se vuelve a mostrar después de acuñarse, y revocar una nunca involucra un shell de base de datos).
Rastro de auditoría — la característica estrella. Filtra por sesión, agente o herramienta. Haz clic en cualquier fila para ver los detalles completos de la llamada MCP: qué herramienta se llamó, qué API upstream alcanzó, cuánto tardó, qué argumentos envió y qué devolvió. Esto es lo que hace que todo el producto encaje — puedes ver exactamente qué hizo cada agente, cuándo y con qué.

Aquí está el panel con las partes importantes etiquetadas:

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

La barra lateral a la izquierda te lleva a cualquier lugar. Los marcadores numerados apuntan a las partes que realmente usarás: tu inquilino y nivel, los conteos en vivo y tus claves API por prefijo — con el botón de revocar justo ahí, para que terminar el acceso de un agente nunca signifique abrir un shell de base de datos.

Juega con ello tú mismo

Todo esto viene dentro del paquete y es servido por haldir serve, así que funciona en tu máquina sin cuenta y sin nada que desplegar:

→ La demo de manipulación en /demo/tamper — la del GIF de arriba. Reescribe una fila real del registro y observa cómo la prueba de inclusión deja de coincidir con la raíz Merkle. Nada está simulado; es el mismo código Merkle que la API incluye.

→ El patio de juegos en /demo — cuatro pasos recorren el camino feliz (acuña una clave, abre una sesión con alcance, verifica un permiso, escribe en el rastro de auditoría), luego tres intentan romperlo: gastar más allá del límite, revocar la sesión en pleno vuelo y actuar después de la revocación. Elige un alcance que nunca se otorgó en el paso 03 para ver una denegación además de una aprobación.

→ La galería en /gallery — cada captura de pantalla de esta página en un solo lugar, si prefieres mirar en lugar de leer.

¿Quieres algo para ejecutar sin instalar nada? Hay un binario de demo de un solo archivo — sin Python, sin clonar — y un fixture de tres sondas que viene con el paquete. Ambos están en DEMO.md: qué ejecutar, qué verás y para qué está diseñada cada sonda.

El resto de la API

La referencia completa está en /docs y /openapi.json en la instancia que estés ejecutando. Abajo: el inicio rápido de Python, números de rendimiento y mapeo de cumplimiento.

Hay una opción alojada en haldir.xyz — nivel gratuito, sin registro. haldir serve es la ruta que funciona hoy, y la indicada si la nube no es lo que quieres de todos modos.

Dos formas de ejecutar

El mismo producto de cualquier manera.

	Auto-alojado	Nube (haldir.xyz)
Precio	Gratis para siempre	Nivel gratuito + planes de pago
Tú ejecutas	API + Postgres	Nada
Mejor para	Regulado, aislado, "debe poseer los datos"	"Solo haz que funcione"

El nivel de nube es gratis para empezar y no requiere registro. Estamos tomando 5 socios de diseño — 30 días, acceso completo, línea directa con el fundador: sterling@haldir.xyz.

Auto-alojamiento en 5 minutos

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

Guía completa de auto-alojamiento: SELF_HOSTING.md

Nube (sin configuración)

pip install haldir

Eso es todo — apunta a https://haldir.xyz, sin registro para el nivel gratuito.

CLI

Instala una vez, maneja toda la plataforma desde la 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 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 lista cada comando y CLI.md es la referencia completa — qué hace cada uno, las banderas que acepta y qué comandos soportan --json (no todos lo hacen; la referencia dice cuáles).

Por qué Haldir

Los agentes de IA están llamando APIs, gastando dinero y accediendo a credenciales con cero supervisión. Haldir es la capa que falta:

Sin Haldir	Con Haldir
El agente tiene acceso ilimitado	Sesiones con alcance y permisos
Secretos en variables de entorno en texto plano	Bóveda cifrada AES-256-GCM
Sin límites de gasto	Cumplimiento de presupuesto por sesión
Sin registro de lo que pasó	Auditoría inmutable y a prueba de manipulación
Sin supervisión humana	Flujos de aprobación con webhooks
El agente habla directamente con las herramientas	El proxy intercepta y hace cumplir

Todo lo de la derecha es un proceso frente a tus herramientas. Tu agente mantiene sus llamadas de herramientas existentes; Haldir responde primero:

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

Inicio rápido (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"])

Bajo el capó, eso son cuatro llamadas HTTP — acuña una clave, abre una sesión, verifica un permiso, escribe en la cadena de auditoría:

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

Productos

Gate — Identidad y autenticación de agentes

Sesiones con alcance, permisos, límites de gasto y TTL. Sin sesión = sin acceso.

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 — Secretos cifrados y pagos

Almacenamiento cifrado con AES. Los agentes solicitan acceso; Vault verifica el alcance de la sesión. Autorización de pagos con presupuestos por sesión.

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 — Rastro de auditoría y cumplimiento

Registro inmutable para cada acción. Detección de anomalías. Seguimiento de costos. Exportaciones de cumplimiento.

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

Proxy — Capa de cumplimiento

Se sitúa entre agentes y servidores MCP. Cada llamada de herramienta es interceptada, autorizada y registrada. Soporta políticas de cumplimiento: listas de permitidos, listas de denegados, límites de gasto, límites de tasa, ventanas de tiempo.

# 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 — Humano en el bucle

Pausa la ejecución del agente para revisión humana. Notificaciones por webhook. Aprueba o deniega desde el panel o la 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}'

Servidor MCP

Haldir está disponible como servidor MCP con 19 herramientas para Claude, Cursor, Windsurf y cualquier IA compatible con MCP:

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

Herramientas MCP (el proceso anterior registra las 19):

Gobernanza	Prueba de manipulación	Aprobaciones y cumplimiento
`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`

Hay un solo catálogo de herramientas. El servidor stdio (haldir-mcp, o haldir mcp serve) registra las 19; el endpoint alojado POST /mcp implementa un subconjunto de 10 herramientas bajo los mismos nombres. Un nombre significa lo mismo en ambas superficies, así que un cliente escrito contra una funciona contra la otra.

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

Rendimiento

Haldir es lo suficientemente rápido para estar en la ruta crítica de cada llamada de herramienta de agente sin convertirse en el cuello de botella.

Rendimiento HTTP de una sola máquina (gunicorn 4 workers, 32 clientes concurrentes, backend SQLite ajustado, cada solicitud pasa por la pila completa de middleware — autenticación, validación, idempotencia, métricas, registro estructurado):

Endpoint	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` (crear)	1,142	27.7 ms	35.2 ms	39.9 ms
`POST /v1/audit` (cadena de hash)	1,092	28.7 ms	37.6 ms	52.6 ms

Hardware: Intel Core i3-1215U de 12.ª generación (8 núcleos, 8 GB de RAM). SQLite está configurado con WAL + synchronous=NORMAL + mmap de 256 MiB + almacenamiento temporal en memoria — el p99 de búsqueda de sesión bajó un 52 % frente a la ruta sin ajustar. Las implementaciones con Postgres (pool configurable vía HALDIR_PG_POOL_MIN/MAX) reducen aún más el p99; habilítalo vía DATABASE_URL=postgresql://....

Costo de primitivas (Python puro, sin E/S):

Primitiva	p50	Notas
`Vault.store_secret` (cifrado AES-256-GCM + AAD)	< 10 µs	en memoria, sin escritura en BD
`Vault.get_secret` (descifrado AES-256-GCM + AAD)	< 10 µs	en memoria
`AuditEntry.compute_hash` (SHA-256 sobre el payload)	< 10 µs
`Gate.check_permission` sobre REST	~50-120 ms	red + ida y vuelta a BD, con Cloudflare al frente
`Watch.log_action` sobre REST	~50-150 ms	incluye búsqueda en cadena + escritura en BD
Envoltura completa de herramienta gobernada (verificación + registro)	~100-250 ms

Los agentes normalmente esperan 500-3000 ms por una finalización del LLM y 100-1000 ms por una llamada a API externa, por lo que la sobrecarga de Haldir queda dentro del ruido. Reproduce localmente:

# 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

Cumplimiento

Un endpoint produce un paquete de prueba de control listo para auditoría que cubre ocho secciones, cada una anclada a un criterio de los servicios de confianza SOC2:

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

#	Sección	SOC2
1	Identidad (inquilino, suscripción, período)	—
2	Control de acceso (claves API + alcances por clave)	CC6.1
3	Cifrado (AES-256-GCM, vinculación AAD)	CC6.7
4	Rastro de auditoría (conteo de entradas, cadena de hash)	CC7.2
5	Gobernanza de gasto (límites por sesión)	CC5.2
6	Aprobaciones humanas (ciclo de solicitud/decisión)	CC8.1
7	Alertas salientes (tasa de entrega de webhooks)	CC7.3
8	Firma del documento (auto-hash SHA-256)	—

El paquete se firma a sí mismo: un SHA-256 sobre el JSON canónico de las secciones 1-7. Un auditor que recibe un paquete archivado puede volver a llamar a /v1/compliance/evidence/manifest y confirmar que el digest coincide — prueba de que el documento no fue modificado después de su emisión.

JSON para la carga al almacén de evidencia, Markdown para el momento de "muestra esto al auditor", ambos desde el mismo endpoint /v1/compliance/evidence.

Retención y eliminación

Los datos de auditoría se conservan para siempre por defecto. Cuando una política requiere lo contrario, puedes establecer una ventana y podar hasta ella — y la poda sigue siendo demostrable:

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

El registro de auditoría es una cadena de hash, por lo que eliminar entradas antiguas de forma ingenua deja la cadena superviviente apuntando a un hash que ya no existe — lo que convertiría un rastro de auditoría funcional en uno que falla la verificación. En su lugar, se toma una Cabeza de Árbol Firmada sobre el registro antes de eliminar cualquier cosa, y el hash de la última entrada eliminada se registra como el enlace a través del límite.

El resultado es que la poda no es silenciosa. haldir audit verify sigue pasando, e informa lo que se eliminó junto con la raíz Merkle firmada que lo compromete — por lo que la respuesta honesta a un auditor es "las entradas anteriores a este punto fueron eliminadas bajo una política de retención, y aquí está la raíz que produjeron en ese momento." Si ese compromiso no puede producirse, no se elimina nada.

Referencia de la API

Documentación completa en haldir.xyz/docs — la especificación completa de OpenAPI 3.1 está en haldir.xyz/openapi.json.

Endpoints clave (consulta la especificación para la superficie completa):

Endpoint	Método	Descripción
`/v1/keys`	POST	Crear clave API
`/v1/sessions`	POST	Crear sesión de agente
`/v1/sessions/:id`	GET/DEL	Obtener / revocar sesión
`/v1/sessions/:id/check`	POST	Verificar permiso
`/v1/secrets`	POST/GET/DEL	Almacenar / listar / eliminar secretos
`/v1/payments/authorize`	POST	Autorizar pago
`/v1/audit`	POST/GET	Registrar / consultar acciones
`/v1/audit/spend`	GET	Resumen de gasto
`/v1/audit/retention`	GET/PUT	Leer / establecer la ventana de retención
`/v1/audit/retention/prune`	POST	Podar hasta la ventana (requiere `confirm`)
`/v1/audit/retention/checkpoints`	GET	Historial de poda + compromisos firmados
`/v1/approvals/rules`	POST	Agregar regla de aprobación
`/v1/approvals/request`	POST	Solicitar aprobación
`/v1/approvals/:id/approve`	POST	Aprobar
`/v1/approvals/:id/deny`	POST	Denegar
`/v1/webhooks`	POST/GET	Registrar / listar webhooks
`/v1/proxy/upstreams`	POST	Registrar servidor MCP externo
`/v1/proxy/call`	POST	Llamar a través del proxy
`/v1/usage`	GET	Estadísticas de uso
`/v1/metrics`	GET	Métricas de la plataforma

Descubrimiento de agentes

Haldir es descubrible a través de cada protocolo importante:

URL	Protocolo
`haldir.xyz/openapi.json`	OpenAPI 3.1
`haldir.xyz/llms.txt`	Documentos legibles por LLM
`haldir.xyz/.well-known/ai-plugin.json`	Plugins de ChatGPT
`haldir.xyz/.well-known/mcp/server-card.json`	Descubrimiento MCP
`haldir.xyz/mcp`	MCP JSON-RPC
`smithery.ai/server/haldir/haldir`	Registro de Smithery
`pypi.org/project/haldir`	PyPI

Socios de diseño buscados

En vivo ahora: haldir.xyz · Documentación de la API · Especificación OpenAPI · Smithery

Estamos tomando 5 socios de diseño — 30 días gratis, acceso completo, línea directa con el fundador. Si estás lanzando agentes de IA a producción, escribe a sterling@haldir.xyz.

Licencia

MIT

Enlaces

Sitio web: haldir.xyz
Documentación de la API: haldir.xyz/docs
Smithery: Ver en Smithery
PyPI: haldir
OpenAPI: haldir.xyz/openapi.json