Troubleshooting

This is the ordinary outcome of pip install, whose WARNING: The scripts ... are installed in '...' which is not on PATH scrolls past unread. pip installs into whichever environment is currently active and puts nothing on PATH globally.

# The daemon, needing no PATH setup at all: `python -m swe_mux` is exactly `muxd`.
python -m swe_mux

# Where the three executables actually went.
python -c "import sysconfig; print(sysconfig.get_path('scripts'))"

# Or ask swe-mux itself.
muxd --where

uv tool install swe-mux and pipx install swe-mux both put all three on PATH globally, and are the recommended forms for that reason.

There never will be from a Python install. Wheels have no post-install hook and pip runs no install-time code, so this is structural rather than a step somebody forgot. On Windows, mux install-shortcut creates them afterwards, and --remove takes them away again.

This is the most confusing first-run symptom in the project, and it is not a bug. The frontend bundle is build output and is not carried in the repository, so a fresh clone, a fresh worktree, and a CI checkout all have none: the daemon answers the API perfectly and serves no interface.

npm --prefix frontend ci
npm --prefix frontend run build

mux doctor distinguishes the two cases that look identical from the browser. In a source checkout the missing bundle is a warning carrying exactly that command. In an installed copy it is a failure, because a wheel that shipped without an interface is a broken artifact, and reinstalling from a complete one is the fix.

Run mux doctor. With nothing listening it produces the local report, and the first FAIL is the one to fix. Four causes account for most of them:

• A config that does not validateThe config check fails with the real parse or validation error. Fix config.toml, or move it aside - a removed config is rewritten with defaults on the next start. This is the fault the CLI otherwise hides, because a config failure makes every mux command fall back to the loopback default and possibly point at the wrong daemon.
• The port is already heldThe port check fails and names the owner-finding command for your host (netstat -ano | findstr :<port> on Windows, ss -ltnp on Linux). Stop the owner, or set a different port.
• A broken installThe import check fails with the real exception attached. On Windows the specific risk is the one compiled dependency in the runtime closure, where a wheel mismatch or a missing Visual C++ runtime surfaces as an import error.
• An unwritable or missing data directoryThe check distinguishes "exists and cannot be written" from "does not exist and cannot be created", and points at MUX_DATA_DIR.

A bound listener is not a ready daemon. Health answers 503 with the startup phase still in flight until the runtime exists, so "it is listening but everything 503s" is the daemon still starting rather than a fault. muxd --local-only takes tailnet detection out of the startup path when you are isolating a network problem.

Which mechanism applies decides what you can get back, and there are two:

• The PTY supervisor, and it ships offWith it on, terminals are held by a separate process and survive a daemon restart, an app rebuild, and a redeploy. With it off, a restart reaps every session - which is why the restart endpoint refuses outright unless it is forced. Turn it on in Settings, Terminals.
• Cold recovery, which ships onIndependent of the supervisor, and it covers what the supervisor cannot: sessions whose daemon and terminal owner both died. They come back as visible, dead, resumable rows rather than vanishing.

Check the state before concluding anything. mux doctor against a running daemon reports supervisor attachment, and mux doctor --export lists cold sessions with their reason and capture state.

mux harnesses      # every harness in the registry, and what it resolved to

If it resolved to the wrong binary, or to none, set the path for that harness in Settings, Harnesses. That is the usual fix on a machine carrying several installs of the same CLI. A harness the registry has never heard of is a different situation and not a fault: it runs perfectly in a real terminal, it just gets no layer on top.

Browsers restrict the microphone and the clipboard outside a secure context, so this is almost always HTTPS rather than swe-mux. In order:

1. Confirm a daemon is listening on the port your configuration actually names.
2. Confirm tailscale serve status proxies port 443 to that port.
3. Confirm the phone is reaching the .ts.net hostname. The certificate is bound to the hostname, so the raw 100.x address cannot serve HTTPS at all.
4. Confirm Use Tailscale DNS is on, and that Android's Private DNS is off or automatic.

Automatic delivery is off by default. A staged message waits for you to send it. If you queued three and expected them to flow, that is the design rather than a fault. The prompt queue covers turning it on and what the readiness gate and stability window mean.

Awaiting means the agent is waiting on you - an approval, a question, a choice. It is not a stall. Read the pane.

Idle is the one that is genuinely ambiguous, and swe-mux never reports it as finished on its own: an agent waiting on you and an agent with background work still running look identical in a quiet terminal and mean the opposite.

mux doctor --export > diagnostics.json

That is the full bundle as JSON: the sanitized configuration, remote-connection state, firewall status, network counters, fleet status health, the status timeline and recovery sink statistics, any cold sessions, and the tails of the daemon log. It is an artifact to attach to a bug report rather than a table to read.

It is sanitized rather than raw, and the full report reads no secret, no terminal byte, and no message content. Read it before you attach it anyway.

Bugs go to the issue tracker, with the export attached. Feature requests go to the Ideas discussions, where a thumbs-up is a vote - and it is worth checking deliberately not on the roadmap first, because some things are answered with a reason rather than with silence.