Doctor Service

September 5, 2026 ยท View on GitHub

The doctor service is Labby's always-on diagnostic surface for local system, authentication, access-store, OAuth relay, and reverse-proxy readiness. It is available through CLI, MCP, and HTTP API.

The generated action catalog is authoritative for exact parameters, scopes, and result schemas.

Current Actions

  • system.checks runs the local system diagnostic set.
  • auth.check validates current authentication readiness.
  • access.check inspects access-store readiness and filesystem safety without creating, migrating, repairing, or otherwise modifying the store.
  • oauth.relay.check checks callback-relay state and optionally probes configured targets; it requires lab:admin.
  • proxy.check validates a requested app/MCP/backend route combination.
  • proxy.preflight checks configured reverse-proxy prerequisites.
  • audit.full streams the combined diagnostic findings, including exactly one local access-store finding.
  • help and schema provide discovery metadata.

Doctor is diagnostic. It reports structured findings and recovery guidance rather than silently repairing state. Repair belongs to the setup service.

Local subprocess probes use one process-wide five-probe admission budget across all concurrent audits, plus per-probe and aggregate deadlines. Dropping an HTTP SSE audit stream cancels its producer and active subprocess tree; disconnected clients do not leave detached diagnostic work running.

system.checks includes config:backup-retention. A warning means the bounded post-commit retention pass could not converge (more than 10 copies or more than 64 MiB remain). Preserve the newest config.toml.bak.* recovery point, verify the active configuration, and follow the recovery procedure in Configuration; doctor never deletes backups.

Access-store health

access.check returns one agent-safe access / store finding. It does not expose database paths, SQL, identities, or raw storage errors. Its stable health classifications project to findings as follows:

ClassificationSeverityOperator response
readyOKNo action required.
missingwarningRun the explicit owner-bootstrap workflow before enabling access enforcement.
uninitializedwarningInitialize or migrate the store and complete owner bootstrap before enforcement.
insecurefailureSecure the state directory, database, and any SQLite sidecars.
corruptfailureRestore or explicitly repair the store before enforcement.
newer_schemafailureUpgrade Labby to a version that supports the store schema.
lockedfailureRetry after the concurrent database operation or checkpoint completes.
read_onlyfailureRestore writable, owner-only access.
unavailablefailureVerify the configured path and filesystem availability.

Missing and uninitialized stores are advisory only while access enforcement remains disabled. All other non-ready states fail closed for readiness. Neither access.check nor audit.full performs owner bootstrap or changes access-control state.