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.
On this page
- Why pair in tmux?
- Method 1: one shared account
- Method 2: separate accounts and a shared socket
- Read-only observers
- Work in different windows at the same time: grouped sessions
- Window size when screens differ
- tmux sockets explained: -L, -S and $TMUX
- tmux on a remote server over SSH
- tmux vs tmate and other ways to share a terminal
- Troubleshooting shared sessions
- FAQ
Quick answer
How do two users share a tmux session?
- Same Linux account: host runs
tmux new -s pair, guest SSHes in and runstmux attach -t pair. - Different accounts: host runs
tmux -S /var/tmux/pair new -s pair, gives the socket group read/write, and runstmux -S /var/tmux/pair server-access -a bob; Bob runstmux -S /var/tmux/pair attach -t pair. - Watch only:
server-access -r bob(enforced by the host) orattach -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.
# Start a named session
tmux new -s pair# Log in as the same user and attach
ssh dev@pairbox.example.com
tmux attach -t pairEither of you can detach (Ctrl+b d) without affecting the other. To see who is attached, run tmux list-clients.
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:
# 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
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}'"'"'' EnterA 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:
# 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-size | Rule | Window became |
|---|---|---|
latest (default) | Size of the client with the most recent activity | 80×23 (the small client was newest) |
smallest | Fits every client | 80×23 |
largest | Fits the biggest; others see only part | 120×39 |
smallest, small client with attach -r | Read-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 run | Socket (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/pair | Exactly that path, which is what makes sharing possible |
Any tmux command inside a pane | The 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:
# 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 socket | tmate | upterm | |
|---|---|---|---|
| What it is | Plain tmux, as above | A fork of tmux that shares a session through a relay server | A separate tool that shares a terminal through an SSH relay |
| Needs | SSH access to the host for each guest | A tmate server; the public one is gone | The upterm client and a server; its README uses uptermd.upterm.dev |
| Status (October 2026) | tmux 3.8, current | Public servers shut down July 2025; last release 2.4.0 | Separate open-source project |
| Read-only guests | attach -r / server-access -r (see warning above) | Read-only link | Not covered here |
| Access control | Unix permissions + per-user list | Secret session token | Allowed 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
| Message | Fix |
|---|---|
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 allowed | File 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-only | The 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 dots | See window size. |
sessions should be nested with care | You 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.