Haldir
Identidade, segredos e auditoria para agentes de IA. O modo proxy intercepta toda chamada de ferramenta MCP.
Documentação
Haldir
Permissões com escopo, limites de gastos, um cofre criptografado e um registro de auditoria que pode provar que não foi editado — para agentes de IA que chamam ferramentas, movem dinheiro e leem segredos.
Esse loop é a ideia central, rodando ao vivo. Alguém reescreve uma linha no registro de auditoria — silenciosamente, direto no banco de dados. A prova de inclusão da entrada não corresponde mais à raiz Merkle ao vivo, e o veredito muda. Não é detectado por monitoramento, não é detectado por um diff: é detectado por aritmética, porque a raiz é um hash do que o registro realmente contém e a Árvore de Cabeçalhos Assinada anterior já está fixada em algum lugar que você não controla.
→ Experimente você mesmo. Execute haldir serve (abaixo) e abra http://127.0.0.1:8000/demo — a mesma demonstração de adulteração, contra uma instância na sua própria máquina. Ela vem dentro do pacote, então não há nada para baixar e nenhuma conta envolvida.
O que você obtém
- Sessões com escopo — permissões e limites de gastos por agente, revogáveis no momento em que algo parece errado.
- Cofre criptografado — AES-256-GCM. Seu agente solicita um segredo; o modelo nunca o vê. Cada texto cifrado registra qual chave o criou, para que você possa rotacionar a chave de criptografia sem reinserir um único segredo — e sem tempo de inatividade.
- Auditoria à prova de adulteração — cada chamada registrada em uma árvore Merkle RFC 6962 com cabeçalhos de árvore assinados, para que o histórico possa ser comprovado, não apenas confiado.
- Aprovações humanas — pause uma execução em um limite de gastos e receba um webhook.
pip install haldir
haldir serve
Isso inicia um Haldir real nesta máquina — SQLite, sem Docker, sem Postgres, sem conta. Ele gera uma chave de criptografia, aplica o esquema, emite uma chave de API e aponta a CLI para si mesmo, para que o próximo comando simplesmente 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
A partir daí, aponte qualquer coisa para ele — a CLI, o SDK Python, um cliente MCP — ou leia a referência da API em /docs na instância que você iniciou. Quando quiser Postgres e contêineres, haldir init && haldir dev cria e executa isso em vez disso; SELF_HOSTING.md cobre o restante.
Funciona com Claude Code, Cursor, LangChain, CrewAI, AutoGen, LlamaIndex e o Vercel AI SDK — qualquer coisa que possa fazer uma chamada HTTP ou falar MCP. Licença MIT: hospede você mesmo, ou aponte para haldir.xyz (plano gratuito, sem cadastro).
Veja em ação
Aqui está o que o Haldir realmente parece — sem diagramas, sem fichas técnicas, apenas capturas de tela da coisa real.
Sem o Haldir, um agente chama qualquer API que quiser, gasta o que quiser e acessa qualquer segredo que encontrar — com zero supervisão e zero trilha de auditoria. Com o Haldir, cada ação é limitada por escopo, com limite de gastos, registrada de forma imutável, e os segredos nunca saem do cofre.
Aqui estão as três coisas que você veria como novo visitante, em ordem:
-
Página inicial — modo escuro, animação de terminal ao vivo no topo, quatro cartões de produto (Gate, Vault, Watch, Proxy), uma comparação entre auto-hospedagem e nuvem, e um chamado para reivindicar uma vaga de parceiro de design. Uma página, tudo o que um visitante de primeira viagem precisa.
-
Painel na nuvem — é isso que você vê após entrar. Uma barra lateral à esquerda leva você a qualquer página — conta, cotas, sessões, auditoria, webhooks, aprovações, conformidade ou configurações. A visão da conta mostra seu locatário, nível, contagens ao vivo e chaves de API por prefixo (a chave completa nunca é mostrada novamente após ser emitida, e revogar uma nunca envolve um shell de banco de dados).
-
Trilha de auditoria — o recurso matador. Filtre por sessão, agente ou ferramenta. Clique em qualquer linha para ver os detalhes completos da chamada MCP: qual ferramenta foi chamada, qual API upstream ela atingiu, quanto tempo levou, quais argumentos enviou e o que retornou. Esta é a única coisa que faz o produto inteiro funcionar — você pode ver exatamente o que cada agente fez, quando e com o quê.
Aqui está o painel com as partes importantes rotuladas:
A barra lateral à esquerda leva você a qualquer lugar. Os marcadores numerados apontam para as partes que você realmente usará: seu locatário e nível, as contagens ao vivo e suas chaves de API por prefixo — com o botão de revogação bem ali, para que encerrar o acesso de um agente nunca signifique abrir um shell de banco de dados.
Brinque você mesmo
Tudo isso vem dentro do pacote e é servido por haldir serve, então funciona na sua máquina sem conta e sem nada para implantar:
→ A demonstração de adulteração em /demo/tamper — a do GIF acima. Reescreva uma linha real do registro e veja a prova de inclusão parar de corresponder à raiz Merkle. Nada é simulado; é o mesmo código Merkle que a API usa.
→ O playground em /demo — quatro etapas percorrem o caminho feliz (emitir uma chave, abrir uma sessão com escopo, verificar uma permissão, escrever na trilha de auditoria), depois três tentam quebrá-lo: gastar além do limite, revogar a sessão no meio do voo e agir após a revogação. Escolha um escopo que nunca foi concedido na etapa 03 para ver uma negação além de uma aprovação.
→ A galeria em /gallery — todas as capturas de tela desta página em um só lugar, se você preferir olhar a ler.
Quer algo para executar sem instalar nada? Há um binário de demonstração de um arquivo — sem Python, sem clone — e um fixture de três sondas que vem com o pacote. Ambos estão em DEMO.md: o que executar, o que você verá e para que cada sonda foi projetada.
O restante da API
A referência completa está em /docs e /openapi.json em qualquer instância que você estiver executando. Abaixo: o guia rápido em Python, números de desempenho e mapeamento de conformidade.
Há uma opção hospedada em haldir.xyz — plano gratuito, sem cadastro. haldir serve é o caminho que funciona hoje, e o que você deve usar se a nuvem não for o que você quer de qualquer forma.
Duas maneiras de executar
Mesmo produto de qualquer forma.
| Auto-hospedado | Nuvem (haldir.xyz) | |
|---|---|---|
| Preço | Gratuito para sempre | Plano gratuito + planos pagos |
| Você executa | API + Postgres | Nada |
| Melhor para | Regulamentado, isolado, "precisa possuir os dados" | "Apenas faça funcionar" |
O nível de nuvem é gratuito para começar e não precisa de cadastro. Estamos aceitando 5 parceiros de design — 30 dias, acesso total, linha direta com o fundador: sterling@haldir.xyz.
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/healthz
Guia completo de auto-hospedagem: SELF_HOSTING.md
Nuvem (sem configuração)
pip install haldir
É isso — aponte para https://haldir.xyz, sem cadastro para o plano gratuito.
CLI
Instale uma vez, controle toda a plataforma pelo terminal:
$ haldir overview
Haldir tenant overview
acct_xyz123 · tier pro · 2026-04-19T18:42:11+00:00
Status ● ok
API calls 4,217 / 2,500,000 ░░░░░░░░░░░░░░░░░░░ 0.2%
Spend $ 47.30 this month
Sessions 12 active · 3/25 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 todos os comandos e CLI.md é a referência completa — o que cada um faz, as flags que aceita e quais comandos suportam --json (nem todos suportam; a referência diz quais).
Por que Haldir
Agentes de IA estão chamando APIs, gastando dinheiro e acessando credenciais com zero supervisão. Haldir é a camada que faltava:
| Sem Haldir | Com Haldir |
|---|---|
| Agente tem acesso ilimitado | Sessões com escopo e permissões |
| Segredos em variáveis de ambiente em texto puro | Cofre criptografado AES-256-GCM |
| Sem limites de gastos | Aplicação de orçamento por sessão |
| Sem registro do que aconteceu | Auditoria imutável e à prova de adulteração |
| Sem supervisão humana | Fluxos de aprovação com webhooks |
| Agente fala diretamente com ferramentas | Proxy intercepta + aplica |
Tudo à direita é um processo na frente das suas ferramentas. Seu agente mantém suas chamadas de ferramenta existentes; Haldir responde primeiro:
Guia 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"])
Por baixo dos panos, são quatro chamadas HTTP — emitir uma chave, abrir uma sessão, verificar uma permissão, escrever na cadeia de auditoria:
Produtos
Gate — Identidade e Autenticação de Agente
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 e Pagamentos Criptografados
Armazenamento criptografado com AES. Agentes solicitam acesso; 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 para 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
Fica entre agentes e servidores MCP. Cada chamada de ferramenta é interceptada, autorizada e registrada. Suporta aplicação de políticas: listas de permissão, listas de negação, limites de gastos, limites de taxa, 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 Circuito
Pausa a execução do agente para revisão humana. Notificações por webhook. Aprove ou negue pelo painel ou 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á disponível como um servidor MCP com 19 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 (o processo acima registra todas as 19):
| Governança | Prova de adulteração | Aprovações e conformidade |
|---|---|---|
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 |
Há um único catálogo de ferramentas. O servidor stdio (haldir-mcp, ou haldir mcp serve) registra todas as 19; o endpoint hospedado POST /mcp implementa um subconjunto de 10 ferramentas sob os mesmos nomes. Um nome significa a mesma coisa em ambas as superfícies, então um cliente escrito para uma funciona com a outra.
Endpoint HTTP MCP: POST https://haldir.xyz/mcp
Desempenho
Haldir é rápido o suficiente para ficar no caminho crítico de cada chamada de ferramenta de agente sem se tornar o gargalo.
Throughput HTTP em uma única máquina (gunicorn 4 workers, 32 clientes concorrentes, backend SQLite ajustado, cada requisição passa pela pilha completa de middleware — autenticação, validação, idempotência, métricas, registro 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 (criar) | 1.142 | 27,7 ms | 35,2 ms | 39,9 ms |
POST /v1/audit (cadeia de hash) | 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). SQLite é configurado com WAL + synchronous=NORMAL + mmap de 256 MiB + armazenamento temporário em memória — o p99 de busca de sessão caiu 52% em comparação com o caminho não ajustado. Implantações com Postgres (pool configurável via HALDIR_PG_POOL_MIN/MAX) reduzem ainda mais o p99; habilite via DATABASE_URL=postgresql://....
Custo primitivo (Python puro, sem I/O):
| Primitiva | p50 | Observações |
|---|---|---|
Vault.store_secret (criptografia AES-256-GCM + AAD) | < 10 µs | em memória, sem gravação em banco de dados |
Vault.get_secret (descriptografia AES-256-GCM + AAD) | < 10 µs | em memória |
AuditEntry.compute_hash (SHA-256 sobre o payload) | < 10 µs | |
Gate.check_permission via REST | ~50-120 ms | rede + ida e volta ao banco de dados, com front-end Cloudflare |
Watch.log_action via REST | ~50-150 ms | inclui consulta de cadeia + gravação em banco de dados |
| Envelope completo de ferramenta governada (verificação + registro) | ~100-250 ms |
Agentes normalmente aguardam 500-3000 ms por uma conclusão de 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 endpoint produz um pacote de prova de controle pronto para auditoria, cobrindo oito seções, cada uma ancorada a um critério de serviço de confiança 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 (chaves de API + escopos por chave) | CC6.1 |
| 3 | Criptografia (AES-256-GCM, vinculação AAD) | CC6.7 |
| 4 | Trilha de auditoria (contagem de entradas, cadeia de hash) | CC7.2 |
| 5 | Governança de gastos (limites por sessão) | CC5.2 |
| 6 | Aprovações humanas (ciclo de vida de solicitação/decisão) | CC8.1 |
| 7 | Alertas de saída (taxa de entrega de webhook) | 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 recebe 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 de "mostre isso ao auditor", ambos do mesmo endpoint /v1/compliance/evidence.
Retenção e exclusão
Os dados de auditoria são mantidos para sempre por padrão. Quando uma política exigir o contrário, você pode definir uma janela e podar até ela — e a poda permanece comprovável:
haldir retention set 90 # keep 90 days (0 = forever)
haldir retention show # what a prune would remove, before running it
haldir retention prune --yes
O log de auditoria é uma cadeia de hash, então excluir entradas antigas de forma ingênua deixa a cadeia sobrevivente apontando para um hash que não existe mais — o que transformaria uma trilha de auditoria funcional em uma que falha na verificação. Em vez disso, uma Cabeça de Árvore Assinada é obtida sobre o log antes de qualquer remoção, e o hash da última entrada excluída é registrado como o elo através do limite.
O resultado é que a poda não é silenciosa. haldir audit verify ainda passa e relata o que foi removido, juntamente com a raiz Merkle assinada que o confirma — então a resposta honesta a um auditor é "entradas antes deste ponto foram excluídas sob uma política de retenção, e aqui está a raiz que elas produziram na época." Se esse compromisso não puder ser produzido, nada é excluído.
Referência da API
Documentação completa em haldir.xyz/docs — a especificação completa OpenAPI 3.1 está em haldir.xyz/openapi.json.
Endpoints principais (consulte a especificação para a superfície completa):
| Endpoint | Método | Descrição |
|---|---|---|
/v1/keys | POST | Criar chave de API |
/v1/sessions | POST | Criar sessão de agente |
/v1/sessions/:id | GET/DEL | Obter / revogar sessão |
/v1/sessions/:id/check | POST | Verificar permissão |
/v1/secrets | POST/GET/DEL | Armazenar / listar / excluir segredos |
/v1/payments/authorize | POST | Autorizar pagamento |
/v1/audit | POST/GET | Registrar / consultar ações |
/v1/audit/spend | GET | Resumo de gastos |
/v1/audit/retention | GET/PUT | Ler / definir a janela de retenção |
/v1/audit/retention/prune | POST | Podar até a janela (requer confirm) |
/v1/audit/retention/checkpoints | GET | Histórico de poda + compromissos assinados |
/v1/approvals/rules | POST | Adicionar regra de aprovação |
/v1/approvals/request | POST | Solicitar aprovação |
/v1/approvals/:id/approve | POST | Aprovar |
/v1/approvals/:id/deny | POST | Negar |
/v1/webhooks | POST/GET | Registrar / listar webhooks |
/v1/proxy/upstreams | POST | Registrar servidor MCP upstream |
/v1/proxy/call | POST | Chamar através do proxy |
/v1/usage | GET | Estatísticas de uso |
/v1/metrics | GET | Métricas da plataforma |
Descoberta de Agentes
O Haldir é descobrível através 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 |
Parceiros de design procurados
Ao vivo agora: haldir.xyz · Documentação da API · Especificação OpenAPI · Smithery
Estamos aceitando 5 parceiros de design — 30 dias grátis, acesso total, linha direta com o fundador. Se você está lançando agentes de IA em produção, envie um e-mail para sterling@haldir.xyz.
Licença
MIT
Links
- Site: haldir.xyz
- Documentação da API: haldir.xyz/docs
- Smithery: Ver no Smithery
- PyPI: haldir
- OpenAPI: haldir.xyz/openapi.json