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

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 Trzsz 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, Trzsz — 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