MOSH(1)

✨ MOSH(1) — mobile shell, but make it bestie-core ✨

okay so bestie, welcome to the mosh manual. this is the part where we read the whole thing together, no skimming, because every flag matters. 💖

🌸 NAME 🌸

mosh — mobile shell with roaming and intelligent local echo. that's the name, that's the game, no cap. 🦋

🌈 SYNOPSIS 🌈

mosh [options] [--] [user@]host [command...]

💅 DESCRIPTION 💅

okay so mosh (mobile shell) is a remote terminal application that supports intermittent connectivity, allows roaming, and provides speculative local echo and line editing of user keystrokes. ngl it's literally built for when your wifi is giving chaotic and your laptop keeps changing its IP. ✨

compared with ssh, mosh is more robust — its connections stay up across sleeps and changes in the client's IP address — and more responsive, because the protocol is tolerant of packet loss and the client can echo most keystrokes immediately, without waiting for a network round-trip. so yeah, the latency? not the main character here. 💅

mosh uses ssh to establish a connection to the remote host and authenticate with existing means (e.g., public-key authentication or a password). then mosh executes the unprivileged mosh-server helper program on the server, then closes the SSH connection and starts the mosh-client, which establishes a long-lived datagram connection over UDP. it's giving "handoff, but make it seamless." 🎀

to improve responsiveness, mosh runs a predictive model of the server's behavior in the background, trying to guess the effect of each keystroke on the screen. it makes predictions for normal typing, backspace, and the left- and right-arrow keys. when it is confident, mosh displays the predictions without waiting for the server. the predictive model must prove itself anew on each row of the terminal and after each control character, so mosh avoids echoing passwords or non-echoing editor commands. no spoilers for your secrets, periodt. 🔒

by default, mosh shows its predictions only on high-latency connections and to smooth out network glitches. (on longer-latency links, the predicted cells are underlined until confirmed by the server.) occasional echo mistakes are corrected within a network round-trip and do not cause lasting effect. so if you see a lil typo prediction, don't panic, it's lowkey temporary. 😭

mosh does not support X forwarding or the non-interactive uses of SSH, including port forwarding or sshfs. mosh works through typical client-side network address translators but requires UDP to pass between client and server. by default, mosh uses the ports between 60000 and 61000, but allows the user to request a particular UDP port instead. so like, it's not trying to be everything, it's just trying to be the bestie that keeps your terminal alive. 💖

currently, mosh has limited support for IPv6, dual-stack networks, and servers with multiple addresses. at session start, it will select a single IPv4 or IPv6 server address to connect to for the lifetime of the session. one address, one session, no flip-flopping. 🌸

mosh will do its best to arrange a UTF-8 character set locale on the client and server. the client must have locale-related environment variables that specify UTF-8. mosh will pass these client variables to the mosh-server on its command line, but in most cases they will not need to be used. mosh-server first attempts to use its own locale-related environment variables, which come from the system default configuration (sometimes /etc/default/locale) or from having been passed over the SSH connection. but if these variables don't call for the use of UTF-8, mosh-server will apply the locale-related environment variables from the client and try again. so it's literally trying its best to make your emojis and accents work. 🫶

✨ OPTIONS ✨

options named --experimental-* are subject to change or removal in future versions of Mosh; their design or function is not yet final. bestie, do not build your whole personality on experimental flags. they ate, but they might leave. 💀

• command — command to run on remote host. by default, mosh executes a login shell. so if you want something else, say it. 🐚
• --client=PATH — path to client helper on local machine (default: "mosh-client"). that's the local bestie doing the work. 💅
• --server=COMMAND — command to run server helper on remote machine (default: "mosh-server").

the server helper is unprivileged and can be installed in the user's home directory. no root required, we love that for us. 🎀

this option can be used to set environment variables for the server by using the env(1) command to wrap the actual server command. see mosh-server(1) for available environment variables. iykyk. ✨

