Troubleshooting

Start here

waired doctor

It checks every part of your setup, marks each one ✓ / ⚠ / ✗, and — press f — repairs what it can. Run it before anything else on this page; it resolves most problems on its own.

Find your symptom

Setting up

• I typed waired and got “command not found”
• No browser opened at sign-in, or the wrong one did
• The sign-in link expired before I finished
• Sign-in stops because the background service is not responding
• Setup stopped partway
• Setup says the inference engine failed to start
• Setup says it cannot download the model you chose
• It says I have reached the device limit
• It says the device is “enrolled system-wide”
• Waired chose a very small model for my machine
• Local inference started off and I did not choose that
• It says local inference is not set up yet
• Setup said it could not complete a test generation

Nothing answers

• I signed in, but Waired says I am signed out
• No answer comes back / the engine stays “not ready”
• Claude Code is still using the cloud
• Claude Code says Waired cannot answer
• The Waired icon says the agent is not running
• A command says “waired-agent is not running”
• macOS: the background service never starts
• Windows: I get a 502 error

Answers are wrong or slow

• Answers are very slow
• My GPU is not being used
• I chose a model bigger than my hardware
• It says the GPU ran out of memory on a long prompt
• Windows: giving the graphics chip more memory made things worse
• A model says it needs a newer inference engine
• This computer has no inference engine
• The Waired entries are missing from /model
• Long Claude Code sessions get summarized

Other computers

• My other computer cannot reach the AI
• Requests stopped working after I pinned a computer

The app itself

• The Waired icon is missing (Linux)
• The status line does not show up in Claude Code

---

I typed waired and got “command not found”

Either the install did not finish, or your terminal was already open when it did and has not picked up the new command yet.

1. Close the terminal and open a new one. This alone fixes it most of the time — a running shell caches where commands live.
2. Still missing? Run the install command again; see Install. It is safe to run twice.

On Windows the command lives at C:\Program Files\Waired\waired.exe. If waired alone does not work, that full path always does.

No browser opened at sign-in, or the wrong one did

The sign-in link is always printed in the terminal before anything opens, so you can finish by hand at any time: copy that link and paste it into the browser you normally use. Sign in there, and stay in that same browser for the rest of setup — the setup page only works in the browser you signed in with.

If a browser you never use opened instead, close it without signing in and open the printed link in the one you want.

Both cases were caused by setup running with administrator rights, and are fixed in current versions:

waired update

The sign-in link expired before I finished

The link that waired init prints is valid for a limited time — Waired’s servers decide how long. A two-factor prompt on a phone in another room, or a tab left open while you do something else, can be enough to use it up. When the time runs out, the terminal stops with:

waired: login expired. Run `waired init` again

Do exactly that:

sudo waired init

Nothing is broken and nothing needs cleaning up: it prints a fresh link, and you sign in with that one instead. (Windows: waired init from an administrator prompt.)

If you finish signing in in the browser after the terminal has already stopped, the browser no longer claims it worked: it says the sign-in link has expired and sends you back to the terminal to run waired init again. If you had already reached the device list in the web console, the banner there says the sign-in expired before this computer finished registering, and to run waired init again on it. All three surfaces are saying the same thing — the computer is registered by the command waiting in the terminal, and that command has stopped, so the browser cannot finish the job on its own.

Earlier versions gave up on a fixed wait of their own, with a line about a request deadline that named nothing you could act on, while the browser went on saying the setup would continue by itself — so a computer that had quietly stopped looked exactly like one still working. Now the terminal waits as long as the link is valid, says what happened in one sentence, and the browser stops promising a computer that is not coming.

Sign-in stops because the background service is not responding

Signing in happens through the background service: it is what talks to Waired, and what keeps this computer connected afterwards. If it is not answering, sign-in stops rather than continuing without it:

Waired's background service is installed but isn't responding, so sign-in can't continue.
  Check what's wrong:  waired doctor
  Start it:            sudo systemctl start waired-agent
  Then run again:      sudo waired init

Work through those three lines in order. waired doctor names the actual fault; on macOS the usual one is the service never starting at all.

Earlier versions signed in anyway when this happened. It looked like it worked — but the computer ended up signed in and unable to finish setup in the browser, with nothing on the machine itself explaining why. Stopping with a message you can act on replaced that.

If the message says “Waired isn’t running in the background” instead, no background service is registered on this computer at all — normally because the programs are being run directly rather than installed. Start waired-agent first, then run waired init again.

Sign-in worked, but the setup steps did not run

Reads and writes reach the background service by different routes, so a computer can reach it for one and not the other. When setup cannot reach it at all, waired init says so rather than continuing in silence:

warn: could not ask the background service about setup (…); its setup steps will be skipped. Run "waired doctor" to see why.

That run skips the steps that need the background service — installing the AI software, connecting coding tools, and reporting progress to the browser. Sign-in itself is unaffected: the computer stays signed in.

A milder form means the question got through and only the first update did not:

