Support

Getting Started

Welcome to rootshell! Here are some quick tips to help you get started with your new terminal emulator.

Local Shell

rootshell includes a built-in local shell that works offline. On macOS, you get full access to your local system shell with all installed utilities and your standard environment. On iOS, the local shell provides a curated set of pre-bundled Unix utilities including ls, cd, pwd, cat, grep, curl, ping, dig, awk, and more—perfect for file management, scripting, and network diagnostics.

SSH Connections

To connect to a remote server via SSH, enter your connection details including host, port (default 22), and username. rootshell supports both password and SSH key authentication. For complex network setups, you can configure jump hosts (bastion servers) to proxy your connection through intermediate servers. Local network hosts using .local addresses are automatically resolved via mDNS.

Tabs & Splits

Open multiple terminal sessions using tabs (Cmd + S) and close them with Cmd + W. Split your current terminal horizontally with Cmd + D or vertically with Cmd + Shift + D. Navigate between splits using Cmd + Option + Arrow keys.

Quick Connect

The quick connect field at the top provides fast access to your servers. Start typing to see autocomplete suggestions from your connection history and configured cloud instances. Host Shorthand patterns (HSS) are also expanded automatically, letting you connect with shortcuts like prod1 instead of typing full hostnames.

The Tab key is your friend—use it to accept autocomplete suggestions quickly. On iOS and iPad without a hardware keyboard, you'll find the Tab key in the keyboard toolbar above the virtual keyboard.

For more on profiles, suggestion sources, and matching modes, see Profiles & Quick Connect below.

Report an Issue

Found a bug or have a feature request? We track issues on GitHub.

Frequently Asked Questions

Profiles & Quick Connect

Profiles are saved connection templates that store everything needed to reach a server in one click. Quick Connect is the unified search field at the top of the app that brings profiles, history, cloud instances, and local network devices together in a single list of suggestions.

Connection Profiles

A profile stores a name, host, port, username, and authentication method (password or SSH key). You can also configure optional extras:

• Jump hosts (bastion servers)
• SSH agent forwarding
• Port forwarding rules
• Automatic tmux attach (see tmux Control Mode)
• A launch command to run on connect

Profiles sync across your devices via iCloud.

Organizing Profiles

• Folders — hierarchical grouping (e.g., Work / Production)
• Tags — cross-cutting labels that span folders
• Color tags — visual color coding for at-a-glance identification
• Icons — custom SF Symbols per profile

Browse all profiles with Cmd + Shift + P.

Quick Connect

The Quick Connect field aggregates suggestions from four sources, shown in priority order:

Suggestions are deduplicated and capped at 15 results.

Autocomplete & Matching

• Tab inserts the current suggestion
• Default: prefix matching — type the beginning of a name or host
• Double-tap Tab or Shift + Tab: switch to substring matching (matches anywhere in the name or host)
• HSS patterns are also expanded — see Host Shorthand below
• On iOS/iPadOS without a hardware keyboard, Tab is in the keyboard toolbar

Connection Protocols

• SSH — standard secure shell, supports all features (agent forwarding, jump hosts, port forwards)
• Mosh — UDP-based, survives network changes and app suspension, ideal for mobile
• tssh — QUIC and KCP-based transport, resilient connections over unreliable networks

Set the protocol per-profile in the profile editor.

tmux Control Mode

rootshell has deep native integration with tmux's control mode (tmux -CC). Instead of tmux painting its windows and panes as text inside a single terminal, rootshell turns every tmux window into a native tab and every pane into a native split. You get full smooth scrolling, native copy and paste, pinch-to-zoom font sizing, and all of the usual tab and split keyboard shortcuts and gestures—no tmux prefix-key gymnastics to switch between windows or panes, and none of the janky redraw scrolling of a normal tmux session. Requires rootshell 1.0.7-101 or later.

Launching Control Mode

Run one of these in any tab on a compatible transport. The tab you launch from becomes the gateway for the session.

The Gateway Tab

The tab you launched from is the gateway for the whole session. Every window and pane in the session you attached to opens as a native tab and split in the current window. Because rootshell tracks the gateway as special, closing the gateway tab detaches the session and closes all of its related tabs. The tmux server keeps running, so you can re-attach later from this device or another one.

What Works

Everything tmux does to its windows and panes is reflected as native tabs and splits, and the sync is two-way: actions you take in rootshell are routed to the server, and changes made by tmux commands—or by another client attached to the same session—show up in rootshell in real time.

• Windows — create, close, rename, reorder, and select. New windows open as native tabs, and renaming a window updates its tab title.
• Panes — split horizontally or vertically, close, toggle zoom, resize, and focus. Each pane maps to a native split, and layout changes reconcile automatically.
• Sessions — switch between sessions from the sessions dashboard; the session you switch to opens focused on its current window.
• Per-window font size — Cmd + +, Cmd + -, and Cmd + 0 scale a whole window's panes together (one size per window).
• Native terminal feel — panes are real terminal views, so selection, copy and paste, and smooth scrollback all work natively—no tmux copy-mode.

