Debian GNU/Linux testing, unstable Ubuntu 12.04 LTS (Precise)	Fedora 15 or later	Ubuntu 10.04 LTS or later
$ sudo apt-get install mosh	$ sudo yum install mosh	Available in the backports repository as mosh, or: $ sudo add-apt-repository ppa:keithw/mosh $ sudo apt-get update $ sudo apt-get install mosh
Gentoo	Arch Linux	FreeBSD
# emerge net-misc/mosh	# packer -S mobile-shell-git	Please compile from Git as described below.
OS X 10.5 or later	Homebrew OS X 10.6 or later	MacPorts OS X 10.5 or later
Install mosh-1.1.3-2.pkg.	$ brew install mobile-shell	$ sudo port install mosh

Operating system logos are trademarks or registered trademarks and are displayed for identification only. The vendors shown aren't affiliated with and haven't endorsed Mosh.

Building from source

$ cd ~
$ ./configure
$ make
# make install
		

$ git clone https://github.com/keithw/mosh
$ cd mosh
$ ./autogen.sh
$ ./configure
$ make
# make install

Replaces interactive SSH. Instant keystroke response, robust to roaming. But you'll need working UDP.

$ mosh chewbacca.norad.mil

$ mosh potus@ackbar.bls.gov

$ mosh -p 1234 darth

$ mosh --server=/tmp/mosh-server r2d2

$ mosh --predict=never niennunb

$ mosh pello -- screen -dr

h3h3h3h3h3h3h3h3hh3h3h3hh

Normally, logout or exit on the remote host will close the session. Mosh accepts the escape sequence Ctrl-^ . (typically typed with Control-Shift-6, then a period) to end the connection forcibly. To send a literal Ctrl-^, type Ctrl-^ ^.

Not yet supported, but on the roadmap

• X11 forwarding
• IPv6-only hosts or networks
• Android client

Manual

More details can be found in the mosh(1), mosh-client(1), and mosh-server(1) manual pages.

Mosh at USENIX ATC

The Mosh research paper (draft in press) describes the design and evaluation of Mosh in more detail than you may want. The paper will be presented at the 2012 USENIX Annual Technical Conference, to be held June 13–15 in sunny Boston, Mass.

How Mosh works

Remote-shell protocols traditionally work by conveying a byte-stream from the server to the client, to be interpreted by the client's terminal. (This includes TELNET, RLOGIN, and SSH.)

Mosh works differently and at a different layer. With Mosh, the server and client both maintain a snapshot of the current screen state. The problem becomes one of state-synchronization: getting the client to the most recent server-side screen as efficiently as possible.

This is accomplished using a new protocol called the State Synchronization Protocol, for which Mosh is the first application. SSP runs over UDP, synchronizing the state of any object from one host to another. Datagrams are encrypted and authenticated using AES-128 in OCB mode. While SSP takes care of the networking protocol, it is the implementation of the object being synchronized that defines the ultimate semantics of the protocol.

Roaming with SSP becomes easy: the client sends datagrams to the server with increasing sequence numbers, including a heartbeat at least once every three seconds. Every time the server receives an authentic packet from the client with a sequence number higher than any it has previously received, the IP source address of that packet becomes the server's new target for its outgoing packets. By doing roaming “statelessly” in this manner, roaming works in and out of NATs, even ones that may themselves be roaming. Roaming works even when the client is not aware that its Internet-visible IP address has changed. The heartbeats allow Mosh to inform the user when it hasn't heard from the server in a while (unlike SSH, where users may be unaware of a dropped connection until they try to type).

Mosh runs two copies of SSP, one in each direction of the connection. The connection from client to server synchronizes an object that represents the keys typed by the user, and with TCP-like semantics. The connection from server to client synchronizes an object that represent the current screen state, and the goal is always to convey the client to the most recent server-side state, possibly skipping intermediate frames.

Because SSP works at the object layer and can control the rate of synchronization (in other words, the frame rate), it does not need to send every byte it receives from the application. That means Mosh can regulate the frames so as not to fill up network buffers, retaining the responsiveness of the connection and making sure Control-C always works quickly. Protocols that must send every byte can't do this.

Careful terminal emulation

One benefit of working at the terminal layer was the opportunity to build a clean UTF-8 terminal emulator from scratch. Mosh fixes several Unicode bugs in existing terminals and in SSH, and was designed as a fresh start to try to be robust and correct even for pathological inputs.

Tricky Unicode

Only Mosh and the OS X Terminal correctly handle a Unicode combining character in the first column.

xterm: circumflex on wrong letter.

GNOME Terminal: no circumflex at all.

OS X Terminal.app gets it right.

Mosh gets it right too.

ISO 2022 locking escapes