warn: could not tell the background service that setup is running (…); retrying in the background. If the browser shows no progress, run "waired doctor".

That one repairs itself within about ten seconds. If the browser still shows no progress after that, run waired doctor.

Before these lines existed, either failure looked exactly like a computer whose background service is too old to have the feature at all. That last case is still silent, deliberately — there is nothing to fix on such a computer except updating it, and setup falls back to the older behaviour on its own.

Setup stopped partway

The setup page names what happened. Each message means something specific:

What you see	What it means	What to do
“The setup command on … was closed before this finished. Your progress was saved.”	The terminal window running setup was closed. Some steps need administrator rights and only that window has them.	Run sudo waired init again (Windows: waired init from an administrator prompt). It resumes; nothing is lost.
“Setup has not been run on … yet, so its coding tools are not connected.”	Nobody has run the setup command on that computer. It is the only thing that can connect coding tools — a web page cannot write into your home folder or change a machine-wide setting.	Run sudo waired init there (Windows: waired init from an administrator prompt). Everything else on that computer can be set up from the browser; this one step cannot.
“Setup has not been run on … yet, so its inference engine is not installed.”	The same thing, one step earlier: nobody has run the setup command, and installing the inference engine needs administrator rights that only that command has.	Run sudo waired init there (Windows: waired init from an administrator prompt). Nothing was interrupted — this is a first run that has not happened yet.
“Setup on … needs administrator access to continue.”	Setup was started without administrator rights.	Start it again from an administrator terminal — see Sign in and set up.
“… has run out of disk space.”	The model did not fit.	Free some space, or pick a smaller model from the catalog.
“… could not finish downloading. Check its internet connection.”	The download failed for a network reason — a name that would not resolve, a connection that dropped, a certificate that would not verify.	Retry. Downloads resume rather than start over.
“The inference engine on … is an older version than this model needs.”	The model needs a newer engine than this computer has.	Update Waired on that computer (waired update), or pick another model from the catalog.
“This took too long on … and was stopped.”	A step exceeded its time limit.	Retry. Twice on the same step usually means this machine is too slow for that model.
“Something went wrong on ….”	Waired could not put a name to what happened — the download was interrupted, or the inference engine could not be started for it to talk to.	Retry. If it keeps happening, run waired doctor on that computer, or read the logs (see Going deeper).

If the coding-tools step is the one that failed, waired link --force all on that computer both repairs it and clears the row — you do not have to run setup again to make the page catch up.

Waired says “check its internet connection” only when the failure really looks like the network. Anything it cannot recognise says so plainly instead of guessing — an interrupted download and an unreachable registry are different problems, and only one of them is fixed by looking at your router.

The model download is the exception to all of the above: it keeps running even if you close the browser tab. Reopen the device at app.waired.ai to see where it got to.

If you are watching from the terminal instead, waired init and waired models pull now print the reason on the line that reports the failure:

qwen3-8b-instruct: failed — no space left on device

An older background service may still report the bare failed with no reason. waired doctor and the logs have it in that case.

Setup says the inference engine failed to start

In the terminal, setup stops waiting for the model and tells you the engine is what went wrong:

The inference engine failed to start, so qwen3.5-4b can't download.
ollama: process exited during startup: signal: killed
Run `waired doctor` for details; `waired status` shows the current state.

The second line is the engine’s own account of what happened, printed exactly as it was recorded — often with the last lines of the engine’s log after it. That is the part worth reading first.

Sign-in itself is finished at this point. The device is on your network and everything except local inference works; the summary at the end says so rather than reporting success. Waired keeps trying in the background, so the download can still start on its own once the engine runs.

If you got here from the one-line installer, it says the same thing under its closing message — the install itself worked, so it still reports that:

🎉 Waired is installed.
✅ Enrolled — the agent service is running.

⚠️  Local inference is not running on this device.
    Sign-in is finished; only local inference is missing.
    Details:      waired doctor

waired init also finishes with exit code 3 for this, so a script can tell it apart from a sign-in that really did not happen:

Exit code	Meaning
0	Signed in, and local inference is running (or was never asked for).
3	Signed in, but local inference is not running on this device.
1	Setup did not finish — sign-in itself failed.
130	You interrupted it with Ctrl-C.

Code 3 is deliberately not 1: the device really is signed in and usable, and re-running sign-in would not change anything about the engine.

If you turned engine installs off yourself — --skip-ollama / -SkipOllama, or WAIRED_NO_OLLAMA in the environment — this is not what you are looking at. That device gets no engine on purpose, and waired init exits 0.

Nor is this what a model that is still downloading looks like. Setup ends on Waired is signed in — local inference is still setting up here and exits 0: nothing failed, the transfer simply outlasted the window setup waits in, and the background service finishes it. Run waired status to watch it.

