Documentation is grouped by what you are trying to do. If you are new, read in the order below: run it, understand how it is built, then go deep on a feature.
| Group | Contents |
|---|---|
| Architecture | How the system is built, and why it is split the way it is |
| Guides | Running, developing, deploying, migrating, extending |
| Product | Feature-level specifications and their authorities |
| Agent runtimes | Qualifying agent and reasoning adapters |
| Reference | Per-process reference and legacy adapters |
| Decisions | Architecture decision records |
| Reports | Point-in-time audits and benchmarks |
- The root README has the shortest runnable path — a Quick start that brings the stack up from a clean clone.
- Architecture and trust model explains what you just started.
- Why LemmaComputer runs as many processes answers the most common question about the design.
- Evaluation, development, and remote workspace workflow is the one setup authority for evaluation, code changes, and local remote-node/Cowork qualification.
How the system is built and why. Read overview.md first.
- Architecture and trust model — system boundaries, policy projection, credential custody, workspace network, governed routing and accounting, the protected-operation protocol, and the Compose network matrix.
- Why LemmaComputer runs as many processes — what each process boundary buys, which are load-bearing trust boundaries, which are only deployment units, and the rule for adding a new one.
- Customer authentication architecture — the accepted Better Auth boundary, authentication database, hosted and customer-managed topology, enterprise SSO, product authorization handoff, and migration sequence.
- LiteLLM gateway architecture — the private administrator API, workspace data path, provider lifecycle, synthetic Auto routing, MCP and OAuth grants, protected execution, and budgets, separating gateway duties from Control authority.
- MCP networking, egress, and OAuth callbacks — outbound model and MCP traffic versus the browser callback path, and the proxy, SSRF, redirect, and provider-registration boundaries.
- Tenant isolation matrix — where tenant scoping is enforced for every persisted and cached record.
- Agent instance identity — how a running agent is identified and bound to policy.
- Organization RBAC — roles, permissions, and the membership authorization boundary.
- Workspace node deployment — the normative remote-node network, mTLS, storage, purge, and qualification contract.
- Workspace guardrail reconciliation — the forced suspension, grant revocation, immutable publication, compatible- selection reconciliation, and recovery contract for organization guardrail updates.
Task-oriented instructions.
- Evaluation, development, and remote workspace workflow — choose a disposable evaluation, isolated task worktree, local split-node qualification, or production-profile path; includes command meanings, node-local Docker authority, relays, mTLS, Cowork, and hosted gaps.
- Local deployment and Microsoft integration setup — the runbook for the transitional Entra and Microsoft 365 integration path.
- Deployment profiles — what
customer-managed,hosted, andworktreechange, and the capability contract between them. - Configuration and operations — reference Compose topology, environment variables, startup, health, persistence, backup, rotation, and production concerns.
- Database migrations — the ledger, legacy baseline, expand/migrate/contract policy, and tests.
- Component extension contracts — subsystem checklists for model routes, MCP connectors, tools, agents, applications, sandbox drivers, channels, and migrations; not a setup guide.
- Demo release runbook — keeping the demo environment pinned, backed up, and separate from development.
- Cloud deployment guides — mapping the logical trust boundaries to provider infrastructure, beginning with the AWS deployment architecture.
Feature-level specifications and the authority that owns each decision.
- AI control plane — the administrator surface mapped to provider, routing, pricing, Team, budget, usage-health, spend, and emissions authorities.
- Governed model routing — stable service classes, deployment rate-card costing, decision evidence, and safe rollout operations.
- AI usage and cost ledger — governed-attempt attribution, normalized provider units, immutable pricing snapshots, reconciliation, privacy, and callback operations.
- AI spend observability — administrator totals, allocation, token categories, price basis, exports, and missing-data states.
- Team spend budgets — period limits, conservative reservations, hard and soft enforcement, overrides, and reconciliation.
- Teams and cost allocation — Team membership, default spending assignment, cost-center references, and the access-control boundary.
- Pinned provider-rate catalogue — the local, hashed pricing evidence used to materialize exact rate cards without egress.
- AI token operational-emissions estimate — the disclosed token-energy proxy, regional grid factors, coverage, and limitations.
- Personal AI usage — the member-facing view of their own usage.
- Activity event protocol and Activity panel — the sanitized employee-visible work trace and its replay and streaming UI.
- Tool-call audit ledger — the record of admitted and terminal tool operations.
- Reasoning adapter qualification — discovery versus qualified runtime adapters, signed route authority, and the live promotion gates for Claude, Hermes, Codex, and future agents.
- Agent model and reasoning adapter playbook — what LiteLLM translates, what LemmaComputer must still govern, the Claude and Hermes implementation differences, and the faster path for future agents.
- Claude reasoning effort — the governed effort control and its transport.
- Service reference — every long-running, one-shot, and dynamic runtime component, its interfaces, dependencies, state, health contract, and extension seam. — the legacy hosted adapter and its real-tenant qualification. It is not the current universal customer-authentication architecture.
Architecture Decision Records (ADRs) preserve consequential design choices: the context at the time, the chosen option, its tradeoffs, and whether it is accepted, amended, or superseded. They explain why a durable decision was made; the Architecture section above describes how the current system works, and Guides describe how to operate it. ADRs remain in the repository after supersession so future maintainers can understand the decision history.
- ADR 0001 — local release gates: why enforcement is local and both profiles share one codebase.
- ADR 0002 — simplified integration and demo tags
- ADR 0003 — deployment profile capability contract
- ADR 0004 — Better Auth adoption and qualification: provider-neutral principal and session contracts, threat model, database and recovery operations, exact pins, and downstream qualification evidence.
- ADR 0005 — catalog-gated Electron sandbox profiles: why the namespace exception is limited to release-qualified applications and arbitrary user-installed Electron apps do not inherit it.
- ADR 0006 — hosted C-minus workspace-node placement and trust: why hosted workspaces use sticky logical-node ownership and remote mTLS plus an internal credential, while health scheduling and failover remain deferred.
Point-in-time evidence. These describe a state of the system on a date, not a current contract.
- Responsive UX and accessibility audit
- Workspace performance benchmark
- Workspace policy design QA
- Settings frame design QA
- Security policy — private vulnerability reporting and the highest-impact trust boundaries.