How to Use tmux on iOS
Mobile SSH has one recurring annoyance: the connection drops the moment the app backgrounds, the network switches from Wi-Fi to cellular, or the screen locks — and your running command dies with it. tmux fixes this by keeping your shell session alive on the server, detached from any single connection. Here's how tmux works, and how to set up GateShell so it reattaches automatically every time.
Step by step
- 1
Understand what tmux actually does
tmux is a terminal multiplexer that runs on your server, not on your phone. When you start a tmux session, your shell keeps running inside it even if your SSH connection drops. Reconnect later and re-attach to the same session — your running process, scrollback, and open panes are exactly where you left them. This matters more on iOS than on a laptop, because iOS suspends network connections aggressively when an app is backgrounded or the screen locks.
- 2
Install tmux on your server (if it isn't already)
Most modern Linux distributions ship tmux or have it in the default package repos. On Debian/Ubuntu run "sudo apt install tmux"; on Fedora/RHEL run "sudo dnf install tmux"; on Alpine run "apk add tmux". Check with "tmux -V" first — many cloud images already include it.
- 3
Start or attach to a tmux session manually
From any SSH session, run "tmux new -s work" to start a new named session, or "tmux attach -t work" to reattach to one that's already running. Detach without killing it using the key sequence Ctrl-b then d. The session and everything running inside it keeps going on the server after you detach or disconnect.
- 4
Enable tmux auto-attach in GateShell
Open a server's settings in GateShell, go to the Auto-Reconnect & tmux section, and turn on the "tmux Auto-Attach" toggle. Set a "tmux Session Name" (it defaults to "gateshell"). From then on, connecting to that server automatically creates the session on first connect and reattaches to it on every subsequent connection — no manual "tmux attach" needed after the app backgrounds, the network drops, or you reopen GateShell later.
- 5
Verify it survives a disconnect
Start a long-running command (for example "top" or a build), then background GateShell or lock your phone for a minute. Reopen the app and reconnect to the server — with tmux auto-attach on, you should land back in the same session with that command still running, exactly where you left it.
Frequently asked questions
Do I need tmux if I'm using GateShell?+
You don't strictly need it for short commands, but for anything long-running — builds, log tailing, database migrations — tmux is what keeps the process alive when iOS suspends your connection in the background. GateShell's auto-attach removes the manual step of reattaching yourself.
What does GateShell's tmux auto-attach actually do?+
It's a per-server setting that runs the tmux attach-or-create command automatically whenever you connect. Instead of typing "tmux attach -t work" every time, GateShell issues it for you as part of connecting, using the session name you configured.
What's the difference between detaching and disconnecting?+
Detaching (Ctrl-b then d) intentionally leaves the tmux session running and returns you to your outer shell. Disconnecting — losing SSH due to network loss or backgrounding — leaves the tmux session running too, since tmux lives on the server independent of any one SSH connection. Either way, reattaching brings you back to the same session.
Does this work with screen instead of tmux?+
GNU screen behaves similarly and the same reconnect problem applies, but GateShell's built-in auto-attach setting is specifically for tmux. If your server only has screen installed, you can still add a manual startup command in GateShell's server settings to attach to it.
Try it in GateShell
GateShell is a zero-backend SSH client for iPhone, iPad, and Mac — no vendor cloud, no accounts, no telemetry. Everything above works out of the box.
Guide reflects GateShell's shipped features as of July 2026. Steps assume basic familiarity with SSH and the command line; server-side commands may vary by distribution. All product names, logos, and brands are property of their respective owners.