Nor is it a computer Waired picked no model for. Setup ends on Waired is signed in — no model chosen for this computer and exits 0. The engine is installed and running; what is missing is a model, because none in the catalog fits this hardware well. Nothing is downloading and waired status has no progress to show. Pick one yourself with waired models pull <model>, or from the browser dashboard — waired models ls --detail shows which ones fit and why.

Common causes:

• Another Ollama is already using the port. waired runtimes status names the version it found. Quit it, or set inference.ollama_port in agent.json to a free port.

• Something that is not an Ollama is using that port. Waired cannot adopt it, so the engine simply fails to start, and waired status names the address:

  ⚠ ollama: another program is already listening on 127.0.0.1:9475, the port the
    inference engine was told to use — set inference.ollama_port in agent.json to
    a free port

  Quit whatever holds it, or set inference.ollama_port to a free port and restart the service.

• Something else is already using the vLLM engine’s port. The engine cannot start at all when its port is taken, and waired status names the address:

  ⚠ vllm: another program is already listening on 127.0.0.1:9479, the port the
    inference engine was told to use — set inference.vllm_port in agent.json to
    a free port

  Quit whatever holds it, or set inference.vllm_port to a free port and restart the service.

• The engine keeps crashing. After a few crashes Waired stops restarting it automatically and says so; waired inference engine start retries once you have dealt with the cause. waired status and waired runtimes ls say gave up in place of the engine’s state, which is how you tell it apart from an engine you stopped yourself:

  runtimes:       ollama 0.32.15 (gave up, ctx 32k q8_0)
  ⚠ ollama: engine repeatedly crashed; not retrying — …

• The engine never started at all. The vLLM engine needs its own setup finished before it can run: the Python environment built (waired runtimes install vllm), and a model chosen that ships a version that engine can serve. When one of those is missing there is no engine to crash, so Waired says the engine failed and names which piece is missing rather than waiting for a download that will never begin.

waired doctor checks all of these in one pass, and sudo waired doctor --fix asks the background service to start the engine and prints the reason it is not running.

Setup says it cannot download the model you chose

Some models will not run on some computers. When the background service turns the choice down, the terminal says so straight away instead of waiting to see whether a download starts:

Waired can't download qwen3.6-35b-a3b on this computer.
the engine on this device is too old for this model
Update Waired here (`waired update`), or pick a different model in your browser.

The middle line is the reason as the background service recorded it. The last line depends on that reason, and there are two of them:

• The inference engine is older than the model needs. Run waired update on that computer; the download starts on its own afterwards. This is the only reason an update fixes.
• Anything else — that computer cannot serve the model at all, or downloads are turned off on it. Pick another model in the browser, or run waired models ls --detail to see which ones fit this machine.

Sign-in is finished either way, and the setup page shows the same reason on the model row, so you can pick again there without returning to the terminal.

A similar-looking line means something different:

Waired hasn't started downloading qwen3.6-35b-a3b yet; it keeps trying in the background.

That one is not a refusal. Nothing has gone wrong that Waired knows about — the download simply had not begun by the time the terminal stopped watching, and it carries on in the background. waired status shows where it got to.

It says I have reached the device limit

Each account can enroll a generous number of devices, and the usual cause is old machines you no longer use still being counted.

Open app.waired.ai, remove a device you no longer need, then set up again.

Re-running setup on a machine that is already signed in never counts against the limit.

It says the device is “enrolled system-wide”

That is not an error. The device’s identity is stored in a system folder only administrators can read, so waired status run as a regular user cannot see it — rather than guess, it tells you the device is enrolled and exits successfully.

To see the full status, run it with administrator rights:

sudo waired status          # Windows: from an administrator prompt

waired doctor says the same thing on such a machine, in its own state directory line, and treats it as a check it could not run rather than a failure — see When the check itself cannot see everything.

If instead you see Not enrolled. Run 'waired init' to connect this device., this machine really has not been set up yet — see Sign in and set up.

Waired chose a very small model for my machine

That is the largest one this computer can hold while keeping a full coding session in memory, and Waired runs it. A model that fits but has to throw away most of a long conversation is not the better choice.

Waired used to refuse instead: if the best model your machine could hold was one it judged too weak for coding work, it started with local inference off and you got nothing. It no longer does that. The one thing that still starts local AI off is speed — see Local inference started off and I did not choose that.

To see what you got and why:

waired models ls --detail

The SIZE column says which class of GPU a model is for, and FIT says whether this computer can hold it. Anything in the list is yours to choose:

waired models use <model>

A bigger model will run — it just spends the conversation reloading itself from system RAM, which is slow in a way you feel most on long coding sessions. waired inference off stops running models here entirely; the machine stays in your network and can use the models on your other computers.

Local inference started off and I did not choose that

Ask the computer why:

waired inference status

When Waired is the one that decided, the answer says so:

Local inference: off
  This computer is below the recommended spec for local inference.
  per request           210.4 s or more
  target                45 s or less
  It can still use the models running on your other computers.
  Turn it on with `waired inference on`.

