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
• 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.

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