Haldir

Identidade, segredos e auditoria para agentes de IA. O modo proxy intercepta toda chamada de ferramenta MCP.

Documentação

Haldir — A Camada de Guardião para Agentes de IA

A camada de governança open-source para agentes de IA. Identidade, segredos, auditoria e aplicação de políticas — licença MIT, auto-hospedado ou use nossa nuvem.

O Haldir impõe governança em toda chamada de ferramenta de agente de IA: sessões com escopo definido e limites de gastos, segredos criptografados que o modelo nunca vê, trilha de auditoria à prova de adulteração com encadeamento por hash, aprovações humanas no fluxo e um proxy que intercepta toda chamada MCP antes que ela chegue às suas ferramentas. SDKs nativos para LangChain, CrewAI, AutoGen e Vercel AI SDK.

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

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

CLI

$ haldir overview

  Haldir tenant overview
  acct_xyz123  ·  tier pro  ·  2026-04-19T18:42:11+00:00

  Status     ● ok
  Actions      4,217 / 50,000   ████░░░░░░░░░░░░░░░░    8.4%
  Spend      $ 47.30 this month
  Sessions        12 active  ·  3/10 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

Instale uma vez e controle toda a plataforma pelo terminal:

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 tail --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

Todo comando aceita --json para scripts. haldir --help para a superfície completa.

Duas formas de executar o Haldir

	Auto-hospedado	Nuvem (haldir.xyz)
Preço	Gratuito para sempre	Plano gratuito + planos pagos
Recursos	Tudo	Tudo — mesma API, mesmos SDKs
Você executa	API + Postgres	Nada
Melhor para	Indústrias regulamentadas, ambientes isolados, "preciso ser dono dos dados"	"Só quero que funcione"

Auto-hospedagem em 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/health

Guia completo de auto-hospedagem: SELF_HOSTING.md

Ou use nossa nuvem

pip install haldir

Pronto — aponte para https://haldir.xyz, sem cadastro, API ao vivo.

Ao vivo agora: haldir.xyz · Documentação da API · Especificação OpenAPI · Smithery

🧪 Aceitando 5 parceiros de design agora. 30 dias grátis, acesso total, linha direta com o fundador. Se você está levando agentes de IA para produção, envie um e-mail para sterling@haldir.xyz.

Performance

O Haldir é rápido o suficiente para ficar no caminho crítico de toda chamada de ferramenta de agente sem se tornar um gargalo.