Where that number comes from. As soon as the inference engine is installed — and before anything downloads a full-size model, tens of gigabytes — Waired downloads a small one, about a gigabyte, and times a realistic request on it: a long question, a full-length answer. It times it three times and takes the middle result, so one busy moment cannot decide the outcome. That takes a few seconds on a fast machine and a couple of minutes on a slow one, and it happens whether you set the computer up from the terminal or from the browser.

On a computer that is a long way under the mark, Waired stops sooner than that. The opening part of the very first timing is already enough to show the answer would take far too long, so it says 210.4 s or more instead of an exact number and does not spend the minutes a full timing would cost — minutes your model download would otherwise be waiting through.

The figure is measured once per install. Starting the service again reuses it; updating Waired or its inference engine measures the machine again, because how fast a new build runs is a new fact about your computer.

Why a smaller model would not rescue it. On a computer with no graphics card, the smallest coding model in the catalog is not much faster than the largest one that fits — minutes per question either way. That is the machine talking, not the model, which is why Waired stops rather than picking something smaller.

It is a starting point, not a verdict. The computer still joins your network and can use the models running on your other computers. Turn local inference on whenever you want:

waired inference on

In the Waired app the same choice is Run models on this computer. Once you have made that choice, Waired keeps it — the timing runs to pick a starting point, and never again to overrule you.

If waired inference status reports off and gives no reason, nothing on this computer decided it: it was chosen here — during setup, with the installer’s --inference-enabled false, or with waired inference off.

It says local inference is not set up yet

waired inference status

Local inference: not set up yet — this device is not signed in. Run `waired init`.

This is the state between installing Waired and signing in. Nothing is wrong and there is no setting to change: the computer has no account to run models for yet. Sign in and the answer becomes on or off.

Older versions answered this state with “unknown (this daemon does not report it — waired update)”, which sent people to an update command that then reported the computer was already up to date. If you see that wording, the computer is running an older build; waired update is harmless, and signing in is what actually moves it forward.

Setup said it could not complete a test generation

At the end of setup Waired asks the AI a short question to check the speed of this machine. This message means the question was asked and no answer came back — so setup could not measure anything, and it will not pretend the AI is working.

Almost always the inference engine itself stopped. Check it:

waired status
waired doctor

waired status shows the engine’s own reason on the line for the engine. If it crashed, the detail is in its log — see Going deeper (logs).

The rest of Waired is unaffected: your device stays signed in, and it can still use the models running on your other computers. Once the engine is healthy, measure again with:

waired runtimes benchmark

I signed in, but Waired says I am signed out

The Waired icon shows “Not signed in”, or the computer is missing from your account — most often right after a restart, even though you never signed out.

Two different things look the same from the outside. waired doctor tells them apart:

waired doctor

network connection is a ⚠ — you are signed in and this computer simply has not connected yet. Waired keeps retrying by itself, including after a restart where the network port it normally uses was taken by something else, so give it a minute and check again. If it never clears, restart the background service:

sudo systemctl restart waired-agent    # Linux
Restart-Service waired-agent           # Windows (administrator)

device sign-in is a ✗ — this computer’s sign-in really has stopped working and only signing in again restores it:

sudo waired init      # Linux / macOS
waired init           # Windows (administrator)

Your models, settings and coding-tool setup all survive this — it re-establishes this computer’s place in your account and nothing else. Local inference keeps answering throughout; what stops is everything that needs your account, so the computer disappears from the web console and your other devices cannot reach it until you sign in again.

No answer comes back

Check what the engine is doing:

waired status --observability

The Engine line is the one that matters.

• ready — the model is loaded. If requests still fail, the problem is routing: see Claude Code is still using the cloud.

• not ready — usually the model is still downloading. waired models ls shows progress; a first model is several gigabytes.

• not ready after the download finished — the model probably does not fit this computer’s memory. Switch to a smaller one: Choose which model runs.

• engine failed — the inference engine stopped on its own. Waired restarts it for you (up to three times), so this usually clears within a minute; the reason it stopped is shown on the same line. If it keeps happening, Waired stops restarting and says so — fix what the reason points at, then start it again:

  waired inference engine start

  A model that is too large for this computer is the usual cause; the engine’s own log has the detail (see Going deeper). While the engine is down this computer stops offering the AI to your other machines, so they fail over instead of waiting on it.

Two more causes worth knowing:

• The AI has to be put into memory before it can answer, and the first request after the engine starts is the one that waits for it. How long depends on the model and the computer, so Waired does not guess — it tells you what is true right now (below).
• A 503 means routing is paused (waired resume) or sharing is off (waired share on).

Is it working, or is it stuck?

waired status answers both halves:

  model loaded:   ollama: no (the next request reloads it)
  serving now:    0 requests

