Do you use a Mac and have long-running ssh session to a workstation or server? Would you like those ssh sessions to behave just like local terminals? How about being able to restore sessions after a disconnection or reboot of your Mac? Then you’ve come to the right place. Here I’ll show you how to set up iTerm and tmux to do all of that and more.

  1. Install iTerm on your Mac

  2. Make sure tmux is installed on your server

  3. Optional, but highly recommended: set up ssh public key login

  4. Create a new Profile in iTerm (Profiles -> Open Profiles -> Edit Profiles -> + button), with the following options:

    a. Name: a name that’s meaningful to you

    b. Shortcut key: if you use this connection often, set a shortcut key for you to start it quickly

    c. Command: ssh -tt user@server tmux -CC new -A -s iterm

This will now reconnect to the session “iterm” or create a new one if a session doesn’t exist.

Shell Integration

iTerm2 features shell integration which does all kinds of wonderful things from marking command results to displaying images to automating file uploads and download. Installing shell integration is easy. When you’re connected to the host you want to use, go to iTerm2 -> Install Shell Integration and it will automatically run the commands to do the installation.

The catch is that shell integration is disabled by default with tmux. To fix that, add the following line to your .bash_profile right before the shell integration is triggered:

export ITERM_ENABLE_SHELL_INTEGRATION_WITH_TMUX=YES

Fixing hostname

Some hosts don’t set hostname correctly or don’t set the proper domain name (I’m looking at you Andromeda). To fix this, again edit your .bash_profile and add the following line above the shell integration:

export iterm2_hostname=foo.example.com

Obviously, replace foo.example.com with the correct fully qualified hostname.