Troubleshooting

Steps for diagnosing connection problems between the Pocketmux mobile app and a host running pmux. For installation problems (PATH, Gatekeeper, checksums), see the Installation guide.

First checks

Start with the agent's own view of the world:

pmux status        # version, agent state, session count, paired device
pmux agent status  # is the background agent running?

If the agent is not running, start it with pmux agent start (any pmux command also spawns it automatically). If the mobile app shows the host as offline even though the agent is running, the agent's connection to the signaling server is the usual suspect — check the log:

tail -f ~/.config/pmux/agent.log

For more detail, set log_level = "debug" in ~/.config/pmux/config.toml (or PMUX_LOG_LEVEL=debug) and restart the agent with pmux agent restart.

Host shows offline in the app

The signaling server marks a host offline after 90 seconds without a heartbeat. Common causes:

• The host is asleep. A sleeping machine drops its signaling connection, and the mobile app cannot wake it. Enable power.keep_awake to hold the host awake while the agent runs.
• The host's network changed (Wi-Fi switch, VPN up/down, laptop moved). The agent reconnects to the signaling server automatically on the connection.reconnect_interval schedule (default every 5 s) — give it a few seconds, then refresh the host list in the app.
• A firewall is blocking the agent. Host firewalls sometimes re-prompt or silently block the agent after a version upgrade. Check your firewall's allowed-apps list for pmux and re-approve it.

Connection drops mid-session

The terminal session itself runs over a direct WebRTC connection between phone and host; tmux keeps your session alive on the host regardless, so nothing is lost — reconnecting reattaches to the same session.

• Network transition on the phone (Wi-Fi ↔ cellular): the app re-establishes the connection; reopen the session from the host list if it doesn't recover on its own.
• Repeated drops on one network: some networks (corporate NAT, CGNAT, hotel Wi-Fi) block peer-to-peer paths. Verify whether the TURN relay fallback works by forcing relay-only mode on both ends — a relay-only connection that succeeds while normal mode keeps dropping points at the direct path being unstable on that network.

Isolating the failing layer

Work down the stack:

1. pmux status — agent running and paired?
2. pmux config — server URL correct? (server.url, default https://signal.pmux.io)
3. ~/.config/pmux/agent.log — signaling connect/reconnect lines, and on connect the selected ICE candidate pair (usingRelay flag).
4. In the app, Settings → Logs — the negotiated transport is logged on connect (P2P direct vs TURN relay).
5. Force TURN relay on both ends to cleanly separate "TURN is broken" from "ICE in general is broken".

Still stuck?

Open an issue on the pmux-agent issue tracker with:

• pmux --version output and your OS
• the relevant lines from ~/.config/pmux/agent.log (debug level if possible)
• what the mobile app's Logs screen shows for the failed connection

For security-sensitive reports, follow the vulnerability disclosure policy instead of filing a public issue.