Lab Docs

August 3, 2026 · View on GitHub

This directory is the documentation entrypoint for lab.

The docs are split by topic so contributors do not have to recover architecture, protocol rules, product behavior, and operator workflows from one large design document.

Start Here

Reading Paths

If You Are Adding or Refactoring Code

  1. ARCH.md
  2. CONVENTIONS.md
  3. SERVICES.md
  4. Then the surface doc you are touching: CLI.md, MCP.md, or the relevant HTTP/web docs

If You Are Working on Product Behavior

  1. CLI.md for command behavior
  2. design/CLI_DESIGN_SYSTEM.md for human-readable output language
  3. MCP.md for tool and envelope behavior
  4. TRANSPORT.md and the service docs for HTTP/web behavior
  5. CONFIG.md for config and env implications
  6. OBSERVABILITY.md for logging, request tracing, and redaction rules
  7. ERRORS.md for stable kinds and structured error behavior
  8. design/SERIALIZATION.md for serde and output-boundary rules
  9. DISPATCH.md for layer ownership and adapter direction
  10. SERVICE_LAYER_MIGRATION.md for the current status of the older migration plan

If You Are Working on a Service Integration

  1. SERVICES.md
  2. ARCH.md
  3. CONVENTIONS.md
  4. MCP.md and CLI.md for the public surfaces
  5. OBSERVABILITY.md for instrumentation and verification requirements
  6. ERRORS.md and design/SERIALIZATION.md for transport and envelope consistency
  7. DISPATCH.md for shared operation ownership across CLI, MCP, and API
  8. SERVICE_LAYER_MIGRATION.md for the refactor sequence if you are migrating existing services

If You Are Operating the Project

  1. CONFIG.md
  2. guides/STDIO_MCP_PROXY.md (if directly exposing a stdio server)
  3. INCUS.md
  4. HOST_GATEWAY.md
  5. TRANSPORT.md
  6. OAUTH.md (if deploying with OAuth)
  7. GATEWAY.md (if managing upstream MCP gateways)
  8. UPSTREAM.md (if proxying upstream MCP servers)
  9. CALLBACK_RELAY.md (when operating the public OAuth relay)
  10. REVERSE_PROXY.md
  11. OPERATIONS.md
  12. CLI.md

