Known issues & connectivity
Current known issues with workarounds, and a step-by-step guide for when a device can't connect to your Neumann daemon.
Current known issues
Issues we know about, what you'll see, and what to do meanwhile. Last reviewed September 2026.
| Symptom | Affects | Workaround |
|---|---|---|
A session started with neumann run sometimes doesn't show in neumann ls for a moment. | CLI, local daemon | Run neumann ls again after a second, or open it by id with neumann attach <id>. |
curl …/install.sh | sh says there's no CLI build for your platform. | Linux, Intel macOS | Prebuilt CLI binaries are rolling out per platform. Use the desktop app, or build from source (see the install docs). |
| After a desktop update the window shows the previous version's UI. | macOS desktop ≤ 0.1.39 | Fixed in 0.1.40+. On older builds quit fully (⌘Q) and relaunch. |
| The composer shows no usage meter for Claude Code / Codex. | All | Per-provider rate windows come from CodexBar's local snapshot; install it, or check usage in Settings → Providers. |
| A warning says the CLI or web UI version differs from the daemon. | Remote / always-on hosts | Upgrade the older side. For a service install, upgrade the binary then restart the service. |
| Phone notifications only arrive for “Needs you” and “Done”. | Mobile companion | By design — open the Agents dashboard for Working / Blocked states. |
On Linux, credentials are stored in private files under ~/.neumann/credentials rather than the desktop keyring. This is intentional; keep that directory private.
1. Run neumann doctor
Most connection problems show up in one command. It makes no model or cloud calls and every warning comes with a fix.
neumann doctor
neumann doctor --host my-server # a remote daemonExit code 3 means the daemon could not be reached; 1 means a check failed. Fix the ✗ lines first, then the ! lines.
2. Is the daemon running?
curl -s http://127.0.0.1:8421/api/health/live
curl -s http://127.0.0.1:8421/api/health/ready| Result | What it means | Do this |
|---|---|---|
| Connection refused | Nothing is listening | Start neumann daemon, or check the service: systemctl --user status neumann-daemon (Linux) / launchctl list | grep neumann (macOS). |
ready → degraded | Serving, something is off | Read the check with a warning — usually the web UI build or git missing. |
ready → HTTP 503 | Not ready | The engine or datadir check failed; follow its remediation, then restart. |
3. Can another device reach it?
- 1It must listen on the network
neumann daemonbinds 0.0.0.0:8421 by default;neumann uiand the desktop app bind loopback only. - 2Allow the port
macOS: accept the firewall prompt (System Settings → Network → Firewall). Linux:
sudo ufw allow 8421/tcpor your cloud security group. - 3Same network or a VPN
Both devices on the same LAN, or both on the same Tailscale / WireGuard network.
- 4Hostnames need allowing
Using a name like
mini.localor a Tailscale name and getting HTTP 403 “forbidden host”? Add it:NEUMANN_ALLOWED_HOSTS=mini.local,*.ts.netin the daemon's environment, then restart.
Pairing controls who can connect; it doesn't encrypt traffic. Over untrusted networks use a VPN, an SSH tunnel, or neumann daemon --relay.
4. Pairing fails
| Symptom | Fix |
|---|---|
| “check the code” / HTTP 401 | Pairing codes change every time the daemon starts. Get the current one from its log: journalctl --user -u neumann-daemon | grep -E 'auth.token=|pairing code'. |
| A phone that used to work is refused | It may have been revoked in Settings → Mobile devices. Pair it again. |
| “protocol version mismatch” | Client and daemon speak different protocol versions. Upgrade the side the message names. |
5. The page is blank
If /api/health/ready reports web_ui: warn, the daemon has no web UI build to serve. The CLI and phone still work; for the browser UI install with the one-line installer (it bundles the UI) or build it and set NEUMANN_WEB_DIST_DIR.