Throughput HTTP de servidor único (gunicorn com 4 workers, 32 clientes concorrentes, backend SQLite otimizado, toda requisição passa pela stack completa de middleware — autenticação, validação, idempotência, métricas, logging estruturado):

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` (create)	1.142	27,7 ms	35,2 ms	39,9 ms
`POST /v1/audit` (hash-chain write)	1.092	28,7 ms	37,6 ms	52,6 ms

Hardware: Intel Core i3-1215U de 12ª geração (8 núcleos, 8 GB de RAM). O SQLite está configurado com WAL + synchronous=NORMAL + mmap de 256 MiB + armazenamento temporário em memória — o p99 da consulta de sessão caiu 52 % em comparação com o caminho sem otimização. Implantações com Postgres (pool configurável via HALDIR_PG_POOL_MIN/MAX) reduzem ainda mais o p99; ative via DATABASE_URL=postgresql://....

Custo de primitivas (Python puro, sem I/O):

Primitiva	p50	Observações
`Vault.store_secret` (criptografia AES-256-GCM + vínculo AAD)	< 10 µs	em memória, sem escrita em banco
`Vault.get_secret` (descriptografia AES-256-GCM + verificação AAD)	< 10 µs	em memória
`AuditEntry.compute_hash` (SHA-256 sobre payload canônico)	< 10 µs
`Gate.check_permission` via REST	~50-120 ms	rede + ida e volta ao banco, na frente do Cloudflare
`Watch.log_action` via REST	~50-150 ms	inclui consulta à cadeia + escrita no banco
Envelope completo de ferramenta governada (verificação + registro)	~100-250 ms

Agentes normalmente aguardam 500-3000 ms por uma resposta do LLM e 100-1000 ms por uma chamada de API upstream, então a sobrecarga do Haldir fica dentro do ruído. Reproduza 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

Conformidade

Um único endpoint gera um pacote de prova de controle pronto para auditoria, cobrindo oito seções, cada uma ancorada a um critério de confiança do SOC2:

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

#	Seção	SOC2
1	Identidade (tenant, assinatura, período)	—
2	Controle de acesso (API keys + escopos por chave)	CC6.1
3	Criptografia (AES-256-GCM, vínculo AAD)	CC6.7
4	Trilha de auditoria (contagem de entradas, integridade da cadeia de hash)	CC7.2
5	Governança de gastos (limites por sessão, registros de pagamento)	CC5.2
6	Aprovações humanas (ciclo de vida de solicitação/decisão)	CC8.1
7	Alertas externos (taxa de sucesso de entrega de webhooks)	CC7.3
8	Assinatura de documento (auto-hash SHA-256)	—

O pacote se autentica: um SHA-256 sobre o JSON canônico das seções 1-7. Um auditor que receber um pacote arquivado pode re-chamar /v1/compliance/evidence/manifest e confirmar que o digest corresponde — prova de que o documento não foi modificado após a emissão.

JSON para upload no cofre de evidências, Markdown para o momento "mostre isso ao auditor" — ambos do mesmo endpoint /v1/compliance/evidence.

Por que o Haldir

Agentes de IA estão chamando APIs, gastando dinheiro e acessando credenciais sem nenhuma supervisão. O Haldir é a camada que faltava:

Sem o Haldir	Com o Haldir
Agente com acesso ilimitado	Sessões com escopo e permissões
Segredos em variáveis de ambiente em texto puro	Cofre criptografado com AES e controle de acesso
Sem limites de gastos	Aplicação de orçamento por sessão
Nenhum registro do que aconteceu	Trilha de auditoria imutável
Nenhuma supervisão humana	Fluxos de aprovação com webhooks
Agente fala diretamente com as ferramentas	Proxy intercepta e aplica políticas

Início Rápido

pip install haldir

from sdk.client import HaldirClient

h = HaldirClient(api_key="hld_xxx", base_url="https://haldir.xyz")

# 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"])

Produtos

Gate — Identidade e Autenticação de Agentes

Sessões com escopo, permissões, limites de gastos e TTL. Sem sessão = sem acesso.

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 — Segredos Criptografados e Pagamentos

Armazenamento criptografado com AES. Agentes solicitam acesso; o Vault verifica o escopo da sessão. Autorização de pagamento com orçamentos por sessão.

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 — Trilha de Auditoria e Conformidade

Registro imutável de cada ação. Detecção de anomalias. Rastreamento de custos. Exportações de conformidade.

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

Proxy — Camada de Aplicação de Políticas

Fica entre agentes e servidores MCP. Toda chamada de ferramenta é interceptada, autorizada e registrada. Suporta aplicação de políticas: allow lists, deny lists, limites de gastos, rate limits, janelas de tempo.

# 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 no Fluxo

Pausa a execução do agente para revisão humana. Notificações via webhook. Aprove ou negue pelo dashboard ou pela 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

O Haldir está disponível como servidor MCP com 10 ferramentas para Claude, Cursor, Windsurf e qualquer IA compatível com MCP:

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

Ferramentas MCP: createSession, getSession, revokeSession, checkPermission, storeSecret, getSecret, authorizePayment, logAction, getAuditTrail, getSpend

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

Arquitetura

Agent (Claude, GPT, Cursor, etc.)
    │
    ▼
┌─────────────────────────────┐
│       Haldir Proxy          │  ← Intercepts every tool call
│  Policy enforcement layer   │
└──────┬──────────┬───────────┘
       │          │
  ┌────▼────┐ ┌───▼────┐
  │  Gate   │ │ Watch  │
  │identity │ │ audit  │
  │sessions │ │ costs  │
  └────┬────┘ └────────┘
       │
  ┌────▼────┐
  │ Vault   │
  │secrets  │
  │payments │
  └────┬────┘
       │
       ▼
  Upstream MCP Servers
  (your actual tools)

Referência da API

Documentação completa em haldir.xyz/docs

Endpoint	Método	Descrição
`/v1/keys`	POST	Criar API key
`/v1/sessions`	POST	Criar sessão de agente
`/v1/sessions/:id`	GET	Obter informações da sessão
`/v1/sessions/:id`	DELETE	Revogar sessão
`/v1/sessions/:id/check`	POST	Verificar permissão
`/v1/secrets`	POST	Armazenar segredo
`/v1/secrets/:name`	GET	Recuperar segredo
`/v1/secrets`	GET	Listar segredos
`/v1/secrets/:name`	DELETE	Excluir segredo
`/v1/payments/authorize`	POST	Autorizar pagamento
`/v1/audit`	POST	Registrar ação
`/v1/audit`	GET	Consultar trilha de auditoria
`/v1/audit/spend`	GET	Resumo de gastos
`/v1/approvals/rules`	POST	Adicionar regra de aprovação
`/v1/approvals/request`	POST	Solicitar aprovação
`/v1/approvals/:id`	GET	Verificar status da aprovação
`/v1/approvals/:id/approve`	POST	Aprovar
`/v1/approvals/:id/deny`	POST	Negar
`/v1/approvals/pending`	GET	Listar pendentes
`/v1/webhooks`	POST	Registrar webhook
`/v1/webhooks`	GET	Listar webhooks
`/v1/proxy/upstreams`	POST	Registrar upstream
`/v1/proxy/tools`	GET	Listar ferramentas do proxy
`/v1/proxy/call`	POST	Chamar via proxy
`/v1/proxy/policies`	POST	Adicionar política
`/v1/usage`	GET	Estatísticas de uso
`/v1/metrics`	GET	Métricas da plataforma

Descoberta de Agentes

O Haldir é descoberto por meio de todos os principais protocolos:

URL	Protocolo
`haldir.xyz/openapi.json`	OpenAPI 3.1
`haldir.xyz/llms.txt`	Documentação legível por LLM
`haldir.xyz/.well-known/ai-plugin.json`	Plugins do ChatGPT
`haldir.xyz/.well-known/mcp/server-card.json`	Descoberta MCP
`haldir.xyz/mcp`	MCP JSON-RPC
`smithery.ai/server/haldir/haldir`	Registro Smithery
`pypi.org/project/haldir`	PyPI

Licença

MIT