• model loaded: — whether the AI is in memory. no means the next request puts it there first, and that request is the slow one. If it names a model followed by not the model this computer serves, something else took the memory and your model has to be loaded again.
• serving now: — how many requests this computer is working on. This is the line that separates the two cases people confuse: a coding tool that has said nothing for a while plus 0 requests means the wait is not on this computer at all — look at routing, not at the AI.
• last turn: — how long the last answer took to start. It appears once this computer has answered something.

Claude Code shows the same thing in its footer while it works: ⚡ waired: on Waired (qwen3-8b-instruct) · model not loaded.

Waired does not sit silent while it loads. When this computer is the one answering, the connection is held open until the answer starts, however long the load takes, and Waired keeps it alive meanwhile; there is no timeout after which the turn goes somewhere else. If the footer says ⚠ waired: Waired cannot answer (…) instead of the line above, nothing of yours can take the turn at all — see Claude Code says Waired cannot answer.

Still stuck? waired runtimes status reports on the engine itself, and Going deeper has the logs.

Claude Code is still using the cloud

waired doctor          # press f to repair what it finds
waired claude status

First read the footer. → waired: Anthropic means this session is on an Anthropic model — and a session you have not touched is, because Claude Code’s own default is one and Waired does not change it. That is the ordinary state after setup, not a fault. Type /model and pick a Waired entry; the next turn runs on your own computers and the footer changes to ⚡ waired: on Waired.

If the Waired entries are not in /model, see The Waired entries are missing from /model. If waired claude status says the integration is not enabled, enable it and restart your Claude Code session:

sudo waired claude enable     # Windows: from an administrator prompt

waired doctor rebuilds the connection between Claude Code and Waired when it is broken. waired claude status shows which model new sessions start on (default model:) and what the last turn did:

last request:       claude-opus-5 → the real Anthropic API   (2 minutes ago)

A turn goes to the cloud only when its model is an Anthropic one. Waired does not send a turn there on its own, so last request: naming the real Anthropic API always means the session’s model did.

Claude Code says Waired cannot answer

A turn on a Waired entry that none of your computers can serve fails at once, inside Claude Code, with API Error: 400 and a message that names what could not answer. It is not sent to the Anthropic API. Every one of these messages ends the same way — Pick an Anthropic model in /model to send this turn to the cloud, or run `waired doctor` to see what is missing. — and those are the two ways out: switch that session to the cloud, or fix what is missing and send again. The start of the message says which fix applies:

The message starts	What it means	What to do
Waired is not set up to answer on this computer, so this turn has nowhere to run.	No engine here, and no other computer of yours is reachable.	waired doctor on this computer; start an engine here, or switch on a computer that runs one.
Pinned peer is unreachable: "<name>".	You pinned that computer with waired worker and it is off, asleep or not sharing.	See Requests stopped working after I pinned a computer.
The peer <name> stopped answering after <time>. / The peer <name> stopped working on this request after <time>.	That computer was answering and went quiet, or reported that it had stopped.	Check it with waired peers list, and waired doctor on that computer.
No computer on Waired runs a medium model or larger. Change the floor with `waired worker set --min-model-size`.	Your own routing floor excluded every computer, this one included.	Lower or clear the floor: --min-model-size.

The footer usually says it first. ⚠ waired: Waired cannot answer (local disabled, no peer) in red means Waired already knows nothing of yours can take the next turn; the brackets give the state of this computer’s engine (local disabled, local no_engine, …) and no peer when no other computer is reachable.

The Waired icon says the agent is not running

Open the Waired menu and choose Start the Waired agent…. Your computer asks for administrator access — that is the operating system’s own prompt, and it is required because the background service belongs to the whole computer, not to one account. If you would rather run it yourself, Copy start command puts the right command for this computer on your clipboard.

Two things this menu tells you apart:

• “Waired agent is starting…” — normal. On Windows the service is set to start a couple of minutes after you sign in, so the Waired icon is up before it is. Nothing is wrong; you can wait, or start it now.
• “Waired agent is not running” — it should be up and is not. Start it from the menu, and if it does not come back, run waired doctor.

Stopping the service by hand does not stick: it starts again with the computer.

A command says “waired-agent is not running”

The background service has stopped.

sudo systemctl restart waired-agent    # Linux
Restart-Service waired-agent           # Windows (administrator)

On macOS the system restarts it for you; if it does not come back, run waired doctor or restart the computer — and if it has never started, see the next section.

A restart also clears most temporary inconsistencies, so it is worth trying before anything more involved.

Windows: it stopped starting at boot on its own

Windows can block Waired’s background service at startup, because Waired’s programs are not yet signed with a certificate Windows recognises. When Smart App Control is switched on it decides at boot, without a network check to fall back on, and the service does not start. It is not consistent: the same computer may start normally on the next boot.

Until Waired ships signed programs, start the service from the Waired menu when this happens — nothing is damaged, and manually starting the same service works.

macOS: the background service never starts

The installer finished, but the service never comes up — and reinstalling, even with --clean, changes nothing. That combination usually means macOS has the service marked as disabled. A Waired version that was installed and then removed between 15 July 2026 and this release left that mark behind, and it survives uninstalling, reinstalling and restarting the computer.

