Help

Troubleshooting

Quick fixes for the problems people hit most. For deeper context see Architecture and Configuration.

Attach fails

Symptom: vmux attach errors, hangs, or exits immediately.

Check	What to do
Stale lock / dead daemon	`vmux sessions`, then `vmux doctor`. If a pid file exists but the process is gone, `vmux stop` and attach again.
Wrong session	`vmux --session <name> attach`. Default session is `default`.
Socket permissions / path	Runtime dir must be owned by you, not a symlink, and not group/other-writable. `vmux doctor` reports this.
Terminal too small	Extremely small TTYs can make the layout unusable; enlarge the window.

vmux doctor
vmux status
vmux logs --lines 200

Phantom sessions in `vmux sessions`

Symptom: names like update-check or relay-devices appear as sessions.

Those are daemon state files that live next to session JSON under ~/.local/state/vmux/. Current builds exclude them via a reserved-stem list. If you still see them, upgrade vmux, and don't create a real session with one of those names.

Relay will not pair / phone cannot connect

See also Phone relay & remote.

Tailscale up on both phone and host, same tailnet.
Relay running: vmux relay status or rely on auto-start (relay.enabled, default on).
Port: default 4399, but it is configurable:
```
vmux config set relay.port 4399
vmux relay serve --listen 127.0.0.1:4400
```
The phone app must use the same port.
Bind mode: relay.bind is auto | tailscale | local. Localhost-only binds are unreachable from a physical phone over the tailnet.
Health probe: curl -s http://$(tailscale ip -4):4399/v1/health
Pairing policy: allow_localhost is for same-machine/dev only. allow_tailnet_cgnat is off by default (whois required).
Lost phone: vmux relay devices list then vmux relay devices revoke <id>.

The relay never binds 0.0.0.0 / ::. LAN-wide exposure is intentionally unsupported — use Tailscale.

vmux hooks status — incomplete installs are reported.
Reinstall: vmux hooks install (or --agent claude|codex|grok|shell).
Inside panes, confirm env: echo $VMUX_PANE_ID.

Manual probe:

vmux set-status busy --message "working"
vmux notify --status done --message "tests passed"

Shell integration: eval "$(vmux hooks shell)" in the rc file the pane actually sources.

Automatic tab titles need agent_titles.enabled (default on) and a daemon restart after config changes.

Scrollback missing or shorter than expected

Retention is ui.scrollback_bytes (default 200 KB, clamp 16 KB–5 MB), applied on the next daemon start:
```
vmux config set ui.scrollback_bytes 500000
vmux stop
vmux attach
```
Session state lives in ~/.local/state/vmux/<session>.json. Corrupt files are moved aside, not silently deleted.
Lean attach polls omit full history except for panes you are scrolled back in.

Port detection empty

See Ports & forwarding. Short version: Linux only, leave ports.enabled on, ensure the listener is a child of a pane process, and check ports.ignore / ignore_ephemeral.

Config changes seem ignored

Many keys apply immediately; ui.scrollback_bytes and some title settings need a daemon restart.
Malformed config is ignored on read (defaults) with a warning; mutation commands refuse to overwrite a broken file — fix or delete ~/.config/vmux/config.json first.
Symlinked (dotfiles) config is written through the link; a broken symlink is refused rather than replaced.

vmux config show

Develop without killing your real session

cargo run -- --session dev attach

Never point a buggy debug build at the session where your agents live.

Still stuck

vmux doctor
vmux logs --lines 200
vmux --version

Open an issue at github.com/UAEpro/vmux with the doctor output (redact paths/secrets), or see Support.

Edit this page on GitHub