User Guide

Everything you need to get the most out of Sudo.

Getting started

Sudo combines SSH terminal, SFTP browser, Git client, and code editor in one app. The main screen is a split sidebar — SSH Hosts on top, Git Repositories below. Tap any host to open a terminal session; tap any repository to open its Git view.

Your first SSH connection

1. Tap + Add Host in the SSH Hosts sidebar.
2. Enter a Name (optional label), Hostname (IP or domain), Port (default 22), and Username.
3. Choose Auth: Password for a quick start, or select an SSH key you've generated in Settings.
4. Tap Save, then tap the host row to connect.

Free vs Pro

The free tier is fully functional for light use:

• Free: 2 saved hosts, 2 concurrent sessions, full SSH terminal, Git client, 6 themes
• Pro ($39.99 one-time): unlimited hosts, 8 sessions, SFTP, server health monitor, all future Pro features
• Annual Pass ($9.99/year): same Pro access, plus new features as they ship

Upgrade via Settings → Upgrade to Pro, or tap the paywall when you hit a limit. You can restore purchases any time from the same screen.

Managing hosts

Hosts live in the SSH Hosts sidebar. Swipe left on a host row to edit or delete. Long-press to reorder (iPad) or use Edit mode (iPhone).

Each host stores its credential in the iOS Keychain, not in the JSON config — your password or private key never appears in any file or iCloud document.

SSH keys

Go to Settings → SSH Keys to manage keys. Three generation options:

• Ed25519 — recommended default. Fast, compact, widely supported.
• ECDSA P-256 — compatible with hardware security keys and most servers.
• Secure Enclave P-256 — the private key is generated inside the device's Secure Enclave chip and can never leave it. Not available on simulator.

After generating a key, tap it to copy the public key in authorized_keys format, then paste it into ~/.ssh/authorized_keys on your server. Or let the auto-setup banner do it for you on first connect.

Sessions & tabs

Each open connection appears as a tab at the top of the detail pane. Tap a tab to switch. Tap ✕ (or press ⌘W) to close. You can have up to 2 simultaneous sessions on the free tier and 8 on Pro.

Keyboard bar

The keyboard bar appears above the software keyboard (and at the bottom of the screen when the keyboard is hidden). It provides:

• Control keys: ESC, TAB, ^C, ^D, ^Z
• Arrow keys: ← ↓ ↑ →
• Special chars: ~, |, -
• Buttons: Snippets, Tunnel, Files, Code, Stats

The bar collapses to a drag handle when you swipe it down, and reappears on swipe-up or tap.

Snippets

Save commands you type frequently. Tap Snippets in the keyboard bar to insert one into the terminal. Manage your snippet library in Settings → Snippets — drag to reorder, swipe to delete.

Port forwarding

Tap Tunnel in the keyboard bar to manage local TCP tunnels for the current session. Each tunnel forwards a local port on your device to a remote host:port through the SSH connection.

Example — access a web server on your remote host from Safari:

1. In the Tunnel sheet, tap +.
2. Set Local Port: 8080, Remote Host: localhost, Remote Port: 80.
3. Open Safari → http://localhost:8080.

Jump hosts (bastion servers)

When editing a host, enable Jump Host and enter the bastion server details. Sudo opens an SSH tunnel through the jump host and connects the inner SSH session over it — equivalent to ssh -J jump@bastion user@target.

Mosh

Mosh (mobile shell) maintains your session over UDP even when your IP address changes or the connection is briefly interrupted — ideal for trains, cafés, or switching between Wi-Fi and cellular.

Enable it per-host: Edit Host → Use Mosh. Requires mosh-server installed on the remote machine (apt install mosh or brew install mosh).

Server health monitor

Tap Stats in the keyboard bar (Pro feature) to see real-time CPU load, RAM usage, disk usage, and uptime — polled via SSH exec, no daemon or agent needed on the server.

SFTP browser

Tap Files in the keyboard bar to open the SFTP browser for the current session. You can:

• Navigate directories by tapping folder rows.
• Preview text files (≤ 2 MB), images (≤ 10 MB), or get info on binary files.
• Upload files from the Files.app picker or photo library (long-press the upload button for options).
• Enter multi-select mode (tap the checkmark toolbar button) to batch-download or batch-delete.

Files.app integration

Each SSH host you've saved appears as a location in the system Files.app sidebar — no extra setup required. Browse and download files from any app that uses the document picker.

Cloning a repository

Tap + in the Git Repositories sidebar. Enter the clone URL:

• HTTPS: https://github.com/user/repo.git — enter your username and a personal access token (GitHub PAT) when prompted.
• SSH: git@github.com:user/repo.git — select an SSH key from your keychain. Make sure the corresponding public key is added to your GitHub/GitLab account.

Cloned repositories are stored in Documents/Repositories/ and are accessible from Files.app.

Daily Git workflow

1. Open a repository from the sidebar.
2. Switch to the Status tab to see modified files. Tap a file to view its diff.
3. Tap + next to files to stage them, or Stage All.
4. Tap Commit, write (or generate) a message, and commit.
5. Tap Push to upload to the remote.

Branches

The Branches tab lists all local branches with ↑/↓ ahead/behind badges vs their remote-tracking ref. Tap a branch to switch. A progress banner shows the switch is in progress — the file list remains visible so you don't lose your place.

Tap + to create a branch from the current HEAD, or long-press a branch row to delete it.

Merge conflict resolution

When a merge or pull results in conflicts, conflicted files appear highlighted in the Status tab. Tap a file to open the conflict resolver — choose Accept Ours or Accept Theirs per block, then stage and commit the resolution.

AI commit messages

After staging files, tap the ✨ Suggest button in the commit sheet. Sudo sends your staged diff to Anthropic Claude or OpenAI GPT and returns a suggested commit message. You can edit it before committing.

Supported providers: Anthropic Claude (claude-3-5-haiku or better) and OpenAI GPT (gpt-4o-mini or better).

Code editor

In a Git repository, tap any file in the file browser to open it in the editor. The editor supports:

• Syntax highlighting for Swift, Python, JavaScript/TypeScript, Shell, Markdown, JSON, YAML, C/C++, HTML, CSS, Go, Rust, and Ruby.
• Git gutter — green bars mark added lines, orange bars mark modified lines vs HEAD.
• Horizontal scrolling for wide files (no line wrapping).
• ⌘S to save; the title shows a • when there are unsaved changes.

Themes

Go to Settings → Terminal → Theme to switch between the six built-in themes: Dracula, Tokyo Night, One Dark, Gruvbox, Solarized Dark, and Solarized Light. Tap Create Theme to build your own — changes apply instantly in any open terminal session.

App Lock

Protect Sudo with a 4-digit PIN and optional Face ID / Touch ID:

1. Go to Settings → App Lock.
2. Toggle App Lock on and enter a 4-digit PIN when prompted.
3. The lock screen appears the next time you background and return to the app.

To disable, toggle App Lock off and confirm with your PIN. If you forget your PIN, tap Forgot PIN? — you'll need to authenticate with your device passcode, and App Lock will be disabled.