Check for it:

sudo launchctl print-disabled system | grep waired

"com.waired.agent" => true means it is disabled. Clear the mark and start the service:

sudo launchctl enable system/com.waired.agent
sudo launchctl bootstrap system /Library/LaunchDaemons/com.waired.agent.plist

Installing or updating Waired now clears this for you, so you should only need these commands on a machine where the installer itself cannot be run.

Windows: I get a 502 error

The inference engine is not installed on this computer — usually because it was installed with -SkipOllama or WAIRED_NO_OLLAMA=1.

From an administrator prompt:

waired runtimes install ollama

Answers are very slow

waired runtimes benchmark

This measures what this computer actually does. If it comes out below what a coding assistant needs, Waired offers a lighter model — accepting is usually right.

Other things worth checking:

• Is your GPU being used? See My GPU is not being used.
• Is the model too big for your memory? An over-sized model runs partly on the processor, which is dramatically slower. waired models ls --detail shows the fit.
• On an AMD Ryzen AI Max machine, how much memory is reserved for graphics? Reserving a lot makes things worse, not better — see Windows: giving the graphics chip more memory made things worse.
• Is the answer coming from another computer? waired infer --explain "hi" names the machine that served it, and the estimated latency.
• Is it the first turn of a Claude Code session? That one is the expensive one — the whole conversation, your instructions and the file contents have to be read before any word comes back, and on a laptop or an older graphics card that can be several minutes. Waired waits it out rather than giving up on a computer that is working; later turns in the same session are far quicker. See Which AI answered?.

My GPU is not being used

First, see what Waired found:

waired models ls --detail

The first line names your card and its memory. If it says no GPU on a computer that has one, the card was never detected — and everything after that, including which model you were given, was sized for the processor.

Waired handles the common cases automatically: integrated AMD and Intel graphics are enabled through Vulkan (recent Ollama versions disable them by default and fall back to the processor silently), and discrete AMD cards use ROCm where it is supported, falling back to Vulkan when it does not engage.

NVIDIA cards are found through the driver itself, not by looking for nvidia-smi on your PATH — the background service does not inherit the PATH from your terminal, so a card is still found when the tool is not on it. If your card is genuinely not showing up, point Waired straight at the tool and restart the service:

On Linux, sudo systemctl edit waired-agent and add:

[Service]
Environment=WAIRED_NVIDIA_SMI=/usr/bin/nvidia-smi

On Windows, in an administrator PowerShell:

[Environment]::SetEnvironmentVariable(
  'WAIRED_NVIDIA_SMI', 'C:\Windows\System32\nvidia-smi.exe', 'Machine')

Then restart the service (see “waired-agent is not running”) and run waired models ls --detail again. On Windows a full reboot is the surest way to make the service pick up a new machine-wide variable.

Also confirm the model actually fits — memory requirements are in the model catalog.

I chose a model bigger than my hardware

Waired warns but does not block you. When you pick an over-sized model it shows the shortfall (needs 32 GB RAM (have 31 GB)) and asks you to confirm.

• Slightly over — it usually runs, just slower.
• Genuinely too big — the engine fails to load it and reports a clear error. Switch back down: Choose which model runs.

The recommended figures carry a safety margin. On Apple Silicon and AMD Strix Halo the fit is judged against the memory the graphics side can actually address; on a computer with a separate GPU, what Waired picks for you is judged against the card’s own memory — so a model that only fits by spilling into system RAM is one you have to choose deliberately. waired models ls --detail shows the verdict for every model on this machine.

It says the GPU ran out of memory on a long prompt

You find this out while using the computer, not during setup. A turn fails partway through a long conversation, and after that the model’s row in waired models ls --detail reads ! running here with a warning, with the engine’s own sentence printed under the table. That sentence starts this computer's GPU ran out of memory serving a request at this model and window, and the engine’s own words follow in parentheses.

This is not the same as “slow”. Short prompts work; the computer runs out of VRAM once the conversation gets long, and a coding session gets long quickly.

Waired does not change anything on its own. The engine keeps serving — the next short request works — and Waired keeps the warning where you will see it:

• waired models ls --detail marks the model ! running here with a warning and prints the engine’s own sentence underneath.
• waired status repeats it.
• waired doctor repeats it with the rest of this computer’s state.

The model is too big for this computer at the length you need. Switch to a lighter model: Choose which model runs.

Waired does not offer you a lighter model automatically in this case, on purpose. That suggestion is for a computer that measured slow. Running out of memory is a different problem — a smaller model at the same conversation length is not obviously the fix, and being told to give up a model that works would be the wrong advice.

Windows: giving the graphics chip more memory made things worse

On an AMD Ryzen AI Max (“Strix Halo”) machine the graphics side and the processor share one pool of memory, and a setting decides how much of that pool is handed to the graphics side up front. Turning it up looks like the way to run a bigger model. It does the opposite.

