How it works
Lupid runs as a small docker compose stack. One port leaves the network — the
dashboard on :3000. Postgres, the REST API, the HTTPS-CONNECT gateway, and the MCP
gateway all stay inside the docker network.
Topology
Section titled “Topology”The HTTPS-CONNECT gateway is reachable only inside the docker network. Next.js can’t
reverse-proxy CONNECT tunnels, so agents that want network-level enforcement run in
the same docker network and set HTTPS_PROXY=http://lupid:7070.
Two ways an agent talks to Lupid
Section titled “Two ways an agent talks to Lupid”SDK path
Section titled “SDK path”The TypeScript SDK installs fetch interceptors for OpenAI, Anthropic, Cohere, and
Gemini at init() time. Every call to those providers is routed through Lupid’s
policy engine first, then sent on. No URL changes, no proxy config — the agent code
doesn’t know it’s being governed.
Network proxy path
Section titled “Network proxy path”Set HTTPS_PROXY=http://lupid:7070 in the agent’s process. Every outbound HTTPS
request issues a CONNECT to Lupid, which authenticates the agent, intercepts the
TLS handshake using a dynamically-minted cert from its local CA, runs the enforcement
pipeline, then re-tunnels the request to the real destination.
No agent code changes either. This path is what you want when you don’t control the agent’s source — third-party tooling, browser-based agents, MCP servers.
Where each decision is made
Section titled “Where each decision is made”| Layer | What runs | Where |
|---|---|---|
| AuthN | JWT verification + revocation blocklist lookup | agentum-authn |
| AuthZ | Policy engine evaluates (principal, action, resource) → allow / deny / require_hitl | agentum-authz |
| Inspection | DLP scans prompt / tool-call args / response for 17 detector kinds (emails, SSNs, API keys, …) | agentum-dlp via agentum-mitm-core |
| Approvals | HITL queue; HMAC-signed webhook fan-out to any URL | agentum-api::hitl + webhooks |
| Credentials | Lease tracker; static (encrypted Postgres) / HashiCorp Vault / AWS Secrets Manager / Azure KV | agentum-vault |
| Audit | Append-only writes to audit_events in Postgres (or ClickHouse with --profile audit) | agentum-audit |
| Lifecycle | Agent state machine + JWT revocation via Postgres LISTEN/NOTIFY | agentum-lifecycle + agentum-authn |
Everything Lupid needs lives in Postgres. The schema is one migration —
migrations/001_initial_schema.sql. There are no other writable state stores by
default; ClickHouse, when enabled, only holds audit events.