[tmux.app]
tmux 3.8

Docs · Collaboration · tmux 3.8

tmux remote pair programming: shared sockets and SSH

Two people can work in one tmux session at the same time: both SSH into the same server and attach to the same session. If you share a login, that is just tmux attach -t pair. With separate accounts, the host starts tmux on a shared socket (tmux -S), opens it to a group, and allows each guest with server-access (tmux 3.3+), optionally read-only. Every command here was run on tmux 3.8 with real separate Linux users.

Updated Tested on tmux 3.88 min read

On this page
  1. Why pair in tmux?
  2. Method 1: one shared account
  3. Method 2: separate accounts and a shared socket
  4. Read-only observers
  5. Work in different windows at the same time: grouped sessions
  6. Window size when screens differ
  7. tmux sockets explained: -L, -S and $TMUX
  8. tmux on a remote server over SSH
  9. tmux vs tmate and other ways to share a terminal
  10. Troubleshooting shared sessions
  11. FAQ

Quick answer

How do two users share a tmux session?

  • Same Linux account: host runs tmux new -s pair, guest SSHes in and runs tmux attach -t pair.
  • Different accounts: host runs tmux -S /var/tmux/pair new -s pair, gives the socket group read/write, and runs tmux -S /var/tmux/pair server-access -a bob; Bob runs tmux -S /var/tmux/pair attach -t pair.
  • Watch only: server-access -r bob (enforced by the host) or attach -r (the guest's choice).
  • Different windows at the same time: the guest makes a grouped session, tmux new -t pair -s bob.

Why pair in tmux?

Screen sharing sends video. tmux pairing sends terminal text over SSH, so it stays sharp and responsive on a weak connection, and each person keeps their own terminal, font and keyboard. Both people type into the same shells and editors (Neovim, Emacs, Helix all work), and when one person's connection drops, the session, the dev server and the unsaved buffers keep running on the server. The trade-off: it is terminal only, and both people need SSH access to the machine.

Method 1: one shared account

If both of you can log in as the same user, for example dev on a pairing box, nothing needs configuring. Both clients attach to the same session and see the same window and cursor.

host
# Start a named session
tmux new -s pair
guest
# Log in as the same user and attach
ssh dev@pairbox.example.com
tmux attach -t pair

Either of you can detach (Ctrl+b d) without affecting the other. To see who is attached, run tmux list-clients.

Method 2: separate accounts and a shared socket

Each user normally gets a private tmux server whose socket only they can open (/tmp/tmux-UID/default, mode 0600). To share, the host starts a server on a socket in a directory both users can reach, and tmux 3.3 and later then also checks the server's own access list. A guest has to get past three checks:

The three checks a guest passes to join a shared tmux socket A guest user running tmux -S on a shared socket must pass three checks. First, file system permissions on the directory and the socket; failing gives error connecting, Permission denied. Second, the tmux server's access list, set with server-access since tmux 3.3; failing gives access not allowed. Third, whether the entry is read-only; a read-only client can watch and detach but commands that change things fail with client is read-only. bob tmux -S /var/tmux/pair 1. File permissions dir 2770 root:tmuxpair socket g+rw Permission denied 2. Server access list server-access -a bob tmux 3.3+ access not allowed 3. Read or write server-access -r bob or attach -r bob (U,W): types bob (U,R): watches client is read-only
The exact error messages from our test on tmux 3.8, one per check.
  1. Create a group and a shared directory (admin, once)

    admin
    sudo groupadd tmuxpair
    sudo usermod -aG tmuxpair alice
    sudo usermod -aG tmuxpair bob
    # Directory only the group can enter; setgid so new files get the group
    sudo install -d -m 2770 -o root -g tmuxpair /var/tmux

    Alice and Bob must log out and in again after usermod for the new group to apply.

  2. Alice starts tmux on the shared socket and lets Bob in

    alice (host)
    # Start detached so you can finish setup
    tmux -S /var/tmux/pair new -d -s pair
    
    # tmux creates the socket owner-only (srw-------): give the group read/write
    chmod g+rw /var/tmux/pair
    
    # tmux 3.3+: allow Bob (otherwise he gets "access not allowed")
    tmux -S /var/tmux/pair server-access -a bob
    tmux -S /var/tmux/pair server-access -l
    alice (U,W)
    bob (U,W)
    
    tmux -S /var/tmux/pair attach -t pair

    Because the directory is setgid, the socket already belongs to tmuxpair; without that, add chgrp tmuxpair /var/tmux/pair.

  3. Bob attaches

    bob (guest)
    tmux -S /var/tmux/pair attach -t pair

What we saw at each stage, as real users alice and bob on tmux 3.8:

StateBob runs tmux -S /var/tmux/pair ls
Socket still srw-------error connecting to /var/tmux/pair (Permission denied)
After chmod g+rw, before server-accessaccess not allowed
After server-access -a bobpair: 1 windows (created …)
A user outside the groupPermission denied

server-access -d bob removes Bob again and detaches him immediately if he is attached (we checked). The access list lives in the running server, so after a server restart run the server-access commands again (or put them in a script that starts the session).

Read-only observers

For a demo, an interview or mentoring, the guest can watch without typing. There are two ways, and they differ in who decides:

read-only
# Guest's choice: attach read-only (also does not resize the window)
tmux -S /var/tmux/pair attach -r -t pair

# Host's choice (tmux 3.3+): every client Bob opens is read-only
tmux -S /var/tmux/pair server-access -r bob
# ...and back to read-write later
tmux -S /var/tmux/pair server-access -w bob
Real screenshot · tmux 3.8tmux list-clients on the host: the guest's client is flagged read-only and ignore-size (attached with attach -r).
tmux list-clients on the host: the guest's client is flagged read-only and ignore-size (attached with attach -r).
How this was captured

Captured 2026-10-29 04:52 UTC from a real xterm window running tmux 3.8 on Ubuntu 24.04. Nothing is mocked up. The commands that set up the screen:

tmux new-session -d -s pair -n code -x 104 -y 15
tmux new-window -d -t pair: -n guest
tmux send-keys -t pair:guest 'TMUX= script -qfc '"'"'tmux -L shot-pair-readonly attach -r -t pair'"'"' /dev/null' Enter
tmux send-keys -t pair:code 'clear; tmux list-clients -F '"'"'#{client_tty}  #{session_name}  #{client_flags}'"'"'' Enter

A read-only client can watch, switch session and detach; key presses are ignored, and commands that change things fail with client is read-only. attach -r is shorthand for the client flags read-only,ignore-size, so a small read-only guest does not shrink the window for everyone. On a shared account, attach -r is only a courtesy: the guest can simply attach again without it. Use separate accounts and server-access -r when it must be enforced.

Work in different windows at the same time: grouped sessions

Attaching to the same session means you always look at the same window. To share the same set of windows but let each person be in a different one, the guest creates a session group:

grouped session
# Alice: the main session, with the shared windows
tmux -S /var/tmux/pair new -s main

# Bob: a new session in the same group (shares main's windows)
tmux -S /var/tmux/pair new -t main -s bob

tmux -S /var/tmux/pair ls
bob: 2 windows (created Wed Oct 28 18:03:28 2026) (group main)
main: 2 windows (created Wed Oct 28 18:03:28 2026) (group main)

In our test Alice stayed in window editor while Bob switched to window server; new windows either of you creates appear in both sessions. If you both open the same window, you still share it, keystroke for keystroke. Killing Bob's session leaves Alice's alone. For sharing a session with yourself from two terminals, see sharing a session.

Window size when screens differ

When two clients look at the same window, tmux has to pick one size. We attached a 120×40 client, then an 80×24 client, on tmux 3.8:

window-sizeRuleWindow became
latest (default)Size of the client with the most recent activity80×23 (the small client was newest)
smallestFits every client80×23
largestFits the biggest; others see only part120×39
smallest, small client with attach -rRead-only clients are ignored (ignore-size)120×39

The height is one less than the terminal because of the status line. A client whose terminal is bigger than the window sees the unused area filled with dots. With latest, the size follows whoever typed last; set setw -g window-size smallest if that jumping bothers you.

tmux sockets explained: -L, -S and $TMUX

Every tmux server listens on a Unix socket, and every tmux command connects to one. Which one:

You runSocket (tested as root, UID 0)
tmux/tmp/tmux-0/default ($TMUX_TMPDIR replaces /tmp if set)
tmux -L work/tmp/tmux-0/work: a separate, named server
tmux -S /var/tmux/pairExactly that path, which is what makes sharing possible
Any tmux command inside a paneThe server in $TMUX (socket,pid,session)

Print the current one with tmux display -p '#{socket_path}'. With -S, every command must name the socket, including kill-server; without it you talk to your default server instead. Deleting a socket file does not stop the server, but no client can reach it any more. Send the server process SIGUSR1 (kill -USR1 <server pid>) and it recreates the socket; we tried it on 3.8.

tmux on a remote server over SSH

Pairing is one case of running tmux remotely. The everyday form is a session that stays on a server between your connections:

your machine
# Attach to "main" on the server, creating it the first time
ssh -t server 'tmux new -A -s main'

-t gives SSH a terminal, which tmux needs. If people search for "tmux remote control", they usually mean one of two other things: driving tmux from scripts or other programs (send-keys, capture-pane, control mode; see tmux scripting), or Claude Code's Remote Control feature (see Claude Code in tmux). Detaching, reattaching and SSH basics are on the sessions page.

tmux vs tmate and other ways to share a terminal

tmux shared sockettmateupterm
What it isPlain tmux, as aboveA fork of tmux that shares a session through a relay serverA separate tool that shares a terminal through an SSH relay
NeedsSSH access to the host for each guestA tmate server; the public one is goneThe upterm client and a server; its README uses uptermd.upterm.dev
Status (October 2026)tmux 3.8, currentPublic servers shut down July 2025; last release 2.4.0Separate open-source project
Read-only guestsattach -r / server-access -r (see warning above)Read-only linkNot covered here
Access controlUnix permissions + per-user listSecret session tokenAllowed SSH keys or GitHub/GitLab users

tmate was the easy answer for years: run tmate and send someone an SSH address. Its README now says the public servers (ssh.tmate.io) "were shut down in July 2025, so tmate no longer works out of the box"; a server rewrite is tracked in issue #336, and until then you must run your own tmate-ssh-server. upterm fills the same gap: upterm host shares your terminal and prints an ssh command for the guest, and --authorized-user github:name limits who can join. Both are separate programs, not tmux. Editor-based sharing (for example VS Code Live Share) only covers that editor, not your shells and terminal tools.

Troubleshooting shared sessions

MessageFix
error connecting to /var/tmux/pair (Permission denied)The guest cannot open the socket: not in the group (or not logged in again after usermod), directory not 2770, or socket missing g+rw.
access not allowedFile permissions are fine but tmux's list does not include the guest: server-access -a bob. For a group entry (3.8), the group must be the guest's effective group.
client is read-onlyThe guest is read-only (server-access -l shows R). The host can run server-access -w bob.
error connecting to /var/tmux/pair (No such file or directory)No server on that path: the host's server exited, or the guest typed a different path. Every command needs the same -S.
Window is tiny or full of dotsSee window size.
sessions should be nested with careYou ran tmux inside tmux; see nested sessions.

FAQ

How do two users share a tmux session on the same server?

The host starts tmux on a socket both can reach (tmux -S /var/tmux/pair new -s pair), gives a shared group read/write on it, and on tmux 3.3+ allows the guest with tmux -S /var/tmux/pair server-access -a bob. The guest runs tmux -S /var/tmux/pair attach -t pair. If both use the same Linux account, a plain tmux attach -t pair is enough.

How do I attach to a tmux session read-only?

tmux attach -r -t name. To enforce it for another user, the host runs tmux -S socket server-access -r user. Read-only clients can watch and detach but not type.

Can both people type at the same time?

Yes. Both clients send keys to the same panes, so agree on who drives. Use a grouped session (tmux new -t main -s bob) if you want to work in different windows.

Is tmate still working?

Not out of the box. tmate's public servers were shut down in July 2025 according to its README; you need a self-hosted tmate server. Plain tmux over SSH, or upterm, are the alternatives.

What is a tmux socket?

The Unix socket a tmux server listens on, by default /tmp/tmux-UID/default. -L name picks another socket in that directory and -S path uses any path, which is how you share a server with another user.

Keep learning

Something wrong or out of date on this page? Email hello@tmux.app and we will fix it.