Windows reserves a matching amount of system RAM behind every graphics allocation — that is how it can move things out of the way when it needs the space. So a model needs room on the graphics side and the same amount again in the memory Windows still sees. Hand 96 GB of a 128 GB machine to the graphics side and Windows is left with about 31 GB, and 31 GB is then the real limit on model size. A larger model starts loading, runs out, and pages to disk for tens of minutes without ever answering.

Measured on a 128 GB Ryzen AI Max+ 395 with one 76 GB model, changing nothing but this setting:

Graphics memory reserved	What happened
96 GB	never finished loading — 28 minutes, no answer
512 MB	loaded in 15 seconds, then ran at full speed

Reserving less costs nothing. The graphics side reaches the rest of the memory anyway, and on this kind of machine it is the same physical memory at the same speed either way.

So set it low. In the BIOS, leave the VRAM size on Auto — it is usually called UMA Frame Buffer Size. Then, in AMD Software: Adrenalin Edition, open Performance → Tuning → System → Variable Graphics Memory and choose the smallest option. Restart, and check what Waired sees now:

waired models ls --detail

The first line should report a much larger figure than before. If it still shows the small leftover, the BIOS is fixing the split itself rather than leaving it to the driver — set it back to Auto there.

A model says it needs a newer inference engine

Some models only run on a recent build of the inference engine, and the row says so:

qwen3.8-27b   27B   medium   ✗ needs Ollama 0.32.13 (this computer has 0.31.1)

This is not about memory — the model may well fit here. The engine on this computer is simply older than the model needs, and until it moves the model cannot be downloaded or loaded.

Waired manages the engine for you, so the fix is the ordinary update:

waired update

The update brings the engine to the version this build of Waired ships with, and the row clears on its own afterwards. Until it does, Waired keeps choosing a model the current engine can run, so local inference keeps working.

The row can end two other ways, and each names its own case:

