MOSH(1) General Commands Manual MOSH(1)
NAME
mosh - mobile shell with roaming and intelligent local echo
SYNOPSIS
mosh [options] [--] [user@]host [command...]
DESCRIPTION
mosh (mobile shell) is a remote terminal application that supports in-
termittent connectivity, allows roaming, and provides speculative local
echo and line editing of user keystrokes.
Compared with ssh, mosh is more robust — its connections stay up across
sleeps and changes in the client's IP address — and more responsive, be-
cause the protocol is tolerant of packet loss and the client can echo
most keystrokes immediately, without waiting for a network round-trip.
mosh uses ssh to establish a connection to the remote host and authenti-
cate with existing means (e.g., public-key authentication or a pass-
word). 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.
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 com-
mands.
By default, mosh shows its predictions only on high-latency connections
and to smooth out network glitches. (On longer-latency links, the pre-
dicted cells are underlined until confirmed by the server.) Occasional
echo mistakes are corrected within a network round-trip and do not cause
lasting effect.
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.
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.
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 vari-
ables 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 envi-
ronment 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.
OPTIONS
Options named --experimental-* are subject to change or removal in fu-
ture versions of Mosh; their design or function is not yet final.
command
Command to run on remote host. By default, mosh executes a login
shell.
--client=PATH
path to client helper on local machine (default: "mosh-client")
--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.
This option can be used to set environment variables for the
server by using the env(1) command to wrap the actual server com-
mand. See mosh-server(1) for available environment variables.
--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".
--ssh-pty
--no-ssh-pty Enable or disable ssh's use of a pty when connecting
to a remote host. The default is enabled.
--predict=WHEN
Controls use of speculative local echo. WHEN defaults to `adap-
tive' (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.
Even on `always', mosh will only show predictions when it is con-
fident. 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.
-a Synonym for --predict=always
-n Synonym for --predict=never
--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'.
-o Synonym for --predict-overwrite
--family=inet
Only use IPv4 for the SSH connection and Mosh session.
--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.
--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.
--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.
--family=prefer-inet
Similar to --family=all, but attempt connects to the IPv4 ad-
dresses first. This is the default.
--family=prefer-inet6
Similar to --family=all, but attempt connects to the IPv6 ad-
dresses first.
-4 Synonym for --family=inet
-6 Synonym for --family=inet6
-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.
--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 multi-
homed servers.
With --bind-server=any, the server will reply on the default in-
terface 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.
With --bind-server=IP, the server will attempt to bind to the
specified IP address.
--no-init
Do not send the smcup initialization string and rmcup deinitial-
ization string to the client's terminal. On many terminals this
disables alternate screen mode.
--local
Invoke mosh-server locally, without using ssh. This option re-
quires the host argument to be a local, numeric IPv4/IPv6 ad-
dress. This option is useful for testing.
--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.
With remote, the server's SSH_CONNECTION environment variable
will be used. This is useful for environments where ssh forward-
ing is used, or the --ssh-proxy-command option is used for other
purposes.
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 host-
name.
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 key-
boards. Users of non-English keyboards may find it difficult or impos-
sible 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.
There are two slightly different modes for escape sequences, depending
whether the escape character is printable or not.
If the escape character is a printable character, it must be prefixed
with a newline, similar to OpenSSH. To send the escape character it-
self, type it twice. If the escape character is set to ~, mosh will be-
have much like OpenSSH.
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 correspond-
ing ASCII character (for Ctrl-^ you would type ^, for Ctrl-B you would
type B).
The escape sequence to shut down the connection is Esc .. The sequence
Esc Ctrl-Z suspends the client. Any other sequence passes both charac-
ters through to the server.
ENVIRONMENT VARIABLES
These variables are not actually interpreted by mosh(1) itself, but are
passed through to mosh-server(1). They are described here for ease of
use.
MOSH_ESCAPE_KEY
When set, this configures the escape character used for local
commands. The escape character may be set to any ASCII character
in the range 1-127. The variable must be set with a single lit-
eral ASCII character. Control characters are set with the actual
ASCII control character, not with a printable representation such
as "^B".
MOSH_PREDICTION_DISPLAY
Controls local echo as described above. The command-line flag
overrides this variable.
MOSH_TITLE_NOPREFIX
When set, inhibits prepending "[mosh]" to window title.
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>.
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
April 2013 MOSH(1)
Generated by dwww version 1.16 on Tue Dec 16 05:54:00 CET 2025.