• --ssh=COMMAND — OpenSSH command to remotely execute mosh-server on remote machine (default: "ssh").

an alternate ssh port can be specified with, e.g., --ssh="ssh -p 2222". so if your ssh is on a weird port, you can still slay. 🔥

• --ssh-pty, --no-ssh-pty — enable or disable ssh's use of a pty when connecting to a remote host. the default is enabled. pty on by default, okay? 💖
• --predict=WHEN — controls use of speculative local echo. WHEN defaults to adaptive (show predictions on slower links and to smooth out network glitches) and can also be always or never.

the MOSH_PREDICTION_DISPLAY environment variable controls this setting permanently and can adopt the same three values. set it and forget it. ✨

even on always, mosh will only show predictions when it is confident. this generally means a previous prediction on the same row of the terminal has been confirmed by the server, without any intervening control character keystrokes. so no wild guesses, only certified vibes. 💅

• -a — synonym for --predict=always. all the predictions, all the time. 👑
• -n — synonym for --predict=never. no predictions, no surprises. 🧚
• --predict-overwrite — when prediction is enabled, do not insert speculative local echo before existing text, but overwrite it instead.

the MOSH_PREDICTION_OVERWRITE environment variable also enables this if its value is 'yes'. so yes means overwrite mode. 💖

• -o — synonym for --predict-overwrite. cute, short, iconic. 🎀
• --family=inet — only use IPv4 for the SSH connection and Mosh session. old school but reliable. 🌈
• --family=inet6 — only use IPv6 for the SSH connection and Mosh session. this and the following modes require Perl's IO::Socket::IP or IO::Socket::INET6 modules. so check your Perl modules, bestie. 🦋
• --family=auto — autodetect IPv4 or IPv6 for hosts that only have addresses in a single family. hosts with both IPv4 and IPv6 addresses will raise an error, and require re-invocation of mosh with another --family option. so dual-stack hosts? not this one. 😭
• --family=all — choose an address from all available IPv4 or IPv6 address, even for dual-stack hosts. this is the most convenient option, but requires dual-stack connectivity, and Mosh 1.2.5 or later on the server, when roaming with dual-stack servers. convenient but with conditions, fr fr. ✨
• --family=prefer-inet — similar to --family=all, but attempt connects to the IPv4 addresses first. this is the default. so IPv4 gets first dibs. 💅
• --family=prefer-inet6 — similar to --family=all, but attempt connects to the IPv6 addresses first. IPv6 first, periodt. 🌸
• -4 — synonym for --family=inet. four, but make it IPv4. 🔢
• -6 — synonym for --family=inet6. six, but make it IPv6. 🔢
• -p PORT[:PORT2], --port=PORT[:PORT2] — use a particular server-side UDP port or port range, for example, if this is the only port that is forwarded through a firewall to the server. with -p 0, the server will let the operating system pick an available UDP port. otherwise, mosh will choose a port between 60000 and 61000. please note that this option does not affect the server-side port used by SSH. so firewall bestie, this one's for you. 🔥
• --bind-server={ssh|any|IP} — control the IP address that the mosh-server binds to.

the default is ssh, in which case the server will reply from the IP address that the SSH connection came from (as found in the SSH_CONNECTION environment variable). this is useful for multihomed servers. so it replies from where ssh came from. 🎀

with --bind-server=any, the server will reply on the default interface and will not bind to a particular IP address. this can be useful if the connection is made through sslh or another tool that makes the SSH connection appear to come from localhost. localhost vibes, but make it intentional. ✨

with --bind-server=IP, the server will attempt to bind to the specified IP address. you pick the IP, it tries to bind. 💅

• --no-init — do not send the smcup initialization string and rmcup deinitialization string to the client's terminal. on many terminals this disables alternate screen mode. so if you hate alternate screen, this is your moment. 🫶
• --local — invoke mosh-server locally, without using ssh. this option requires the host argument to be a local, numeric IPv4/IPv6 address. this option is useful for testing. local testing era. 🧪
• --experimental-remote-ip={proxy|local|remote} — select the method used to discover the IP address that the mosh-client connects to.

