Docs · Topic
Mosh
Mosh keeps your terminal alive across Wi-Fi-to-cellular handoffs, changing IP addresses, phone sleep, and lossy connections. You enable it per host with Use mosh on the connection form, or make it the default for new connections under Settings › Terminal › Mosh for new connections.
Install mosh-server on the host
Section titled “Install mosh-server on the host”Moshpit connects over SSH first, launches mosh-server on your host, and switches the session to UDP. Install the mosh package on the server with your system package manager:
# Debian / Ubuntusudo apt install mosh
# Fedora / RHELsudo dnf install mosh
# macOS (Homebrew)brew install moshIf mosh-server lives outside the standard PATH (for example /opt/homebrew/bin/mosh-server), set its location on the connection under ADVANCED › mosh-server path. If mosh-server is not installed when you connect, Moshpit tells you and opens the session over SSH instead.
Open UDP ports
Section titled “Open UDP ports”Each Mosh session binds one UDP port on the server, defaulting to the range 60000–61000. Make sure your server firewall and cloud security group allow inbound UDP on that range, and your local network allows outbound UDP.
To narrow or move the port range for every connection:
- Open Settings › Terminal › UDP ports.
- Set From and To (between
1and65535). - Tap Save.
Predictive echo
Section titled “Predictive echo”While waiting for the server to acknowledge keystrokes over a slow link, Mosh can show what you typed right away and underline or trail predicted characters until the server confirms them.
Configure the default under Settings › Terminal › Predictive echo, or override a single host under Predict Mode in Edit connection:
| Mode | Behaviour |
|---|---|
| Adaptive | Predicts keystrokes only when round-trip latency rises. |
| Always | Predicts keystrokes on every Mosh session regardless of latency. |
| Never | Waits for the server to echo every character. |
You can also toggle Trail while predicting under CURSOR in Settings › Terminal.
Roaming and background resume
Section titled “Roaming and background resume”When your phone switches networks or wakes from sleep:
- If
mosh-serveris still running and reachable when you return to Moshpit, the session picks right back up without reconnecting. - While a network change is settling and no UDP reply has arrived yet, Moshpit displays a notice and queues what you type, sending it as soon as the server answers.
- Long-press the
MOSHpill in the terminal’s top bar to inspect round-trip time and packet counters or tap Repaint screen.
When to use SSH instead
Section titled “When to use SSH instead”Turn off Use mosh (or tap Use SSH when UDP cannot get through) in these cases:
- Jump hosts: Mosh needs UDP straight to the target machine. Any connection using Connect via runs over SSH; see Jump hosts.
- Blocked UDP: guest Wi-Fi networks or strict firewalls that drop all UDP packets on
60000–61000. - Inline terminal graphics: Mosh synchronizes character screen states rather than the raw byte stream, so kitty, iTerm2, and sixel inline images require SSH; see Reading the terminal.