Troubleshooting

Start with nanomuse doctor: it prints the config file in use, the data directory, the model and endpoint (and whether a key is set), the tools and connectors, and makes one call to the model. Most of the problems below show up there first.

The phone cannot open the URL. Start with --host 0.0.0.0 (the default binds to localhost only), make sure both devices are on the same network, and allow the port through the machine's firewall. The URL shown uses the LAN address the server could detect; if it is wrong, use the machine's address from ip addr / ipconfig with the same #token= part (the token rides in the link's fragment, never in a query string — a ?token= link from before 0.1.31 is refused with a message saying so).

"web app not built" on start. You are running from a checkout without the built front-end. cd web && npm install && npm run build, or install the package instead.

Replies come back in the wrong language. With agent.language = "auto" the system prompt names the language of your latest message (detected by script). If a model still drifts, set a fixed language in You → Reply language or agent.language = "English".

The beginning of a streamed reply is missing. Some proxies that inline <think>…</think> into the content drop the first tokens after </think> on the server side. Non-streaming responses are complete; set stream = false under [llm].

The model never calls tools. The endpoint probably ignores the tools field without an error (an endpoint that rejects it is handled by the default tool_mode = "auto"). Set tool_mode = "prompt"; tools are then described in the system prompt and parsed from <tool_call> blocks.

"does not support tools" in the log, then the agent carries on. That is auto doing its job: Ollama refused function calling for this model, so tools are described in the prompt from then on. Pick a model with a tool template (qwen3:8b, llama3.1:8b) for better results on long tasks.

Empty replies, or Ideas that stay on the starter list, with a reasoning model. DeepSeek's thinking variants and the OpenAI o-series count their reasoning against max_tokens; on a hard prompt they can spend the whole budget thinking and return nothing (finish_reason = "length"). nanoMuse asks once more with four times the budget when that happens. If it keeps happening, raise max_tokens under [llm] (16384 is a sensible value for these models).

429 / rate limits. Requests retry with exponential back-off (max_retries, default 5). Lower agent.max_steps, or add web_fetch to always_ask_tools to slow the loop down.

An approval card never appears in the terminal. nanomuse daemon and --auto run in Sentinel auto mode by design. Use nanomuse chat or the app for interactive approvals.

"Sentinel blocked" for something you wanted. Check nanomuse audit -n 20 for the reason: a deny rule, deny_tools, or taint (private data read earlier in the session plus a new network destination). Add the host to egress_allowlist or approve once.

Email tool returns nothing useful. With scrub_secrets = true one-time codes and reset links are removed before the model reads a mail; that is intentional. Check IMAP settings with nanomuse config show and the vault entries with nanomuse vault list.

Playwright fails to install Chromium. Older distributions are not supported by recent Playwright builds. Use the Docker image or leave browser.enabled = false; web_fetch covers most reading tasks.

The desktop app shows "nanoMuse could not start", or a blank window. The shell starts nanomuse serve on 127.0.0.1:8787 and reads its log at ~/.nanomuse/desktop-app.log (NANOMUSE_HOME if you set it); the dialog quotes the last lines and names the usual causes — the port taken by another program or another nanoMuse (NANOMUSE_PORT picks a different one), a data folder that is not writable, a config.toml that does not parse. If the runtime stops later, the shell restarts it once and asks before trying again; Open the log in that dialog and the tray's Open the log folder lead to the same file. Updates are not installed on their own: the tray's Check for updates looks at GitHub Releases.

"The data folder … is not writable" / "cannot write to the data directory" right after installing (Windows, 0.1.20–0.1.21). The runtime created its workspace folder relative to wherever the launcher started it — C:\Windows\System32 when the installer opened the app — and stopped when that failed. Since 0.1.22 the workspace defaults to <data dir>\workspace and the shell starts the runtime inside its data folder; update, or set NANOMUSE_WORKSPACE for an older version.

macOS: Finder "can't complete the operation … error code -36" while dragging nanoMuse.app out of the dmg (0.1.20–0.1.21). The image was HFS+; since 0.1.22 the dmg is APFS and the release also carries a .zip of the app — download it, double-click to unpack, drag nanoMuse.app to Applications.

macOS: "nanoMuse.app is damaged and can't be opened" or "Apple could not verify…". Builds made without an Apple developer certificate are ad-hoc signed, so macOS asks once (a release signed and notarized with the project's Developer ID — desktop/app/README.md says when that is — opens without the question). Open it, dismiss the dialog, then System Settings → Privacy & Security → Open Anyway (or, from a terminal, xattr -dr com.apple.quarantine /Applications/nanoMuse.app). Windows shows "Windows protected your PC" for the same reason: More info → Run anyway.

Linux: the hands look but do not act — clicks land nowhere, or typed * comes out as 8 (0.1.37). Two X11 bugs fixed in 0.1.38. The glow the app draws around the screen while the hands work is an X window whose click-through shape X11 forgets each time it maps, so the clicks of 0.1.37 went into the glow itself (and a type could end up in the app's own composer); and libnut dropped Shift for the symbols of the US layout. Update (0.1.37 has no workaround). Still off after the update: check ~/.nanomuse/desktop/desktop.log for operator: available · display W×H (scale N) — not available (Wayland session …) means a Wayland login (choose Ubuntu on Xorg on the login screen; the hands cannot work under Wayland and say so in Settings → Computer use's Take a test shot and in the chat). display is the X root in pixels; a click the app says it made at x,y can be checked with DISPLAY=:0 xdotool getmouselocation. A picture that is all black usually means no window manager is running (Electron's capturer needs one; the runtime then uses its own capture). A click that lands a few pixels beside a small button (the gap between two calculator keys) is the chat model's aim, not the hands: the pointer goes exactly where the model said (the log line and getmouselocation agree). Larger targets, keyboard shortcuts and typing are the reliable way through such screens (the agent itself switched to typing 12*34 + Enter when its key clicks missed).

The Android app says "Refused by the relay — sign in again" under Devices. The relay no longer accepts this phone's key (signed out everywhere, or the account was deleted). Sign out and in again on the Account screen; the hub joins again on its own.

Reset everything. Stop the server and delete ~/.nanomuse (or your data_dir). The vault key lives there too, so export secrets first if you need them.