• (this computer's version could not be read) — the engine is here but has never been started, so there was nothing to ask. Start it and look again:

  waired inference engine start

• (no inference engine on this computer) — there is no engine here at all. See This computer has no inference engine below.

This computer has no inference engine

Some computers never get one: Waired only installs the engine when you said this computer should run models itself. waired models ls --detail says so above the table:

Host: Intel Arc 8 GB VRAM / 63 GB RAM · no inference engine installed

! No inference engine is installed on this computer, so it cannot run a model itself.
  Requests go to your other computers instead.
  Install one with `sudo waired runtimes install ollama`.
  The verdicts below are what this computer would run once an engine is installed.

This is normal, not a fault. The computer stays signed in and keeps working: your requests are answered by the other computers in your Waired network. The model rows below that block still make sense — they say what would run here.

Two things to know:

• Picking a model in the tray offers to install the engine. Choosing one on a computer with no engine cannot do anything on its own, so Waired asks first and installs the engine before recording your choice.

• You can install one at any time. It needs administrator rights, because the engine goes somewhere an ordinary user cannot write:

  sudo waired runtimes install ollama

  On Windows the same line reads Install one with `waired runtimes install ollama`, from an elevated prompt. — there is no sudo to put in the command, so the elevation is said beside it.

If you expected an engine here, the likeliest reason is that sign-in was answered with “do not run models on this computer”. Re-run sudo waired init to answer it again.

The Waired entries are missing from /model

/model should offer Waired — 200k, Waired local and Waired peer below the Anthropic names, and Waired public share once Public Share is on. Four things hide them, in the order worth checking:

1. Claude Code has not been restarted. The list is read once at startup — re-opening /model in a running session does not re-read it. Quit Claude Code and start it again.

2. Routing is not on for this computer. Check with waired claude status; the entries are only offered once Claude Code is pointed at Waired.

   sudo waired claude enable    # Windows: from an administrator prompt

3. The entries were written for a different user. They live in your home folder, so an install that set Waired up as root leaves them where your Claude Code will never look. waired claude status now says which file it checked and what it found:

   /model picker:      not written — /home/you/.claude/cache/gateway-models.json
                       run `waired claude enable` as the user who runs `claude`

   The same line reports the other version of this: a file that is there but points at a different address than Claude Code is using, which Claude Code ignores entirely and silently.

4. CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC is set. Any value hides the entries, even when everything else is correct. Unset it and restart Claude Code.

Running Claude Code inside WSL2 while Waired is installed on Windows is a separate case: they are two different systems, so use the Windows-side Claude Code.

Until the entries are back there is nothing to pick, so a session on Claude Code’s own default stays on the real Anthropic API — the status line says → waired: Anthropic, so you can see it.

Long Claude Code sessions get summarized

This is expected and healthy. Local models hold less of a conversation at once than cloud models do, so Waired tells Claude Code the real limit and Claude Code summarizes older turns to fit — the session keeps working instead of silently losing its beginning.

If you briefly see “prompt is too long”, Claude Code retries on its own.

Summarizing much earlier or later than you expect? The limit is passed to Claude Code when you connect it, so it can fall behind after you switch models:

waired claude status

The local window line shows the limit your model handles now next to the one Claude Code was started with. If it says they disagree, re-run sudo waired claude enable (Windows: from an administrator prompt), then restart Claude Code.

Want the larger window for a while? Pick the model you want in /model — an Anthropic model there sends the session to the real Anthropic API, and its full window applies from your next message.

My other computer cannot reach the AI

waired status --observability

The Mesh line reads enrolled / reachable / ready. If reachable is 0:

1. Are both computers signed in with the same Google account? By far the most common cause. Compare the account line from waired status on each.
2. Is the other computer awake, with Waired running? Run waired doctor there.
3. Is it sharing? A computer only answers other devices when its own sharing switch is on — waired share status shows it, waired share on turns it on — and the web console’s Sharing card offers it to Your other computers.

If it is reachable but never ready, it has no model loaded — work through No answer comes back on that machine.

If everything looks reachable and requests still do not arrive, run waired doctor. Its mesh peers line does not take the network’s word for it — it sends a real request to each computer and reports what came back:

⚠ mesh peers — 2/3 reported reachable, but only 0 answered an overlay ping —
  no reply from mac-mini, work-laptop. Inference cannot route to a peer that
  does not answer; check NAT traversal and relay connectivity

That line means the two computers are listed as connected but nothing actually gets through to them. Work through the three checks above on the named machines. A count marked (measured) has been confirmed the same way.

You should not need to open ports or configure a VPN. Your computers connect directly when the network allows it, and fall back to an encrypted relay when a firewall gets in the way, automatically.

Requests stopped working after I pinned a computer

waired worker get

Pinning is a firm instruction: use that computer, and no other. So when the pinned computer is asleep, offline or not sharing, Waired does not quietly run the work somewhere else — you get an error instead. That is deliberate. Silently answering from a different machine would mean a request you sent to your big GPU box was really handled by the laptop in front of you, with no sign of it.

The Waired icon says the same thing: Worker: <name> (pinned) — unavailable, requests are not served here.

Claude Code gets the same answer. The turn fails at once and names the computer — it is not sent to the Anthropic API:

API Error: 400 Pinned peer is unreachable: "sv-mag". Pick an Anthropic model in /model to send this turn to the cloud, or run `waired doctor` to see what is missing.

If you want that turn in the cloud after all, pick an Anthropic model in /model — see Claude Code.

To fix it, either wake the pinned computer (check it with waired peers list and waired doctor on that machine — see My other computer cannot reach the AI), or stop pinning:

waired worker set --mode=auto

The Waired icon is missing (Linux)

GNOME does not show icons next to the clock on its own — the Waired icon needs the AppIndicator extension. Setup installs one when it finds GNOME on the computer, and Waired checks again each time you sign in — an extension that is present but switched off is switched back on for you.

If the icon is still missing, this fixes it:

waired doctor --fix

It reports what is wrong, asks before changing anything, and installs or switches on the extension as needed.

To do the same 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.

KDE Plasma needs nothing. MATE cannot show the icon at all.

The status line does not show up in Claude Code

Run waired claude status inside the project directory.

Claude Code allows one status line, and a project-level setting (.claude/settings.json or .claude/settings.local.json) overrides the one Waired installs for your user. When that happens the command names the file that is winning, and prints a line you can add to your own status-line script.

Also make sure you restarted the Claude Code session after enabling the integration.

---

Going deeper (logs)

Only after waired doctor:

Linux	journalctl -u waired-agent -e
macOS	/Library/Logs/waired-agent.err.log, or sudo log show --predicate 'process == "waired-agent"' --last 10m. Waired caps that file at 32 MB and keeps ten previous ones beside it as waired-agent.err.log.0.gz, .1.gz and so on — look there for anything older (gzcat). At debug the cap rises to 128 MB, so turning the detail up does not shorten how far back you can look.
Windows	logs\waired-agent.log under Waired’s state folder — C:\ProgramData\waired\logs\… for the usual service install, which takes an elevated PowerShell to read. Same caps as macOS: 32 MB and ten .0.gz, .1.gz … copies, rising to 128 MB at debug. Get-WinEvent -ProviderName waired-agent -LogName Application -MaxEvents 50 is the short version: it carries warnings and errors, not the detail.
The inference engine	…/runtimes/ollama/logs/engine.log under Waired’s state folder — /var/lib/waired/… on Linux, /Library/Application Support/waired/… on macOS, C:\ProgramData\waired\… on Windows.

Reporting a problem

Follow Report a problem: turn on detailed logs before reproducing it, collect them into one file, and attach that. Doing it in that order matters — the detail that explains a bug is not written down unless you ask for it first.

waired init --mask-pii (or WAIRED_PII_MASK=1 on other commands) masks your home directory, username, hostname and account email in the output, so a transcript or screenshot is safe to attach to an issue.