How to Access Your tmux Sessions From Your iPhone

If you're a developer who uses tmux, you've probably had this thought: "I have a tmux session running on my Mac with 6 windows, a specific layout, and three long-running processes. I want to check on it from my iPhone."

Accessing tmux from your iPhone is absolutely doable, but the experience varies wildly depending on how you connect. Some setups are seamless. Others make you want to throw your phone.

This guide covers the practical side: how to connect, what works, what doesn't, and how to make tmux actually usable on a phone screen.

Quick Background: Why tmux Matters for Mobile

tmux is a terminal multiplexer. It lets you:

Run multiple terminal sessions in one window (panes and windows)
Detach from a session and reattach later — even from a different device
Keep processes running after disconnecting

That last point is critical for mobile use. iPhone connections are unreliable by nature — you switch between WiFi and cellular, the app gets backgrounded, the connection drops. Without tmux, every disconnection kills your running processes.

With tmux, a disconnection is a non-event. Your session keeps running on the Mac. When you reconnect, you attach and pick up exactly where you left off.

How to Connect: Your Options

Option A: SSH Client + Port Forwarding or VPN

The traditional stack:

Set up SSH access to your Mac (see our SSH from iPhone guide for details)
Install an SSH client on your iPhone (Termius, Blink Shell, Prompt)
SSH in and run tmux attach

This works but requires solving the connectivity problem first — port forwarding, Tailscale, or similar. The SSH connection itself is also subject to dropping when your phone switches networks.

Blink Shell deserves a special mention here. It supports mosh (Mobile Shell), a protocol designed for roaming connections. Mosh handles network switches gracefully — if you switch from WiFi to cellular, the session continues without reconnecting. The catch: mosh requires a UDP port exposed on your Mac, which means port forwarding.

Option B: Seasalt

Seasalt's terminal automatically detects running tmux sessions on your Mac. When you open a terminal in Seasalt, if tmux is running, it offers to attach to an existing session.

No SSH setup, no port forwarding, no VPN. The terminal renders natively on the iPhone with proper font rendering and scrollback. Connection drops are handled by the relay — when you reopen the app, you're reconnected to your tmux session.

For a broader look at remote terminal options, see Remote Terminal Access on iOS.

Making tmux Usable on a Phone Screen

Here's where most people hit frustration. tmux was designed for large monitors. Using it on a 6.1-inch screen requires adjustments.

Resize Handling

When you attach to a tmux session from a device with a different terminal size, tmux resizes the session to the smallest connected client. If you're still attached on your Mac (with a large terminal), your phone will see a small viewport surrounded by dots.

Solution: Detach from the Mac first, or use:

tmux attach -d -t mysession

The -d flag detaches other clients, so the session resizes to your phone's terminal dimensions.

Alternatively, use aggressive-resize:

# In ~/.tmux.conf
set-option -g aggressive-resize on

This makes tmux resize each window independently based on the smallest client *viewing that window*, rather than the smallest client attached to the session.

Simplify Your Layout for Mobile

Your usual 4-pane tmux layout with vim on the left and tests on the right is not going to work on a phone. When you know you'll be checking from mobile:

# Create a simple single-pane window for mobile
tmux new-window -n mobile

Or better, create a dedicated mobile-friendly session:

# In ~/.bashrc or ~/.zshrc
alias tmux-mobile='tmux new-session -d -s mobile -x 80 -y 24 2>/dev/null; tmux attach -t mobile'

tmux Key Bindings on iPhone

The default tmux prefix is Ctrl-b, which requires holding two keys simultaneously. On an iPhone software keyboard, this is awkward.

Solutions:

Remap the prefix to something easier to hit on mobile:

``bash # Use Ctrl-a instead (screen-style) set-option -g prefix C-a unbind C-b bind C-a send-prefix ``

Use an app with a dedicated Ctrl row. Blink Shell and Termius both provide an extra keyboard row with Ctrl, Esc, Tab, and arrow keys. Seasalt also includes this.

External keyboard. A Bluetooth keyboard makes tmux on iPhone genuinely comfortable. Even Apple's Magic Keyboard works well.

Useful tmux Settings for Mobile

Add these to your ~/.tmux.conf:

# Increase scrollback buffer (you'll want this on a small screen)
set-option -g history-limit 50000

# Enable mouse mode (for scrolling and pane selection with touch)
set-option -g mouse on

# Shorter escape-time (reduces delay after hitting Escape)
set-option -sg escape-time 10

# Status bar — keep it minimal on mobile
set-option -g status-left "[#S] "
set-option -g status-right "%H:%M"
set-option -g status-left-length 20

Mouse mode is especially important for mobile — it lets you scroll through output with swipe gestures in apps that support it.

Common Workflows

Monitoring a build or deploy

# On your Mac, before leaving:
tmux new-session -d -s build
tmux send-keys -t build 'npm run build && echo "DONE" || echo "FAILED"' Enter

# From your iPhone:
tmux attach -t build
# See the output, check if it finished

Checking on a long-running process

# Attach and check
tmux attach -d -t mysession

# Switch to the window running your process
# Ctrl-b + 2 (or whatever window number)

# Check output, then detach
# Ctrl-b + d

Quick git operations

tmux attach -d -t dev
git status
git log --oneline -5
git diff --stat
# Detach when done: Ctrl-b + d

Troubleshooting

"sessions should be nested with care" — This means you're trying to run tmux inside tmux. Your iPhone terminal might have started a new tmux session instead of attaching. Use tmux attach -t sessionname explicitly.

"no sessions" — tmux isn't running on your Mac. You need to start it before you can attach remotely.

Garbled display after attach — Terminal size mismatch. Detach other clients with tmux attach -d or run tmux refresh-client.

Can't scroll — Enable mouse mode (set -g mouse on) or use Ctrl-b [ to enter copy mode, then scroll with arrow keys or Page Up.

Try Seasalt Free

If you need persistent, encrypted terminal and file access from your iPhone to your Mac — with zero configuration and no open ports — that's exactly what Seasalt is built for.

Download free for macOS →

macOS 13+ · Apple Silicon & Intel · No credit card required