Documentation - lemma.id

5-minute quickstart

Install the CLI: pipx install lemma-cli
Run the demo: lemma demo --api-base https://lemma.id — issues a credential, starts the local firewall, and runs 6 containment tests.
Configure identifiers: choose stable runtime_id, agent_id, and workspace_id values for your environment.
Send proofs on protected routes: attach X-Lemma-Credential (base64url-encoded signed lemma) on every privileged API call.
Validate controls: confirm allow/deny decisions appear in Agent Ops and that kill switch denies new privileged actions immediately.

Fastest personal path

For OpenClaw-style local onboarding, run lemma setup-openclaw --api-base https://lemma.id. It handles browser approval, firewall startup, one allowed request, and a kill-to-deny check.

What is Agent Ops?

Agent Ops is lemma.id's proof-first control plane for AI agent runtimes. The Lemma Firewall sits between your agent and upstream APIs, verifying Ed25519-signed credentials on the enforcement hot path — without a server round-trip per action when running locally.

New integrations should send X-Lemma-Credential directly. Exchange proofs for bearer tokens only on legacy routes that cannot yet accept the lemma header.

Runtime onboarding (one-time)

Install lemma-cli and start a wallet session (or use an existing proof file).
lemma.id issues or validates a runtime credential for your connected environment.
The runtime registers with a policy profile, risk defaults, and kill switch enabled.
Your gateway sends X-Lemma-Credential on protected API calls.
Agent Ops shows runtime state, decisions, and control-plane defaults.

Per-request enforcement

Gateway validates proof scope, audience, and signature.
Runtime authorization gate checks active state and kill switch.
Request is allowed or denied with a machine-readable reason code.
Decision is logged for query and explain workflows.

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, and expiry constrained
Runtime binding proof	Binds grant to runtime / agent / workspace	Kill switch and runtime state enforced
Run proof (ephemeral)	Constrains a specific job window	Short TTL, budgeted operations
PoP request signature	Protects each API call from replay	Nonce, method, path, body hash (advanced tier)

Beginner integrations use the full signed credential in X-Lemma-Credential. Advanced integrations may send X-Lemma-Proof plus X-Lemma-PoP for proof-chain and per-request replay resistance.

Security boundaries

Property	How it is 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 and freshness channels gate stale credentials
Identity boundary	PPID is the relying-party identity key; wallet_id is internal plumbing
Taint epoch	Prompt-injection containment — stale epoch denies until re-approval

Installation

Install the packaged CLI with pipx for isolated, repeatable local usage.

Shell

pipx install lemma-cli

Prerequisites: Python 3.10+, a browser for wallet approval (or an existing proof file), and stable runtime_id / agent_id / workspace_id identifiers.

Runtime request contract

Load the signed proof from disk or memory and attach it to protected requests. This is the default contract for new agent integrations.

Environment

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

HTTP

POST /api/protected/action
Headers:
  X-Lemma-Credential: <base64url(full signed lemma)>
  Content-Type: application/json

Compatibility only

Legacy bearer integrations may call POST /api/auth/exchange-proof for a short-lived lm_at_... token. Do not use token exchange as the default on new routes.

CLI reference

Command	Purpose
`lemma demo`	Issue credential, start firewall, run 6 containment tests
`lemma setup-openclaw`	One-command OpenClaw starter: approve, firewall, allow, kill-to-deny
`lemma firewall-connect`	Connect runtime to control plane (aliases: `runtime-onboard`, `openclaw-connect`)
`lemma session start\|status`	Browser-backed wallet session for CLI
`lemma start\|stop\|replay`	Local scoped session + firewall on `:8787`
`lemma doctor --fix`	Remediation by error code (`wallet_unlock_required`, etc.)
`lemma safety-status`	Check local firewall posture
`lemma login`	Headless auth with platform API key (CI only)

Shell — common flows

lemma demo --api-base https://lemma.id

lemma session start --api-base https://lemma.id
lemma firewall-connect --api-base https://lemma.id \
  --runtime-id my-runtime --agent-id my-agent --workspace-id prod

lemma doctor --fix --error wallet_unlock_required --api-base https://lemma.id

Machine-oriented commands support --json with fields schema_version, command, ok, and error_code.

Code examples

Runtime client (Node.js)

Node.js

import fs from 'node:fs/promises';

const proof = JSON.parse(await fs.readFile(process.env.LEMMA_PROOF_FILE, 'utf8'));
const encodedProof = Buffer.from(JSON.stringify(proof)).toString('base64url');

const response = await fetch('https://api.example.com/api/agent/run', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Lemma-Credential': encodedProof,
  },
  body: JSON.stringify({ action: 'site.read' }),
});

Protected backend route (Express)

Express

app.post('/api/agent/run', async (req, res) => {
  const encoded = (req.header('X-Lemma-Credential') || '').trim();
  if (!encoded) {
    return res.status(401).json({ success: false, error: 'auth_required' });
  }
  const credential = JSON.parse(Buffer.from(encoded, 'base64url').toString('utf8'));
  const verification = await verifyCredentialWithTrust(credential);
  if (!verification.valid) {
    return res.status(401).json({ success: false, error: 'invalid_lemma' });
  }
  return res.json({ success: true, actor: credential.subject });
});

API reference

Runtime control-plane endpoints require wallet session or operator auth. Compatibility auth endpoints are listed separately.

Runtime control plane

Method	Path	Purpose
`POST`	`/api/wallet/runtimes/bootstrap`	Register or connect a runtime
`POST`	`/api/wallet/runtimes/issue-proof`	Issue runtime proof
`GET`	`/api/wallet/runtimes`	List runtimes (org/env scoped)
`POST`	`/api/wallet/runtimes/<id>/kill`	Kill switch — deny new privileged actions
`POST`	`/api/wallet/runtimes/<id>/authorize`	Per-action authorization gate
`GET`	`/api/wallet/runtimes/decisions`	Decision feed
`GET`	`/api/wallet/runtimes/decisions/<id>/explain`	Explain allow/deny with policy snapshot
`GET`	`/api/wallet/runtimes/decisions/export`	Export decisions for audit
`GET`	`/api/wallet/runtimes/alerts/summary`	Deny spikes and revocation lag SLA

Compatibility auth

Method	Path	Purpose
`POST`	`/api/auth/exchange-proof`	Exchange verified proof for short-lived bearer token (legacy)
`POST`	`/api/auth/introspect`	Introspect bearer token (API key)
`POST`	`/api/auth/revoke`	Revoke bearer token (API key)

Monitoring (delegated tokens)

Method	Path	Purpose
`GET`	`/api/agent/monitor/summary`	Activity summary (`X-API-Key`)
`GET`	`/api/agent/monitor/events`	Event stream (`X-API-Key`)

Agent Ops console

After connecting a runtime, operators use the Agent Ops console to monitor decisions, publish policies, and trigger kill switches.

Connect your runtime with lemma firewall-connect or lemma setup-openclaw
Monitor live activity and the decision stream
Kill or contain a runtime or delegated agent
Explain allow/deny decisions from logs and policy snapshots
Track deny spikes and revocation lag SLA

Sign in with your lemma.id wallet, then open /admin/agent-ops. The console requires an authenticated wallet session with operator access to your organization.

Validation checklist

Check	Expected result
Protected request with valid proof	`ALLOW` with normal response
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
`lemma demo` containment suite	6/6 tests pass