I want to be able to start a tmux session on a remote server, and then use iTerm2's native windows and split screens on my local machine.

For example, let's say my remote server has a tmux session running with one window that has two panes. In iTerm2 on my local machine, I want two native iTerm2 panes such that each pane contains a different tmux pane.

Is this possible?

(I know the reverse is possible — whereby I can run a tmux session on my local machine and another machine will see my iTerm2 tabs as windows for instance. But this seems kind of useless.)

3 Answers 3


Yes it is possible, jut make sure:

  • To have latest version of tmux installed remotely
  • Have most recent version of iterm2 installed locally

Login via ssh login@hostname -t 'tmux -CC' and voilà - this should open iTerm2 window on your local box logged into remote box.

  • 6
    also don't forget on reconnect to use ssh login@hostname -t 'tmux -CC attach' and look into the shell->tmux->dashboard menu in iterm2. Aug 16, 2016 at 23:05
  • 1
    hey, do You guys know how to do it with mosh instead of ssh? edit: it's not possible: github.com/mobile-shell/mosh/issues/640
    – Thomas
    Mar 12, 2018 at 20:29
  • 2
    If you want to connect and attach to a specific session, you can use the following: ssh login@hostname -t 'tmux -CC a -t sessionName' Nov 12, 2018 at 0:05
  • any chance to make it work with autossh or somehow make it resist disconnects?
    – igor
    Nov 14, 2018 at 22:45


ssh <hostname> -t 'tmux -CC new -A -s tmssh'


Inside an existing ssh session (assuming you are using iTerm2), you can simply run tmux -CC and a native iTerm2 window will open with tmux integration. This means that you have native scrolling, split screen, and copy-paste available to you.

You can combine this with the ssh command to immediately open the native tmux window:

ssh login@hostname -t 'tmux -CC'
  • -t forces pseudo-tty allocation (allows control characters inside SSH)

The downside of this approach is that you will get a new tmux session each time, so you will not be able to reconnect to view long-running processes (unless you remember to run tmux -CC attach).

We can expand the command a little to create a named tmux session, create the session if it does not exist, or reconnect if the session already exists:

ssh <hostname> -t 'tmux -CC new -A -s tmssh'
  • new creates a new session
  • -A makes new-session behave like attach-session if session name already exists
  • -s tmssh creates a session named tmssh

Now you have a native iTerm2 tmux window, which you can close at any time, and reconnect to when needed.

Helper Function

Finally, to make life easier we can put this all into a helper function that you can add to your bashrc or zshrc:

# tmux+ssh helper function with iterm integration
function tmssh () {
  if [[ -z "$1" ]]; then
    echo "usage: $me [ssh-args] hostname"
    return 1

  ssh "$@" -t 'tmux -CC new -A -s tmssh'
  • Not able to split session using ctrl+b, " or ctrl+b %
    – Logu
    Apr 17, 2021 at 15:33
  • Correct. Because if you do this you will get an iTerm window, which means you need to use iTerm shortcuts to split windows (cmd+D). Apr 19, 2021 at 23:59

Here is what worked for me, with the stable release versions as of 2015-12-16, which are iTerm 2.1.4 on OS X 10.11.2 and tmux 1.9 on Raspbian Linux:

  1. First use .ssh/config on your local machine and .ssh/authorized_keys on your remote machine to configure password-less login to the remote system. Once this is properly configured, you should be able to login just by doing ssh pi (supposing pi is the host name of your remote system).

  2. Create a new iTerm2 profile which, instead of doing a login to your local shell, only calls ssh pi to login to the remote machine. To configure this, go: Preferences / Profiles / + / Command.Command = "ssh pi"

  3. Open an iTerm2 window to the remote machine via your new profile, by doing: Profiles / Pi.

  4. In the iTerm2 remote login window, at the command line do: tmux -CC. After this your iTerm2 window shows the tmux command mode, tmux creates a new session, and iTerm2 immediately creates a new iTerm2 window for that tmux session. Within that new iTerm2 window, the initial iTerm2 tab represents the single tmux window of that session. If you do CMD-T, this will create a new iTerm2 tab, representing a new tmux window.

How do you use this?

  • At this point you can do "Shell / tmux / Dashboard" in order to observe iTerm2's understanding of the existing tmux sessions and windows.

  • If you close the iTerm2 window representing the tmux session, it kills the underlying session and all it's tmux windows.

  • If you close the iTerm2 window showing the tmux command mode, then it seems to just kills the tmux client instance that was connected to that session, so both your iTerm2 windows disappear, but the tmux session is still alive and you can re-attach to it.

  • If you want a more orderly detach from tmux, then just do ESC within the tmux command mode window.

  • If instead of creating a new tmux session, what you wanted originally was to attach to an existing session, then you can do that with tmux -CC attach.

In theory, I think there should be a way to configure iTerm2 or tmux so that when you connect to the remote system you are automatically attached to any existing tmux session, but I was not able to get that to work by modifying the command line in the iTerm2 profile.

  • To automatically connect to a running tmux session on ssh login I use [[ $- == *i* && $SSH_TTY && -z $TMUX && ! -r ~/.notmux ]] && tmux attach-session && exit in .bashrc (or something that is called from there) The tests are for: interactive shell, ssh session, not already running in tmux, no emergency-dont-do-it file. The exit at the end closes the connection upon exiting tmux (mostly a detach for me).
    – zany
    Oct 27, 2016 at 11:21

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .