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: core SSH terminal functionality with 1 saved host, 1 terminal session, and 1 Git repository.
• Pro — Monthly ($3.99/month): unlocks all Pro features for the billing period.
• Pro — Annual ($19.99/year): same Pro access with a lower effective monthly price.

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). When your current plan is over its saved-host limit, delete extra hosts from this list before connecting again.

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.

Host configuration (names, addresses, usernames, auth type) syncs to your personal iCloud account when iCloud Drive is enabled on your device. SSH passwords and private keys are Keychain-only and never sync — you re-enter credentials on each device. Keys generated on one device cannot be transferred to another; generate a separate key on each device and add both public keys to your server's authorized_keys.

Discover devices on your network

Tap Discover Devices inside the Add Host sheet to scan your local network for SSH-capable hosts via Bonjour/mDNS. Sudo resolves each device's IP address and pre-fills the Add Host form when you tap a result.

Bonjour discovery requires local network permission, which iOS will request the first time you open the discovery screen. You can change this permission in iOS Settings → Privacy & Security → Local Network.

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.

Deleting an SSH key is blocked while any open terminal session uses a host configured with that key. After those sessions are closed, Sudo warns before deleting the private key and switches affected host records back to password authentication so stale key metadata is not left behind.

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. Session limits depend on your current plan and are shown in the app when you reach a limit.

Live Activity

When an SSH or Mosh session is active, Sudo can show a Lock Screen and Dynamic Island Live Activity. This is expected while the app is backgrounded or the iPhone is locked.

For privacy, the Live Activity shows only protocol type, session count, elapsed connection time, and verified/unverified status. It does not show hostnames, usernames, IP addresses, commands, terminal output, repository names, or file paths.

If Sudo is terminated or cannot refresh the activity, the Live Activity can change to Unverified. Open Sudo to verify whether the session is still available.

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: AI, Snippets, Tunnel, Files, Code, Stats

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

Terminal AI command assistance

Tap AI in the keyboard bar to ask Sudo to generate a shell command from natural language. Configure Anthropic or OpenAI in Settings → AI first. Your API key is stored in Keychain and sent only to the selected provider to authenticate requests you initiate.

Generated commands can be wrong or destructive. Review every command before sending it to the terminal.

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.

App Intents & Shortcuts

Sudo exposes a Connect to Host App Intent that you can use in the iOS Shortcuts app. Run a Shortcut to open Sudo and begin connecting to a saved host — useful for home-screen shortcuts or Siri automation.

1. Open the Shortcuts app and create a new Shortcut.
2. Search for Sudo actions and add Connect to Host.
3. Select the target host from your saved hosts list.
4. Run the Shortcut to open Sudo and start the connection.

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.

Remote Code with code-server

Tap Code in the keyboard bar to open Remote Code for the current SSH session. Sudo checks whether code-server is installed on the remote host, starts it on 127.0.0.1 on that host, creates a private SSH tunnel, and opens the local tunnel inside the app.

1. Install code-server on the SSH server you control, for example from the code-server project instructions.
2. Connect to that server in Sudo.
3. Tap Code, choose a remote folder, then tap Open Remote Code.

Remote folder examples:

• ~ — your remote home folder.
• ~/dev/project — a cloned repo under a dev folder.
• /var/www/site — an absolute server path.

The folder field can suggest remote directories as you type, and the folder button opens an SFTP-backed directory picker.

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

If Mosh cannot start, Sudo fails the connection quickly with an actionable message. Check that mosh-server is installed and UDP ports 60001–60999 are open, or disable Mosh for that host and connect with plain SSH to verify the server.

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 larger than 500 MB cannot be uploaded; Sudo will show an error before attempting the transfer.
• Directory listings are capped at 10,000 entries to prevent memory issues on servers with very large directories.

Files.app integration

When Pro is active, 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. Files.app host locations are removed when Pro is inactive.

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. Deleting a repository in Sudo removes that repository's own folder, not the entire Repositories directory. Use Settings → Git → Clean Deleted Repositories to remove leftover clone folders that are no longer shown in Sudo.

When your current plan is over its Git repository limit, delete extra repositories from the Git Repositories list before opening another repository in Sudo.

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.
6. Tap Fetch to download remote changes and update remote-tracking refs without merging into your working branch.
7. Tap Pull to fetch and merge remote changes into the current branch in one step.

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.

Commit graph

Switch to the Graph tab inside a repository to see a lane-based visual commit history. Each branch occupies a lane; merge commits show connecting lines between lanes. Tap any commit node to see its message, author, date, and the list of files changed in that commit.

Stash

To save uncommitted changes without creating a commit, open the repository actions menu and tap Stash Changes. Sudo supports multiple stash entries — each entry appears in the Stash list with its message.

• Pop — apply the stash entry and remove it from the list.
• Drop — remove the stash entry without applying it.

Stash entries are stored in the repository's .git folder and are visible to other Git clients using the same clone.

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 and OpenAI GPT text/code models listed in Settings.

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.