the default is proxy, which uses SSH's --ssh-proxy-command option to generate and report the exact address that ssh uses to connect to the remote host. this option is generally the most compatible with hosts and other options configured in ssh configuration files. however, this may not work for some configurations, or for environments where a ssh bastion host forwards to a remote machine. it only works with OpenSSH. so OpenSSH only, bestie. 💀

with remote, the server's SSH_CONNECTION environment variable will be used. this is useful for environments where ssh forwarding is used, or the --ssh-proxy-command option is used for other purposes. remote said "i got this." ✨

with local, Mosh resolves the hostname given on its command line, and uses that address for both ssh and Mosh connections. this option ignores any configuration in ssh_config for the same hostname. local means local, no ssh_config drama. 🌸

🔮 ESCAPE SEQUENCES 🔮

the default escape character used by Mosh is ASCII RS (decimal 30). this is typically typed as Ctrl-^ or Ctrl-Shift-6, on US English keyboards. users of non-English keyboards may find it difficult or impossible to type the default escape character, and may need to change the escape character. see the description of MOSH_ESCAPE_KEY, below. in this description, the configured escape character is represented as Esc. okay so Esc is just our shorthand, don't @ me. 💅

there are two slightly different modes for escape sequences, depending whether the escape character is printable or not. so vibe check your escape char. ✨

if the escape character is a printable character, it must be prefixed with a newline, similar to OpenSSH. to send the escape character itself, type it twice. if the escape character is set to ~, mosh will behave much like OpenSSH. so ~ is giving very OpenSSH-coded. 🎀

if the escape character is a non-printable control character, no prefix is used and the escape character is recognized at any time. to send the escape character itself, type the escape character, then its corresponding ASCII character (for Ctrl-^ you would type ^, for Ctrl-B you would type B). so Ctrl-^ then ^, got it? 🫶

the escape sequence to shut down the connection is Esc .. the sequence Esc Ctrl-Z suspends the client. any other sequence passes both characters through to the server. so Esc . is the peace out, Esc Ctrl-Z is the pause, and everything else goes to the server. periodt. 💖

🌸 ENVIRONMENT VARIABLES 🌸

Okay bestie, listen — these variables are not actually interpreted by mosh(1) itself, no cap. They get passed straight through to mosh-server(1). They're listed here just so your life is easier, because digging through another manpage at 2am is not the vibe. 🫶

---

💜 MOSH_ESCAPE_KEY

When you set this, it configures the escape character used for local commands. The escape character can be any ASCII character in the range 1-127. ✨

Fr fr, the variable must be set with a single literal ASCII character. And for control characters? You set them with the actual ASCII control character — not some printable stand-in like "^B". Do not do the printable thing. It will not slay.

---

🦋 MOSH_PREDICTION_DISPLAY

This one controls local echo, as described above (iykyk). 👀 And heads up: the command-line flag overrides this variable. Flag wins, always. Periodt.

---

🎀 MOSH_TITLE_NOPREFIX

When set, this inhibits prepending "[mosh]" to the window title. That's it, that's the whole thing. A little toggle with main character energy. 💅

---

🔥 SEE ALSO 🔥

• mosh-client(1)
• mosh-server(1)

Project home page: https://mosh.org 🌈

---

👑 AUTHOR 👑

mosh was written by Keith Winstein <mosh-devel@mit.edu>. Absolute legend, honestly. ⭐

---

💀 BUGS 💀

Please report bugs to mosh-devel@mit.edu. 🐛

Users may also subscribe to the mosh-users@mit.edu mailing list, at http://mailman.mit.edu/mailman/listinfo/mosh-users 🌸

---

And that's a wrap, bestie! This page is from April 2013 — yes, 2013, it's giving vintage but it still eats — and it's the MOSH(1) manual page. Go forth and roam. 💖✨