Focus stays put: activity on another tmux client attached to the same session won't yank your visible tab. Only your own actions—or a session switch you request—change which tab is selected.

Spotting tmux Tabs

tmux tabs are badged so you can tell them apart at a glance. Each window tab carries a T badge, and the gateway tab carries a star badge. Both are tinted with a color pulled from your active theme's palette, so the exact color follows whatever theme you're using. If you run more than one tmux -CC gateway at the same time, each group gets its own distinct color. These colors are deliberately kept clear of the blue roaming indicator used by tssh and mosh tabs, so a tmux group never looks like a roaming session.

In the Vertical Tab Bar

When you use the vertical tab sidebar, a tmux gateway is shown as a collapsible group with its window tabs indented beneath it; everything else stays flat in tab order.

• The gateway header shows the star badge, the session name, and the connection host and port. A chevron collapses or expands the group (and the collapsed state is remembered), and a window count appears while it's collapsed. Inline buttons let you open a new window, open the sessions dashboard, or close the gateway.
• Window rows are indented under their gateway and carry the same theme-tinted T badge used in the horizontal tab bar.
• Hidden windows collect in a Hidden group at the bottom of the gateway. A window can be hidden without killing it, and the hidden state is saved with the session.
• Reordering — drag a window tab to reorder it within its own gateway group, and the move is routed to the tmux server. Gateway headers themselves aren't draggable, while ordinary tabs can still be dragged freely, including past a whole gateway group. Searching the sidebar auto-expands groups to reveal matches.

Detaching

When you attach, rootshell prints a short menu into the gateway tab:

[ rootshell tmux control mode ]
Press ESC to detach.

Press ESC in the gateway tab to cleanly detach and drop back to your shell on that tab. Closing the gateway tab detaches as well. Either way, the tmux session keeps running on the server so you can re-attach later.

Compatible Transports

Control mode works over a local shell on Mac, SSH, and tssh—transports that carry a byte-accurate stream. Mosh is not supported for control mode, because its UDP state-sync transport can't carry the control-mode protocol; use SSH or tssh instead. Your server needs a build of tmux that supports control mode (-CC).

Recovering After the App Closes

rootshell treats gateway tabs as special so they can survive the app being terminated. If the app is force-quit or relaunched, it restores the gateway and its window tabs as placeholders, forces the terminal parser back into control mode, and tries to re-sync with the running tmux server by finding the protocol framing again. If tmux is still running, your tabs and panes reattach automatically. If tmux is gone—for example, the server exited while rootshell was closed—the re-sync times out after a short wait, the placeholder tabs are removed, and the gateway drops you back to a normal shell.

Siri & Shortcuts

rootshell integrates with the Shortcuts app and Siri, so you can launch connections from automations, the home screen, or by voice.

Open Connection Profile

The Open Connection Profile action connects to any saved profile. It appears in the Shortcuts app under rootshell's actions and accepts the following parameters:

The profile picker in Shortcuts includes search and suggestions, so you can find profiles by name or hostname.

Siri

You can also connect by voice. Siri recognizes phrases like "Open [profile name] in rootshell" and "Connect to [profile name] with rootshell".

Host Shorthand (HSS)

Host Shorthand lets you create quick aliases for your servers using pattern matching. Configure shortcuts in YAML format and store them in the app's Documents directory.

Configuration Example

Create a YAML file with patterns that expand short names to full hostnames:

patterns:
  - short: "^prod(\\d+)$"
    long: "prod#{1}.example.com"
    note: "Production servers"
  - short: "^dev$"
    long: "dev.internal.example.com"
    note: "Development server"

With this configuration, typing prod1 in quick connect expands to prod1.example.com. Capture groups from the regex pattern are available as #{1}, #{2}, etc. in the expansion template.

SSH Agent Forwarding

rootshell supports SSH agent forwarding, allowing you to use your local SSH keys on remote servers without copying private keys. Configure agent forwarding on a per-connection basis in the connection settings.

Approval Modes

Choose how rootshell handles agent signing requests:

• Auto-approve: All signing requests are automatically approved
• Per-session: Approve each key once per terminal session
• Per-request: Prompt for approval on every signing request

You can also restrict which keys are available for forwarding, selecting specific keys instead of exposing your entire keychain to the remote server.

GPG Agent Forwarding

rootshell can act as a GPG agent and forward it over SSH or tssh, so signing requests issued on the remote (signed git commits, gpg --sign, release tag signing, etc.) are handed back to the device, performed locally, and returned to the server. Your GPG private key never leaves the device. Requires rootshell 1.0.6-93 or later.

