Troubleshooting

When something looks off, three commands diagnose almost everything. Run them in order.

#	Command	What it tells you
1	`waired doctor`	✓/⚠/✗ for gateway token, paused state, engine readiness, mesh peer, and coding-agent integration. In a terminal, press `f` to repair what’s fixable (`--fix` to repair non-interactively).
2	`waired status --observability`	Live snapshot: engine, share, paused, mesh (enrolled / reachable / ready), and the last inference’s decision + latency. Add `-o json` for machine-readable output.
3	`waired claude status`	Whether the Claude Code managed-settings integration is enabled, and where the `managed-settings.json` file lives.

Symptom → first command

Symptom	Start with	What’s happening
Claude Code uses the cloud, not your local model	`waired doctor` → `waired claude status`	If gateway token / paused / engine / mesh peer shows ✗, serving is failing open to Anthropic. Press `f` to rebuild the token + skills. If managed settings aren’t enabled, enable them (see below).
`waired infer` returns 503 `waired_paused`	`waired resume`	Routing is paused; resume it.
`waired infer` returns 503 `waired_inference_disabled`	`waired inference share on`	Sharing is off. (Fine to leave off for local-only use — your own `waired infer` still works.)
`Engine: not ready`	`waired runtimes status` + `waired models ls`	The runtime is down or the model is still pulling.
A mesh peer doesn’t appear / `reachable=false`	`waired status --observability -o json`	Check enrollment, control-plane sync, and WireGuard reachability.
The system tray icon doesn’t appear (Linux)	`waired doctor`	On GNOME the tray needs an AppIndicator host extension. The `system tray host` line tells you when one is missing (see below).
`waired status` says “permission denied” / asks for sudo	`sudo waired status`	On a service install the device state is root-owned; see below.
A command says “waired-agent is not running”	`waired doctor`	The local daemon isn’t reachable — restart the service (see Going deeper).

Common fixes

`waired status` says “permission denied” — or used to say “Not enrolled”

On a service install (the normal sudo waired init flow on Linux/macOS), the device state lives in a system directory — /var/lib/waired on Linux — that only root can read. Running waired status or waired auth status as a regular user can’t read it, so the command exits with a permission message that names the directory and the fix: sudo waired status (Windows: re-run from an elevated prompt).

If you instead see Not enrolled. Run \waired init` to connect this device.with exit code 0, the machine really has no enrollment — runwaired init`.

Claude Code (or OpenCode) isn’t using my model

Run waired doctor. If it flags the gateway token or integration, press f (or run waired link all) to rebuild it. If waired claude status shows the managed-settings integration isn’t enabled, enable it: sudo waired claude enable (Linux/macOS) or, elevated, waired claude enable (Windows). See Coding agents.

waired claude status also shows the last fallback and its reason when requests went to the real Anthropic API instead of your model:

local_no_model — no local model is active on this device yet. Check waired status and pick/pull a model.
local_status_<code> — the local serving path errored with that HTTP status just before the fallback; waired status --observability has the detail.

The waired status line doesn’t show up in Claude Code

Run waired claude status inside the project directory. Claude Code uses a single status line with strict precedence, and a project-level .claude/settings.local.json / .claude/settings.json outranks the user-level entry Waired installs. If yours is shadowed, the status output names the file and prints a one-liner you can append to that status-line script to show the route. Also make sure you restarted the Claude session after waired claude enable.

Engine stays “not ready”

During sign-in, waired init shows the engine come up step by step — “Starting the inference engine…”, “Preparing to download …”, then a live “Downloading : NN% X.X GB / Y.Y GB (Z MB/s)” bar, then “ ready”. A large first model is several GB, so the download step can take a while; that is normal and the bar keeps moving.

If it instead sits at “Waiting for the inference engine to start…” and then prints that the engine still isn’t up, the local engine didn’t come up — run waired status to see the current state, and waired doctor (or journalctl -u waired-agent -e on Linux) for details. The model may also still be downloading — waired models ls shows progress. If the runtime itself is down, waired runtimes status shows details. The first load of a model is slow (a cold CUDA load can take ~60 seconds, and ROCm is similar); the engine retries automatically and recovers.

A model won’t load on an integrated GPU

Recent Ollama versions disable integrated GPUs (AMD Strix Halo / Radeon, Intel iGPU) by default and silently fall back to CPU. They need OLLAMA_IGPU_ENABLE=1. The Windows installer sets this for known iGPUs; on other systems, set the environment variable for the Ollama service and restart it. Also confirm the model fits — see the RAM/VRAM columns in the model catalog.

“This machine can only run a very small model” — should I enable it?

On a low-RAM machine, waired init may report that only a very small model fits, and ask whether to enable local inference anyway (the default is No). At that size a local coding model is very low quality and often produces broken output, so it is usually not worth running — decline, and Waired still works as a secure gateway/relay (it can route to a capable peer on your mesh). Similarly, if the end-of-init benchmark finds the model is too slow and the only lighter option is that tiny model, it offers to turn local inference off. You can revisit either choice later with waired runtimes benchmark, or by re-running waired init on better hardware.

The system tray icon doesn’t appear (Linux / GNOME)

GNOME has no built-in system tray, so the waired-tray icon only renders when an AppIndicator host extension is installed and enabled. waired init installs and enables one automatically when it detects GNOME, and waired doctor flags a system tray host warning when none is present. To set it up by hand:

sudo apt install gnome-shell-extension-appindicator
gnome-extensions enable appindicatorsupport@rgcjonas.gmail.com

Then log out and back in (required on Wayland) so GNOME loads the extension. KDE Plasma has a tray host built in and needs nothing; MATE cannot show the icon at all — use GNOME (with the extension) or KDE to see it.

Windows: `waired infer` returns 502 (Ollama not installed)

The bare Windows one-liner doesn’t bundle Ollama. Install it separately:

iwr -useb https://github.com/gen16k/waired-install/releases/latest/download/ollama-windows.ps1 | iex

(Passing -Control/-Dev to install.ps1 installs Ollama for you.)

A peer isn’t reachable

Run waired status --observability -o json and check each peer’s reachable and last_check. Then confirm:

Both devices enrolled under the same Google account (same network). Compare the account / network lines from waired status on each.
WireGuard can connect — waired peers list shows the peer’s endpoint; suspect a firewall or NAT if direct UDP can’t open. Waired falls back to a relay automatically, so connectivity should still work even when the direct path doesn’t.
The Network Map is current — if waired status shows a stale map, restart the agent.

Going deeper (logs)

Only after waired doctor:

Linux: journalctl -u waired-agent -e
Windows: Get-WinEvent -ProviderName waired-agent -LogName Application -MaxEvents 50
Ollama (bundled engine): the engine log under waired’s state dir — …/runtimes/ollama/logs/engine.log (Linux: /var/lib/waired/…, macOS: /Library/Application Support/waired/…) for repeated 503s during model load. If you brought your own Ollama (--skip-ollama + reuse), see ~/.ollama/logs/server.log instead.

A Restart-Service waired-agent (Windows) or systemctl restart waired-agent (Linux) resolves most transient inconsistencies.