Guide · tmux

How to attach a tmux session from your phone

tmux keeps your terminal sessions running on the server after you disconnect: long builds, coding agents, log tails, and shells all stay alive. This guide walks through attaching to those sessions from an iPhone or iPad with QuickTUI, reattaching after a drop, and starting a fresh session when you need one.

The idea behind tmux persistence is simple: the session lives on the machine, not on the client. You attach a view to it, detach, and the work keeps going. QuickTUI is a native app (plus a browser client) that attaches to real tmux on your own server, so the session you open on your phone is the same one you left in the terminal at your desk.

Install the server

Run the installer on the machine where your tmux sessions live. It sets up the QuickTUI service and can install tmux 3.2+ for you if it is missing.

curl -fsSL https://quicktui.ai/q.sh | sh

irm https://quicktui.ai/q.ps1 | iex

The connection is direct by default, so your code and keys never pass through our servers. A single server is free with full features; QuickTUI Pro is a one-time purchase that unlocks unlimited server profiles.

Pair the app

Start the pairing code on the server and scan it once:

quicktui-server --qrcode

Open the QuickTUI app on your iPhone or iPad, scan the QR code, and the server is added. You can also add it manually by URL and token if you prefer to type the details in.

Open, attach, and reattach

• Attach to a running session. QuickTUI lists the tmux sessions on the server; tap one and you drop straight into the live view with scrollback intact.
• Reattach after a disconnect. Switching Wi-Fi to LTE or 5G, backgrounding the app, or losing signal does not end the session. The session keeper holds your place, and reopening the app puts you back where you were.
• Create a new session. Run tmux new-session -s work on the server, or open a shell in the app and start it there; the named session then shows up in the list to attach from any device.

FAQ

Does the session survive if my phone loses connection?

Yes. tmux keeps the session running on the server, and QuickTUI's session keeper reattaches after a network change, a dropped connection, or an app restart, so you pick up where you left off.

How do I start a new tmux session?

Run tmux new-session -s name on the server, or open a shell in the app and start it there. The named session appears in QuickTUI's list to attach from iPhone, iPad, or a browser.

Do I need SSH?

No. QuickTUI talks to its own lightweight server over HTTP/WebSocket. You can reach it on your LAN, over a VPN or tunnel such as Tailscale or Cloudflare Tunnel, or a public address.