Run Doctor (Health Check)
Doctor is a built-in diagnostic tool in the Wayland desktop app. It runs a battery of independent checks across the app’s subsystems and reports a verdict for each one: pass, warn, or fail, with a plain-language detail and a remediation suggestion when something needs attention.
Doctor is the first thing to run when the app behaves unexpectedly, a provider stops responding, or you want to confirm everything is wired up correctly after a fresh install.
Open Doctor
Section titled “Open Doctor”- Open Settings (the gear icon in the sidebar, or the Wayland menu).
- Navigate to the Doctor section in the settings sidebar.
- Click Run (or Re-run if it has run before).
Doctor runs its checks in sequence and reports results as they complete. A summary line at the top shows the overall status and a count of passes, warnings, and failures.
What Doctor checks
Section titled “What Doctor checks”Doctor covers seven categories:
| Category | What is checked |
|---|---|
| Providers | Whether connected providers can reach their endpoints (a live connectivity probe). |
| Models | Whether the model registry is internally consistent: connected providers have at least one model, and the routing table is sane. |
| Engine | Whether the bundled wayland-core engine binary is present and reachable, and whether it has enough providers and models to route requests. |
| MCP | Whether each configured MCP server can be reached. |
| Backends | Whether any detected agent backends (Claude Code, Codex, and others) loaded without errors. |
| Workspace | Whether every configured project workspace path actually exists on disk. If a path has moved or been deleted, this check flags it. |
| Config | Whether OS-level encrypted credential storage is available, and whether the engine config file parses cleanly. |
Each check resolves to a verdict and a one-line detail. On a warn or fail, Doctor also shows a Fix: line with an actionable next step.
Reading results
Section titled “Reading results”- Pass (green): the subsystem looks healthy.
- Warn (yellow): something works but may need attention. The fix line describes what to do.
- Fail (red): the check found a problem that likely affects functionality. The fix line points to the setting or action needed.
The overall status reflects the worst individual verdict: if any check fails, the overall is fail; if any warns, it is warn.
Copying the report
Section titled “Copying the report”Click Copy report to copy the full diagnostic text to your clipboard. The copied report includes each check’s id, category, status, detail, and remediation, formatted as plain text. This is useful for sharing with support or pasting into a bug report.
Re-running
Section titled “Re-running”You can re-run Doctor at any time with the Re-run button. This is useful after you fix something, to confirm the check now passes.
How Doctor differs from wayland-core --doctor
Section titled “How Doctor differs from wayland-core --doctor”The desktop Doctor and the Core CLI diagnostic are separate tools:
- The desktop Doctor (this page) runs inside the Wayland app and checks the app’s own state: its provider registry, the bundled engine, MCP servers configured through the app, and the app’s config.
- The
wayland-coreCLI has its own built-in health checks and--check-onlyflags. Those operate on the standalone CLI installation and its config, not on the desktop app’s state.
If you are running the desktop app, use the desktop Doctor. If you are running wayland-core as a standalone CLI tool, consult the Core docs for its diagnostic options.