Key Sources

Two kinds of keys can be forwarded:

• Existing SSH keys — Any key configured under Settings → Connections → SSH Keys can be used for GPG signing with no extra import step, including YubiKey-backed PIV keys. The same key that authenticated your SSH session can also sign commits on the other side. Supports Ed25519, RSA, and ECDSA P-256.
• Imported GPG keys — Standalone signing keys can be added under Settings → Connections → GPG Keys by pasting an ASCII-armored secret block (gpg --export-secret-keys --armor KEYID) or dropping a binary .gpg file. Imported keys must be exported without a passphrase. RSA, Ed25519, and ECDSA P-256/P-384/P-521 signing keys are supported.

Each imported key has a detail screen for renaming, copying the full fingerprint, viewing per-subkey details, or exporting an ASCII-armored public block to paste into gpg --import on the remote.

Per-Connection Settings

GPG agent forwarding is configured per connection. In the connection editor:

• Enable — Toggle GPG agent forwarding for this connection.
• Approval Mode — Choose how signing requests are handled:
  • Auto-approve — All signing requests succeed silently.
  • Per-session — First request prompts; subsequent requests for the same key are approved automatically until disconnect.
  • Per-request — Every signing request shows an approval sheet (with hash preview and remote host).
• Forwarded Keys — Optionally restrict which keys this connection can use; leave empty to forward all configured keys.
• Remote Socket Path — Where the forwarded agent socket appears on the server. Defaults to $HOME/.gnupg/S.gpg-agent; point your remote gpg at it (e.g., export GNUPGHOME=$HOME/.gnupg).

Transport Support

GPG agent forwarding rides on a reverse Unix-socket forward channel that only SSH and tssh expose, so the option is shown for those protocols only. Mosh sessions hide the toggle, since UDP cannot carry the forward.

Decryption (PKDECRYPT)

Decryption support — letting the remote gpg --decrypt ask the device to unwrap session keys for RSA, ECDH Curve25519, ECDH P-256, and X25519 — is included in rootshell 1.0.6-94 and later. When available, it uses the same per-connection enable toggle and approval mode as signing; sign and decrypt approvals are tracked separately in per-session mode, so approving a signing operation never silently approves a decryption.

Location Diary

iOS suspends background apps after a short period, which drops TCP-based connections like SSH, Kubernetes, and Cloud Console sessions. Location Diary uses iOS location services to keep rootshell active in the background, preserving your sessions while you switch between apps.

Resilient transports like Mosh and tssh use UDP state-sync that survives app suspension and network changes—they don't need Location Diary at all.

Modes

• Off — Location tracking disabled. Background sessions may disconnect when the app is suspended.
• Session Only — Manually enabled; stays active until you turn it off or close the app. Not remembered across app restarts.
• Auto During Active Sessions (recommended) — Automatically enables when you have SSH, Kubernetes, or Cloud Console sessions. Automatically pauses when all those sessions end. Remembered across restarts.

Which Sessions Need It

• Needs Location Diary: SSH, Kubernetes, Cloud Console, SSH started from local shell — these use TCP connections that the OS will close when the app is suspended.
• Doesn't need it: Mosh, tssh — their UDP state-sync protocol survives network changes and app suspension. Local shell also doesn't need it.

Privacy: Location entries are automatically pruned after 5 minutes.

Touch Gestures

rootshell supports two touch interaction modes, toggled in Settings → Terminal.

Scroll Mode (default)

Legacy Mode

Mouse capture apps (tmux, vim): In Scroll Mode, single-finger pan sends scroll events to the running application, and long press acts as mouse click-and-drag.

Mod-Tap

Mod-Tap lets a single key perform different actions depending on whether it's tapped quickly or held down. The classic example: Caps Lock sends Escape on tap, acts as Control on hold.

Presets

• Caps Lock → Escape / Control — Tap sends Escape, hold acts as Control.
• Escape → Escape / Control — For users who already remapped Caps Lock to Escape at the OS level.

Custom Rules

• Source keys: any modifier key, letter, digit, or symbol
• Tap actions: Escape, Backspace, Return, Tab, Space, Delete, arrow keys, Home/End/Page Up/Down, or a custom text sequence
• Hold modifiers: Control, Alt, Shift, or Command
• Hold threshold: adjustable from 150ms to 300ms (default 200ms)

Caps Lock LED note: The keyboard LED still toggles when Caps Lock is pressed. To avoid this, remap Caps Lock to Escape in iOS Settings → Keyboard → Hardware Keyboard → Modifier Keys, then create a mod-tap rule for Escape instead.

Keyboard Shortcuts

rootshell supports extensive keyboard shortcuts when using an external keyboard:

Clipboard

Tabs & Windows

Split Windows

View & Display

Terminal