Tmate makes the perfect Instant Terminal Sharing Tool for live troubleshooters

Share on:

We love Tmate and we bet you will!

Visionary, outstanding, almost magic” that’s what I thought the first time I got my hands on Tmate. Sure, we all know about TeamViewer, VNC, and other remote desktop products we used a hundred times to help our parents or friends through a shared screen. But nothing compares nor prepares you for this in terms of simplicity and seamlessness, especially if Terminals are part of your daily job.

Remote collaboration, in these quarantine times, became more than vital. It was only after posting an issue on a random project on GitHub that someone proposed help through slack and mentioned “live troubleshooting”. I wasn’t sure what he meant but I decided to join and explained my problem. Next thing I know, a command-line I pasted made him connect to my VirtualBox VM and here he was hammering keys on my own terminal. All this with zero latency while he was in Madrid and me in Toronto. That was lit! Total ubiquity, full encryption and of course completely free. Those were the features of Tmate, an Opensource fork of Tmux (local terminal multiplexer) which lets you attach a terminal session from across the world. No more sharing all your desktop’s screen and worrying about your sensitive data or browser tabs you forgot to close. That’s where I thought this little discovery deserved a post on its own. 

For those wondering, Tmate was developed by Nicolas Viennot who opened its source since 2013 hoping to promote pair programming between strangers across the globe.


How It Works

Once installed in your machine you’d run tmate command to establish a secure SSH connection with’s public server that’ll return random SSH and HTML connection strings for your session. Your friend will then paste the connection string (or URL) to attach your terminal session and instantly start interacting with it. This is particularly helpful when using different keyboards. To add more to this awesomeness, remote clients don’t even need Linux as they can pair through a web browser. You can learn more about the architecture from the author’s paper, or by checking the below diagram I managed to draw from reading his publication ;).

Network: The SSH public server ( resolves 4 IPs spread across San Francisco, New York, London, and Singapore which makes it highly available. When the fastest server is elected, the remote tmate(tmux) daemon sends back the connection strings to the session running tmate. Whenever a disconnection happens between a host and remote tmate, or remote tmate & proxy, or proxy & master, sessions reconnect automatically and sync back (with likely a different socket name). Tmate goes through NATs and tolerates host IP changes while its proxy ensures the transparency of remote client connection.

Connection string: The 25 character long random id generated for the session is called token.



In this tutorial, we will learn how to install and use Tmate for remote terminal sharing. It will prove handy for pair-programming, live troubleshooting, or managing servers from a remote location. The example depicts how I quickly shared my VirtualBox environment with someone who could jump in live and resolve my issue (providing the VM had to access to the internet).

1. Open a terminal and enter the following command.



2. Run “tmate” command.

-Your will see all available connection strings for both web and ssh (read-write/read-only) accesses.
  > Copy the content and hit to clear the screen.

3. From the remote machine, open a terminal, past the ssh connection string, hit enter and voila. You are now connected to the host session without any authentication setup. 
    > Let’s run command.

 – Alternatively, you could do the same from a web browser by entering the mentioned session URL. 

4. Your host machine will now display the same command ran from the above remote clients.

5. Find tmate session information and currently connected clients, using the following command:

– If you only want your remote client to interact with the session you can use the “-F” option

Note: For those who want to use named sessions instead of tokens to restart consistently. They will have to request an API key from tmate website and then run a command that would look like this:


End Session

6. To end tmate session enter exit command (always remember this!). 


Install your own server

If you are a security freak you can always host the whole tmate infrastructure in your own server by deploying the docker images listed below: (more details at

Once installed the local machines you want to share sessions from should include the below attributes in the  ~/.tmate.conf file


What’s Next?

I keep enjoying tmate as I was just live fixing a KVM terraform issue I was stuck on, yesterday, with the help of a developer from Sao Paulo, Brazil. Such a cool way to learn and discover the world!  Feel free to talk about it with your colleagues. 

Share on:
Back to Top