Learn Tmux - Multi-server & Shared Session

#Introduction

In episode 18 we built a calm remote workflow: sessions surviving dropped connections, mosh for slow networks, and bastion as a gateway. All of that solved the problem of one server. Now it's time to answer a much wilder question: what if what you need to manage isn't one server, but dozens?

In modern infrastructure — Kubernetes clusters without full automation, application server fleets, or edge device fleets — routine work like checking package versions, restarting services, or syncing configs must run against many machines at once. Doing it one by one over SSH isn't just slow, it's error-prone: a command typed twenty times is guaranteed to differ on some attempts.

This episode covers two big tmux capabilities at the infrastructure level: broadcasting commands to many servers in one motion, and shared sessions for real-time collaboration — from pair programming to read-only observation. All examples refer to tmux 3.7b as the latest stable version.

#Broadcasting Commands to Many Servers

Imagine you're the person who must announce the same thing to twenty rooms. Knocking on each door one by one is exhausting and inconsistent; a megaphone is the answer. In the server context, tmux is that megaphone — with several ways to use it, depending on how much control you need.

#tmux-cssh

tmux-cssh is the most direct tool: it opens one tmux session containing one window per host, then syncs input to all those windows. Installing it is just copying one script into PATH:

git clone https://github.com/peikk0/tmux-cssh.git
sudo cp tmux-cssh/tmux-cssh /usr/local/bin/

Using it accepts a list of hosts as arguments, complete with brace expansion support:

tmux-cssh -o '-p 2222 -l deploy' web-01 web-02 web-03

The -o flag forwards extra arguments to SSH (e.g. user and port), and -c creates a new window in the running session instead of creating a new one. Because syncing is window-based, you can move between windows to check each host's output, then return to broadcast mode. Add a shortcut to toggle sync in ~/.tmux.conf:

bind = setw synchronize-panes

#tmux-cluster

tmux-cluster is for those who need structured server groups. It's fully compatible with the clusterssh config file format — the standard tool for cluster administration — so you can define a hierarchy: a web cluster containing three hosts, an all cluster containing the union of web and db.

web fleet-web-01 fleet-web-02 fleet-web-03
db fleet-db-01 fleet-db-02
all web db

With that file, running tmc web opens a session named cluster-web with one window per host. If installed as a TPM plugin, prefix + C brings up a prompt to choose a cluster interactively. tmux-cluster's advantage over other alternatives: it supports cluster hierarchy and produces the command list in a single source-file call, making it very fast even for dozens of hosts.

#Pure pattern with synchronize-panes

Before adding any tool, know that tmux already provides built-in broadcasting: the window option synchronize-panes. When active, input typed in one pane is copied to all panes in the same window. This pattern is the foundation tmux-cssh uses under the hood.

To use it comfortably daily, bind the toggle and give it a visual indicator when sync mode is active — this indicator saves you from accidental broadcasts:

bind s setw synchronize-panes
setw -g window-status-current-format '#{?pane_synchronized,#[bg=red],}'
setw -g window-status-format '#{?pane_synchronized,#[bg=red],}'

How to use it: create a window, split into one pane per server, run ssh in each pane, then press prefix + s to enable syncing. Everything you type — including SSH passwords if authentication is still manual — is forwarded to all panes. The format lines above make the window name's background turn red while sync is active, so you won't forget broadcast mode is on.

#Shared Sessions and Pair Programming

tmux is multi-client: many terminals can attach to the same session simultaneously, and all of them see the identical screen. That's the engine behind real-time collaboration — long before modern collaboration tools, engineers were already pair programming via shared tmux sessions.

The simplest experiment: open two terminals, run the following commands in each:

tmux new -s pair

tmux attach -t pair

tmux attach -t pair -r

tmux list-clients

Both clients now see the same screen. Whatever client A types instantly appears on client B's screen — and vice versa. This is pair programming in its rawest, most direct form: no sync lag, no cloud service, just two terminals sharing one session.

Attaching without flags means read-write mode: you can type and execute commands. Add the -r flag to attach read-only — the client still sees all activity but can't type.

tmux list-clients shows all attached clients along with their modes — the fastest way to realize someone else is on the same session. This is a habit you should always run before working in a shared session.

#Managing Permissions on Shared Sessions

By default, tmux separates access by user: the tmux server creates a socket at /tmp/tmux-<uid>/default, and only users with the same uid can attach. That means sharing a session among teammates on one account (e.g. a shared deploy user) already works with no extra config — just share the session name.

To share across users — e.g. between an ops user and a dev user — the socket must be set up so both can access it. One way is starting the server with a special socket path and setting group permissions:

tmux -S /tmp/tmux-shared new -s shared
chgrp ops /tmp/tmux-shared
chmod 660 /tmp/tmux-shared

Another user in the ops group can then attach with tmux -S /tmp/tmux-shared attach. Note that this is a very permissive action: anyone who can read the socket can also send commands to that session.

#Orchestration with the Nested Tmux Pattern

Combining broadcast and shared sessions produces one pattern very popular in operations teams: a local orchestration session, one window per server, and inside each window you enter the tmux running on that server. This pattern combines the broadcast of episode 18 (nested tmux) with the syncing of this episode.

tmux new -s fleet -n web-01
tmux new-window -n web-02
tmux new-window -n web-03

In each window, SSH into the respective server then attach to the remote tmux session. Once all windows are connected, activate prefix + s — and now broadcast input flows from your local screen, through the remote tmux layer, executing on all servers in unison. This pattern's advantage over tmux-cssh: you keep full control over tmux on each server, including each one's own scrollback and status bar.

#Common Pitfalls

1. Broadcasting without verifying the host list. One misfired command — especially a destructive one like systemctl stop — can spread to all servers at once. Always check the host list before broadcasting, and test the command in a single pane first.
2. Forgetting to turn off synchronize-panes. Still-active sync mode will forward follow-up commands — including private ones — to all panes. Get in the habit of turning it off right away (prefix + s) after a batch of work finishes, and use the color indicator from the earlier section.
3. Read-write attaching to a session under review. The moment you enter read-write, every keystroke also types on your teammate's screen. If the goal is only observation, use tmux attach -t pair -r.
4. Sharing a session without restricting access. Too-open socket permissions mean anyone can execute commands — including closing the session. Restrict with groups and read-only mode as needed.
5. Running interactive editors through broadcast. nvim or vim in broadcast mode shows a garbled screen on all panes and input becomes uncontrollable. Editors are for single-pane work only.
6. Not checking tmux list-clients. Without knowing who's connected, you could send secret commands or break someone else's work. Make client checking a habit on shared sessions.

#Conclusion

This episode took tmux from a personal tool to a team and infrastructure tool. You understand three ways to broadcast to many servers — tmux-cssh for quick adoption, tmux-cluster for structured clusters, and synchronize-panes as a pure, tool-free foundation. You also mastered shared sessions for real-time collaboration, the difference between read-write and read-only attach, how to set up socket permissions, and the nested tmux pattern for cross-layer orchestration.

Key points to take away:

• synchronize-panes is tmux's built-in broadcast engine; pair it with a visual indicator so you don't forget it's on.
• Shared sessions work by default for the same user; cross-user requires a deliberately risk-aware socket permission setup.
• -r turns an active collaborator into a spectator — suitable for review and mentoring.
• Broadcasts crossing nested tmux use send-prefix to control the inner layer.

The more control you have, the greater the responsibility. In episode 20 we'll cover security and hardening best practices — locking sessions with lock-session, setting lock-after-time, keeping secrets from leaking into the environment, and safe practices for running tmux on production servers. See you in episode 20!