>_
RemoteConsoleSSH|Docs
Home

Install tmux

tmux is a terminal multiplexer -- a program that runs on the server and keeps your terminal sessions alive even when you disconnect. For mobile SSH, this is the single most important tool you can install.

Why tmux Matters for Mobile SSH

Mobile devices lose their network connection constantly. Your phone switches from Wi-Fi to cellular. You lock the screen. You switch to another app. iOS suspends background processes aggressively. Any of these events can kill your SSH connection.

Without tmux, a dropped connection means your session is gone. Whatever command was running is terminated. Whatever you had on screen disappears. You have to reconnect and start over.

With tmux, nothing is lost. Your session continues running on the server regardless of what happens to your phone. When you reconnect, you pick up exactly where you left off -- same output on screen, same running processes, same working directory.

💡

Tip

Think of tmux like a browser tab that lives on the server. Close your phone, come back an hour later, and everything is exactly where you left it. You can even start a session on your phone and pick it up later on a laptop.

How RemoteConsoleSSH Uses tmux

RemoteConsoleSSH has built-in tmux integration that works automatically:

  • Auto-detection -- When you connect to a server, the app checks if tmux is installed. If it is, the app uses it automatically. No configuration needed.
  • Session management -- The app creates a tmux session named remoteconsole-{connection-id} for each connection. This gives each connection its own isolated session.
  • Automatic reconnection -- If your connection drops, the app attempts to reconnect with exponential backoff: 2 seconds, then 4, 8, 16, and finally 32 seconds between retries. Up to 5 attempts.
  • Session reattachment -- On reconnect, the app reattaches to your existing tmux session. Your terminal output, running processes, and shell state are all preserved.
  • Multi-device access -- You can connect to the same tmux session from multiple devices simultaneously. Start something on your phone, check on it from your laptop.
ℹ️

Info

The reconnection flow works like this: connection drops, the app enters a reconnecting state (preserving your tmux session name), retries with exponential backoff, re-establishes the SSH connection, reattaches to your tmux session, and your terminal buffer is restored from tmux. All of this happens automatically.

Install tmux

Install tmux on the machine you connect to (your Mac, Linux server, etc.), not on your phone.

Install with Homebrew

If you have Homebrew installed (and you should on macOS):

brew install tmux

If you do not have Homebrew, install it first:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Then run brew install tmux.

Verify Installation

tmux -V

You should see something like tmux 3.4 or later.

Verify the Installation

After installing, confirm tmux is available:

tmux -V

This should print the version number, such as tmux 3.4. If you get command not found, the installation did not succeed or tmux is not in your PATH.

You can also do a quick smoke test:

# Start a new tmux session
tmux new-session -s test
 
# You should see a green status bar at the bottom
# Type some commands, then detach:
# Press Ctrl+B, then D
 
# Reattach to the session
tmux attach-session -t test
 
# Clean up
tmux kill-session -t test

If all of that works, tmux is properly installed and RemoteConsoleSSH will detect and use it automatically on your next connection.

What Happens Without tmux

RemoteConsoleSSH does not require tmux. The app works fine without it. But here is what you lose:

With tmuxWithout tmux
Sessions survive disconnectionsSessions are lost when the connection drops
Reconnect picks up where you left offReconnect starts a fresh shell
Running commands continue in the backgroundRunning commands are terminated on disconnect
Access the same session from multiple devicesEach device gets its own independent session
Terminal output is preserved across reconnectsPrevious output is gone after reconnection
⚠️

Warning

Without tmux, any network interruption -- switching from Wi-Fi to cellular, locking your phone, or even a brief signal drop -- will terminate your session and any commands that were running. For mobile SSH, this is a significant limitation. We strongly recommend installing tmux.

Basic tmux Usage

While RemoteConsoleSSH manages tmux sessions automatically, it helps to know the basics in case you want to work with tmux directly.

Key Concepts

  • Session -- A tmux session is a collection of windows. RemoteConsoleSSH creates one session per connection.
  • Window -- Each session can have multiple windows (like browser tabs). You can switch between them.
  • Pane -- A window can be split into panes for side-by-side terminal views.

Essential Commands

All tmux keyboard shortcuts start with the prefix key, which is Ctrl+B by default. Press Ctrl+B, release, then press the next key.

ActionKeysDescription
Detach from sessionCtrl+B, then dLeaves the session running in the background
Create a new windowCtrl+B, then cOpens a new terminal tab within the session
Next windowCtrl+B, then nSwitches to the next window
Previous windowCtrl+B, then pSwitches to the previous window
Split horizontallyCtrl+B, then "Splits the current pane top/bottom
Split verticallyCtrl+B, then %Splits the current pane left/right
Switch panesCtrl+B, then arrow keyMoves focus between panes
Scroll modeCtrl+B, then [Enter scroll mode to view history (press q to exit)

Command-Line Operations

# List all sessions
tmux list-sessions
 
# Create a new named session
tmux new-session -s my-session
 
# Attach to an existing session
tmux attach-session -t my-session
 
# Kill a session
tmux kill-session -t my-session
ℹ️

Info

You do not need to memorize any of this to use RemoteConsoleSSH. The app handles session creation, attachment, and reconnection automatically. These commands are here for users who want to manage tmux sessions manually or from another SSH client.

Next Steps