Skip to content
moshpit

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.

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:

Terminal window
# Debian / Ubuntu
sudo apt install mosh
# Fedora / RHEL
sudo dnf install mosh
# macOS (Homebrew)
brew install mosh

If 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.

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:

  1. Open Settings › Terminal › UDP ports.
  2. Set From and To (between 1 and 65535).
  3. Tap Save.

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.

When your phone switches networks or wakes from sleep:

  • If mosh-server is 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 MOSH pill in the terminal’s top bar to inspect round-trip time and packet counters or tap Repaint screen.

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.