Quick Start Guide
Get the Lemma Firewall running in under 5 minutes
Quick Start
Get the Lemma Firewall running locally and see agent containment in action.
The fastest way to see the firewall work: pip install lemma-cli && lemma demo. This issues a signed credential, starts the firewall, and runs 6 containment tests in under 30 seconds.
Before You Start
- Install
lemma-cliwithpipx install lemma-cli - Have a browser available for wallet approval, or an existing proof file for non-interactive flows
- Choose stable identifiers for your runtime:
runtime_id,agent_id, andworkspace_id - Know whether your integration is proof-first native or needs temporary bearer compatibility
Step 1: Install and Run the Demo
The demo issues a signed credential from the control plane, starts the local firewall, and proves containment works — all in one command.
pip install lemma-cli
lemma demo --api-base https://lemma.id
You should see 6/6 containment tests pass: allowed requests forwarded, wrong path blocked, wrong method blocked, taint epoch denial, recovery after re-issuance, and revocation denial.
Step 2: Configure Your Runtime
Your runtime should send X-Lemma-Credential directly to protected endpoints by default. This is the primary product contract for new integrations.
LEMMA_BASE_URL=https://lemma.id
LEMMA_PROOF_FILE=/path/to/.lemma-proof.json
LEMMA_RUNTIME_ID=my-runtime
LEMMA_AGENT_ID=my-agent
LEMMA_WORKSPACE_ID=prod
POST /api/protected/action
Headers:
X-Lemma-Credential: <base64url(full signed lemma)>
Content-Type: application/json
Step 3: Use Token Exchange Only for Compatibility
If an older integration still requires bearer transport, exchange the proof for a short-lived access token. Do not make token exchange your default on new routes.
POST /api/auth/exchange-proof
{
"credential": { "...": "signed lemma object" },
"site_id": "example.com",
"requested_scope": ["read"],
"ttl_seconds": 900
}
Step 4: Validate Runtime Controls
Once requests are proof-first, validate that your runtime can be monitored, explained, and contained.
| Check | Expected result |
|---|---|
| Protected request with valid proof | ALLOW with normal response |
| Protected request with missing scope or wrong audience | DENY with machine-readable reason code |
| Decision query / explain | Runtime decisions visible in Agent Ops |
| Kill switch | New privileged actions denied immediately |
OpenClaw Starter Path
If you want the fastest personal runtime onboarding flow, use the starter-safe OpenClaw path:
lemma setup-openclaw --api-base https://lemma.id
This path handles browser approval, local firewall startup, one protected allow, and one kill-to-deny check.
What Lemma Handles For You
| Area | Lemma responsibility |
|---|---|
| Proof issuance and wallet approval | Interactive wallet flow and proof acquisition |
| Verification contract | Proof-first request validation and compatibility token exchange |
| Runtime control plane | Runtime registration, policy defaults, and kill switches |
| Observability | Decision logs, explain endpoints, and alert summaries |
| Remediation | CLI session helpers and lemma doctor --fix for common failures |
CLI Guide - packaged commands for session, remediation, and reference runtime setup
Examples - generic runtime request, server verification, and monitoring examples
Authentication API - proof-first and compatibility endpoint contract
Developer Platform - runtime controls, monitoring, and keys