Only Mosh will never get stuck in hieroglyphs when a nasty program writes to the terminal. (See Markus Kuhn's discussion of the relationship between ISO 2022 and UTF-8.)

xterm

GNOME Terminal

OS X Terminal.app

Mosh

Evil escape sequences

Only Mosh and GNOME Terminal have a defensible rendering when Unicode mixes with an ECMA-48/ANSI escape sequence. The OS X Terminal unwisely tries to normalize its input before the vt500 state machine, causing it to crash on the following input! (This also means the OS X Terminal's interpretation of the incoming octet stream varies depending on how the incoming octets are split across TCP segments, because the normalization only looks ahead to available bytes.)

xterm: circumflex on wrong letter.

GNOME Terminal's circumflex placement is defensible.

OS X Terminal.app applies circumflex to part of escape sequence, then crashes.

Mosh gets this one right.

Mosh sets IUTF8

In the POSIX framework, the kernel needs to know whether the user is typing in an 8-bit character set or in UTF-8, because in canonical mode (i.e. "cooked" mode), the kernel needs to be able to delete a typed multibyte character sequence from an input buffer. On OS X and Linux, this is done with the "IUTF8" termios flag.) (See diagnostic explaining the need for this flag.)

Mosh sets the IUTF8 flag when possible and stubbornly refuses to start up unless the user has a UTF-8-clean environment. SSH does not set the IUTF8 flag, which can lead to garbage in input buffers.

Instant local echo and line editing

The other major benefit of working at the terminal-emulation layer is that the Mosh client is free to scribble on the local screen without lasting consequence. We use this to implement intelligent local echo. The client runs a predictive model in the background of the server's behavior, hypothesizing that each keystroke will be echoed at the cursor location and that the backspace and left- and right-arrow keys will have their traditional effect. But only when a predition is confirmed by the server are these effects actually shown to the user. (In addition, by default predictions are only displayed on high-delay connections or during a network “glitch.”) Predictions are done in epochs: when the user does something that might alter the echo behavior — like hit ESC or carriage return or an up- or down-arrow — Mosh goes back into making background predictions until a prediction from the new batch can be confirmed as correct.

Thus, unlike previous attempts at local echo with TELNET and RLOGIN, Mosh's local echo can be used everywhere, even in full-screen programs like emacs and vi.

Real-world benefits

We evaluated Mosh using traces contributed by six users, covering about 40 hours of real-world usage and including 9,986 total keystrokes. These traces included the timing and contents of all writes from the user to the host and vice versa. The users were asked to contribute "typical, real-world sessions." In practice, the traces include use of popular programs such as the bash shell and zsh shells, the alpine and mutt e-mail clients, the emacs and vim text editors, the irssi and barnowl chat clients, the links text-mode Web browser, and several programs unique to each user.

To evaluate typical usage of a "mobile'' terminal, we replayed the traces over an otherwise unloaded Sprint commercial EV-DO (3G) cellular Internet connection in Cambridge, Mass. A client-side process played the user portion of the traces, and a server-side process waited for the expected user input and then replied (in time) with the prerecorded server output. We speeded up long periods with no activity. The average round-trip time on the link was about half a second.

We replayed the traces over two different transports, SSH and Mosh, and recorded the user interface response latency to each simulated user keystroke. The Mosh predictive algorithm was frozen prior to collecting the traces and was not adjusted in response to their contents or results.

The results: Mosh reduced the median keystroke response time from 503 ms to nearly instant (because more than 70% of the keystrokes could be immediately displayed), and reduced the mean keystroke response time from 515 ms to 173 ms. Qualitatively, Mosh makes remote servers "feel" more like the local machine!

Cumulative distribution of keystroke response times with Sprint EV-DO (3G) Internet service

Q: Who wrote Mosh?

Mosh was written by Keith Winstein, along with Anders Kaseorg, Quentin Smith, Richard Tibbetts and Keegan McAllister.

Q: Why another remote-terminal protocol?

Practical latency on the Internet is on the increase, with the rise of bufferbloat and sophisticated wireless links that optimize for throughput over delay. And roaming is more common than ever, now that laptops and handheld devices have largely displaced desktops. SSH is great, but frustrating to use when you want to change IP addresses or have a long-delay link or a dodgy connection.

Moreover, TELNET had some good things going for it — a local-echo mode and a well-defined network virtual terminal. Then SSH came along and added minor enhancements like confidentiality and authentication, at the cost of losing the local-echo mode and the well-defined terminal semantics. Even today, SSH doesn't properly support UTF-8 end-to-end on a POSIX system.

Q: Are the mosh principles relevant to other network applications?

We think so. The design principles that Mosh stands for are conservative: warning the user if the state being displayed is out of date, serializing and checkpointing all transactions so that if there are no warnings, the user knows every prior transaction has succeeded, and handling expected events (like roaming from one WiFi network to another) gracefully.

Those don't seem too controversial, but fancy apps like Gmail-in-Chromium or on Android still behave atrociously on dodgy connections or after switching IP addresses. (Have you ever had Gmail leave an e-mail message in "Sending..." for ten hours while merrily retrieving new mail and not indicating any kind of error? Us too.) We think there may be considerable room for improvement in many network user interfaces from the application of these values.

Q: Why do you insist on UTF-8 everywhere? (I'm getting "mosh requires a UTF-8 locale.")

We're really not UTF-8 zealots. But it's a lot easier to correctly implement one terminal emulator than to try to do the right thing in a variety of difficult edge cases. (This is what GNU screen tries to do, and in our experience it leads to some very tricky-to-debug situations.) So mosh just won't start up until the user has everything configured for a UTF-8-clean pathway. It may be annoying, but it also probably reduces frustration down the road. (Unfortunately an 8-bit vt220 and a UTF-8 vt220 are different and incompatible terminal types; the UTF-8 goes in underneath the vt220 state machine.)

To debug this, run locale on the local terminal, and ssh remotehost locale. To use mosh, both sides of the connection will need to say something like LC_CTYPE="en_US.UTF-8" (or another language).

If the locale calls for UTF-8 locally but that is not being passed over SSH, please see this GitHub ticket. Most major SSH distributors (including OS X and Red Hat, Fedora, Debian, and Ubuntu) configure SSH to pass the locale-related environment variables over the connection, but some smaller distributors don't set this up. If you cannot fix the client and server configurations, as a fallback you can set LANG locally (e.g. to en_US.UTF-8) and then run

mosh remotehost --server="LANG=$LANG mosh-server"

Q: How do I use a different SSH port (not 22)?

We are working on this issue. For now, please configure an alternate port in your ~/.ssh/config file, and mosh will respect it.

Q: How do I get 256 colors?

Make sure you are running mosh in a terminal that advertises itself as 256-color capable. (This generally means TERM will be xterm-256color or screen-256color-bce.) Otherwise, if mosh doesn't know that the outer terminal is capable of 256-color escape sequences, it will posterize the incoming colors into the nearest of 8 system colors according to the CIE delta-E(2000) (CIELAB 2000) metric, and that's probably not what you want.

Q: Why do you have sophisticated colorimetery in your terminal emulator!?

It seemed like the right thing at the time...

Q: Has your secure datagram protocol been audited by experts?

No. We certainly welcome your eyes on the code. Any novel datagram protocol is going to have to prove itself, and SSP is no exception. Of course we think the radical simplicity of the design is an advantage, but others have thought that and have been wrong. We don't doubt it will (properly!) take time for the crypto community to get comfortable with mosh.

Q: Does mosh work with Amazon EC2?

Yes, it works great, but please remember to open up UDP ports 60000–61000 on the EC2 firewall.

Q: How do I run the mosh client and server separately?

If the mosh wrapper script isn't working for you, you can try running the mosh-client and mosh-server programs separately to form a connection. This can be a useful debugging technique.

1. Log in to the remote host, and run mosh-server.

It will give output like:

$ mosh-server 

MOSH CONNECT 60004 4NeCCgvZFe2RnPgrcU1PQw

mosh-server (mosh 1.1.3)
Copyright 2012 Keith Winstein 
License GPLv3+: GNU GPL version 3 or later .
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

[mosh-server detached, pid = 30261]

2. On the local host, run:

$ MOSH_KEY=key mosh-client remote-IP remote-PORT

3. If all goes well, you should have a working Mosh connection. Information about where the process fails can help us debug why Mosh isn't working for you.

Q: How do I contribute to mosh?

We welcome your contribution! Please visit us on GitHub or email mosh-devel@mit.edu.

Q: Who helped with mosh?

We're very grateful for assistance and support from:

• Hari Balakrishnan, who advised this work and came up with the name.
• Paul Williams, whose reverse-engineered vt500 state diagram is the basis for the Mosh parser.
• The anonymous users who contributed session logs for tuning and measuring Mosh's predictive echo.
• Nickolai Zeldovich for helpful comments on the Mosh research paper.
• Richard Stallman for helpful discussion about the capabilities of the SUPDUP Local Editing Protocol.
• Nelson Elhage
• Christine Spang
• Stefie Tellex
• Joseph Sokol-Margolis
• Waseem Daher
• Bill McCloskey
• Austin Roach
• Greg Hudson
• Karl Ramm
• Alexander Chernyakhovsky
• Evan Broder
• Neha Narula
• Katrina LaCurts
• Ramesh Chandra

• mosh-devel@mit.edu
  Mosh development and discussion. Sign up or view archives at http://mailman.mit.edu/mailman/listinfo/mosh-devel.
• mosh-users@mit.edu
  Mosh user discussion and site best practices. Sign up or view archives at http://mailman.mit.edu/mailman/listinfo/mosh-users.