Mosh Connections
Use Mosh for resilient connections that survive network changes.
What Is Mosh?
Mosh (Mobile Shell) is a UDP-based remote terminal protocol designed for unreliable or roaming networks. Unlike SSH, which uses a single TCP connection, Mosh establishes an SSH session to start a server process on the remote host, then switches to UDP for the ongoing terminal session.
This makes Mosh ideal when you:
- Move between Wi-Fi networks or switch between Wi-Fi and cellular
- Put your headset to sleep and resume later
- Work on connections with high latency or intermittent drops
- Want local echo prediction so keystrokes appear instantly
Requirements
Mosh requires mosh-server installed on the remote host. Most Linux distributions include it in their package manager:
- Ubuntu / Debian:
sudo apt install mosh - Fedora / RHEL:
sudo dnf install mosh - macOS (Homebrew):
brew install mosh - Arch Linux:
sudo pacman -S mosh
vmux automatically searches common install paths (/usr/local/bin, /opt/homebrew/bin, /usr/bin, /snap/bin) when connecting, so mosh-server doesn't need to be on the remote user's default PATH.
Connecting with Mosh
- Open the Hosts Window or create a new window.
- Set the Transport to Mosh.
- Enter your host, username, and port as you would for SSH.
- Tap Connect.
vmux uses SSH to start mosh-server on the remote host, then establishes a UDP session for the terminal. Authentication works the same as SSH -- you can use a password or SSH key.
Mosh Settings
When you select Mosh as the transport, additional options appear. Most users can leave these at their defaults.
| Setting | Description | Default |
|---|---|---|
| UDP port/range | Single port or range (60000:60010) for the UDP session. Leave empty to let the server pick an available port. | Server default |
| Prediction | Local echo mode. Adaptive shows predictions on slow links, Always shows them immediately, Never disables prediction. | Adaptive |
| Server command | Path or name of the mosh-server binary on the remote host. Only change this if your server is installed in a non-standard location. | mosh-server |
| Address family | IP version preference for the UDP session. | Prefer IPv4 |
Address Family Options
| Option | Behavior |
|---|---|
| Prefer IPv4 | Try IPv4 first, fall back to IPv6 |
| Prefer IPv6 | Try IPv6 first, fall back to IPv4 |
| IPv4 | IPv4 only |
| IPv6 | IPv6 only |
| All | Use any available address |
| Auto | Let the system decide |
To access the Server command and Address family settings, tap Show Advanced Mosh Options in the host form.
Troubleshooting
"mosh-server not found on remote host"
The remote host doesn't have mosh-server installed, or it's in an unusual location. Install it using your distribution's package manager, or set the Server command to the full path (e.g., /home/you/.local/bin/mosh-server).
Connection hangs after "SSH bootstrap starting"
This usually means mosh-server started but UDP traffic is blocked. Check that:
- The remote firewall allows UDP on ports 60000-61000 (the default Mosh range), or on the specific port you configured.
- Your local network doesn't block outbound UDP.
- If you're behind a corporate firewall, try specifying a known-open UDP port in the UDP port/range field.
"Mosh bootstrap failed"
The SSH session connected but mosh-server failed to start. Common causes:
- The remote host doesn't have a UTF-8 locale installed. Mosh requires UTF-8. Run
locale -a | grep -i utfon the remote to check. - The server binary crashed or returned an unexpected response.
Mosh vs. SSH
| SSH | Mosh | |
|---|---|---|
| Protocol | TCP | UDP (after SSH bootstrap) |
| Survives network changes | No | Yes |
| Survives sleep/wake | No | Yes |
| Local echo prediction | No | Yes |
| Port forwarding | Yes | No |
| Requires server install | No (built-in) | Yes (mosh-server) |
For stable, wired connections where you need port forwarding, use SSH. For mobile or unreliable networks, Mosh is the better choice.