Lemma Firewall Documentation
Local-first agent containment with signed credentials. Zero server calls per action.
/
What is the Lemma Firewall?
The Lemma Firewall is a local enforcement gateway for AI agents. It sits between your agent and the APIs it calls, verifying signed credentials on every request via Ed25519 signature check — no server calls on the hot path.
Quick demo
Run lemma demo to see it in action: issues a credential, starts the firewall, and runs containment tests in under 30 seconds. Or follow the quickstart guide.
How the Lemma Firewall Works
Runtime onboarding (one-time setup)
- Developer installs
lemma-cliand starts a wallet session or uses an existing proof file - Lemma.id issues or validates a runtime credential for the connected environment
- Runtime is registered with policy profile, risk defaults, and kill switch enabled
- Your runtime or gateway sends
X-Lemma-Credentialon protected API calls - Agent Ops shows runtime state and control-plane defaults
Per request (proof-native enforcement)
- Gateway validates proof and required scope/audience
- Runtime authorization gate checks active state + kill switch
- Request is allowed/denied with machine-readable reason code
- Decision is logged for query + explain workflows
Default mode is proof-first authorization for sensitive operations, with explicit policy-gated legacy compatibility only where required.
Control and containment
- Runtime kill switch denies new protected actions immediately
- Revocation events propagate through Redis + freshness channels
- Operators can query decisions by runtime or delegator PPID and inspect explain output
Proof Hierarchy
| Layer | Purpose | Boundaries |
|---|---|---|
| Root identity proof | Links operator identity to PPID | Never grants broad runtime access directly |
| Delegation proof | Delegates authority to automation intent | Scope + audience + expiry constrained |
| Runtime binding proof | Binds grant to runtime/agent/workspace | Kill switch and runtime state enforced |
| Run proof (ephemeral) | Constrains a specific job/run window | Short TTL, budgeted operations |
| PoP request signature | Protects each API call from replay | Nonce, method, path, body hash |
Security Boundaries
| Property | How it's enforced |
|---|---|
| Proof-first route protection | Protected routes require signed proofs and policy checks |
| Deny-by-default execution | Missing or ambiguous context produces explicit deny |
| Runtime containment | Kill switch checked before privileged execution |
| Revocation freshness | Revocation list + freshness channels gate stale credentials |
| Identity boundary | PPID is the relying-party identity key; wallet_id is internal plumbing |
| Legacy compatibility | Legacy token paths are explicit, policy-gated, and monitored |
Operator Outcomes
- Connect your own runtime with a packaged CLI flow
- Monitor live activity and decision stream
- Kill/contain runtime or delegated agent
- Explain allow/deny decisions from logs + policy snapshot
- Track deny spikes and revocation lag SLA
Get Started
Ready to run proof-first Agent Ops with your own runtime?
- Quick Start Guide -- install the CLI, acquire a proof, and send
X-Lemma-Credential - Installation -- packaged CLI path and optional reference runtime tooling
- CLI Guide -- session, remediation, and reference runtime commands
- Authentication API -- direct proof-first and compatibility token exchange contract
- Developer Platform -- Agent Ops controls and activity
- Examples -- runtime request, server verification, and monitoring patterns