Tmux Auto-Attach

ZestSSH supports a per-connection startup command that runs automatically when the SSH session connects. The most common use for this is automatically attaching to (or creating) a tmux session, so your terminal state persists even if the SSH connection drops.

Why Tmux Matters on Mobile

Mobile SSH sessions are inherently unstable. iOS aggressively suspends background apps, and Android may kill network connections to save battery. Without tmux or a similar terminal multiplexer, losing the connection means losing everything running in your terminal: the command you were watching, the file you were editing, the build in progress.

With tmux auto-attach, ZestSSH reconnects and reattaches to the same tmux session. Your terminal looks exactly as you left it — scrollback intact, running processes uninterrupted.

Setting Up a Startup Command

1. Open a connection’s edit screen.
2. Scroll to the Startup Command field.
3. Enter a tmux command. Common options:

Attach or create a named session:

tmux new-session -A -s main

This creates a session called “main” if it does not exist, or attaches to it if it does. The -A flag handles both cases in a single command.

Attach to any existing session, or create one:

tmux attach || tmux new-session

Use a specific session name per server:

tmux new-session -A -s zestssh

4. Save the connection. The next time you connect, the startup command runs immediately after the shell prompt loads.

How It Works

The startup command is stored in the connection’s startupCommand field in the database (nullable text column). When ZestSSH establishes an SSH session, the startup command is sent to the shell after environment variables are injected. It runs in the same pseudo-terminal that the user interacts with, so the tmux session’s output replaces the initial shell.

The startup command is plain text — it can be any valid shell command, not just tmux. You could use it to cd into a project directory, start screen, source a dotfile, or run an interactive tool.

Installing Tmux on the Server

If your server does not have tmux installed:

Debian / Ubuntu:

sudo apt update && sudo apt install -y tmux

RHEL / Fedora / AlmaLinux:

sudo dnf install -y tmux

Alpine:

sudo apk add tmux

macOS (Homebrew):

brew install tmux

Verify the installation with tmux -V. Any version 2.x or later works well with ZestSSH.

Recommended Tmux Configuration

A minimal ~/.tmux.conf for mobile-friendly use:

# Enable mouse support (scrolling, pane selection)
set -g mouse on

# Increase scrollback history
set -g history-limit 10000

# Start windows and panes at index 1 (easier to reach on mobile)
set -g base-index 1
setw -g pane-base-index 1

# Reduce escape delay (improves responsiveness)
set -sg escape-time 10

Screen as an Alternative

If you prefer GNU Screen over tmux, the startup command works the same way:

screen -dR main

This detaches any existing “main” session and reattaches to it, or creates a new one if none exists. ZestSSH’s built-in snippet library includes dynamic variables for both tmux and screen sessions ($[TMUX] and $[SCREEN]).

Cloud Sync

The startup command field is included in cloud sync exports, so your tmux configuration follows your connections across devices.

Limitations

• The startup command runs every time you connect. If your tmux session is already attached from another client, the -A flag handles this gracefully by reattaching. Without -A, you may get a “session already attached” error.
• The startup command is not executed during automation/headless connections (API-triggered commands use SSHClient.execute() which runs a single command without a PTY by default).
• On iOS, the startup command cannot prevent the system from suspending ZestSSH in the background. Tmux keeps the server-side session alive, but the app itself may need to reconnect when you return to it.