Topic Map

  • ARCH.md System shape, crate boundaries, shared contracts, and runtime flow.
  • TECH.md Stack choices, toolchain, feature posture, verification surfaces, and release tooling.
  • crate-extract/README.md Architecture, contract, dependency map, execution strategy, and verification plan for extracting Lab into reusable Rust crates, TypeScript packages, and standalone binaries.
  • adr/README.md Accepted architecture decision records.
  • MCP.md Transport model, prompts/completions/logging capabilities, one-tool-per-service design, discovery, envelopes, and destructive-op elicitation.
  • RMCP.md RMCP SDK integration contract: transports, feature posture, handler patterns, auth ownership, and capability rules.
  • OAUTH.md HTTP auth modes: static bearer compatibility, internal Google-backed OAuth, lab-issued JWTs, JWKS, RFC 9728 metadata, and redirect/callback forwarding rules.
  • CALLBACK_RELAY.md Public OAuth callback relay cutover, relay-state import, validation, and rollback.
  • REVERSE_PROXY.md Reverse-proxy requirements and examples for the web UI, OAuth, native MCP, and protected routes.
  • GATEWAY.md Gateway control plane: CRUD, reload/test flows, runtime views, tool exposure policy, and Gateway-managed OAuth protected MCP routes.
  • UPSTREAM.md Upstream MCP proxy gateway: config, discovery, tool collision handling, circuit breaker, resource proxying.
  • TRANSPORT.md Stdio and streamable HTTP transport: middleware stack, stateless discovery, subscriptions, DNS rebinding protection, CORS.
  • guides/STDIO_MCP_PROXY.md Direct stdio-to-Streamable-HTTP proxy quickstart, configuration, auth, Tailscale ownership, security, cleanup, and troubleshooting.
  • apps/gateway-admin/README.md Labby admin UI: local frontend workflow, static export, and same-origin deployment model.
  • design/component-development.md Web UI component workflow: feature specs, render iteration, design-system review, and browser verification.
  • design/design-system-contract.md Labby web UI design-system contract: Aurora tokens, typography, surfaces, components, page patterns, accessibility, and approval rules.
  • SERVICES.md Service inventory, feature gates, plugin metadata, multi-instance support, coverage docs, and add-a-service workflow.
  • coverage/README.md Service coverage doc index.
  • upstream-api/README.md Upstream API/spec reference index.
  • generated/README.md Generated CLI/MCP catalog docs and refresh notes.
  • features/README.md Focused feature docs and implementation artifacts.
  • design/README.md Design contract and artifact index.
  • SERVICE_ONBOARDING.md End-to-end checklist for adding a new service, from upstream spec to verification.
  • SCAFFOLD_AND_AUDIT.md Deferred scaffold/audit command contract.
  • CLI.md Command structure, output rules, confirmation rules, setup/install surfaces, operator commands, and labby oauth relay-local.
  • design/CLI_DESIGN_SYSTEM.md Human-readable CLI output language, semantic tokens, status hierarchy, and pipe-safe color policy.
  • design/CLI_OUTPUT_THEME_API.md Proposed Rust API for CLI semantic styling, color policy resolution, and renderer integration.
  • TUI.md Deferred TUI status.
  • CONFIG.md Env and TOML config ownership, load order, secrets handling, and instance naming.
  • INCUS.md Recommended amd64 Ubuntu 24.04 Incus gateway deployment, bare-metal variant, in-box provisioning, Tailscale TUN passthrough, rollback, and dependency diagnostics.
  • HOST_GATEWAY.md Gateway runtime choice overview: Incus recommended, bare metal secondary, Docker explicit smoke/dev path.
  • ENV.md Deployment-ready env examples and auth-mode variables.
  • OBSERVABILITY.md Mandatory logging boundaries, required fields, correlation rules, redaction, and verification gates.
  • ERRORS.md Shared error taxonomy, stable kind values, MCP and HTTP error envelopes, and status mapping.
  • design/SERIALIZATION.md Serde ownership, stable envelope shapes, CLI output boundaries, and naming rules.
  • DISPATCH.md Surface-neutral dispatch ownership, dependency direction, operation metadata, and adapter responsibilities.
  • SERVICE_LAYER_MIGRATION.md Phase-by-phase guide and checklist for moving existing services into the shared dispatch layer.
  • CONVENTIONS.md Locked engineering rules around async, HTTP, testing, docs, API surface, and privacy.
  • OPERATIONS.md Repo helpers, doctor/health workflows, CI expectations, release behavior, and update rules.
  • CICD.md GitHub Actions check matrix and release behavior.
  • TESTING.md Test runner contract and verification expectations.
  • MARKETPLACE.md Marketplace service, plugin workspace mirrors, save/deploy flows.

Canonical Source Policy

These topic docs are the source of truth for the project.

When updating behavior or decisions:

  • edit the topic doc that owns that concern
  • do not recreate a monolithic “master design” file
  • update multiple docs only when a decision genuinely crosses boundaries

Edit Guide

Use the smallest correct doc:

Common Questions

  • “Where does business logic belong?” See ARCH.md.
  • “What is the canonical MCP response/error shape?” See MCP.md.
  • “How should lab use the RMCP SDK itself?” See RMCP.md.
  • “How do multi-instance services work?” See CONFIG.md and SERVICES.md.
  • “How should a new service be added?” See SERVICES.md.
  • “What rules are locked and review-enforced?” See CONVENTIONS.md.
  • “What is the expected CI and release behavior?” See OPERATIONS.md and TECH.md.
  • “How do we extract Lab into reusable crates/packages?” See crate-extract/README.md.