Docs / Getting Started

Quick start

Go from a fresh install to a live, fail-closed SSH session in a few minutes — on iPhone, iPad, or Mac.

1. Install NetShell

NetShell is a free SSH client for iPhone, iPad & Mac. There is no subscription, and no telemetry runs by default — analytics are strictly opt-in. Grab it from the App Store, then open it. NetShell runs on iOS/iPadOS 17 and later, and on Mac.

On first launch you'll see a short onboarding flow. Nothing is gated behind an account — there is no NetShell account to create. When you're done, you land on your (empty) connections list, ready to add your first server. For a tour of everything the app does, see What is NetShell.

2. Add a connection

Tap + to create a connection and fill in the basics:

  • Host — the hostname or IP address of your server (for example 198.51.100.10 or server.example.com).
  • Port — defaults to 22; change it if your server listens elsewhere.
  • Username — the account you log in as, such as root or deploy.
  • Name — an optional friendly label so the connection is easy to spot in the list.

If you don't know the host yet, the built-in network scanner can sweep your LAN with Bonjour and a port scan, surface devices, and flag the ones running an SSH server — tap one to pre-fill a connection. More detail lives in Add a connection.

3. Choose how you authenticate

NetShell supports two auth methods per connection:

  • Password — quick to set up. The password is stored in the hardware-backed iOS Keychain, protected by Face ID.
  • SSH key — stronger and the recommended path. You pick a key from your Key Vault and NetShell loads it at connect time.
Tip. Key-based auth means you never type a server password again, and you can disable password logins on the server entirely once your key works.

4. Generate an ed25519 key

Open Settings → SSH Keys and tap Generate:

  1. Choose ed25519 — modern, fast, and the recommended type. (RSA is also available if a server requires it.)
  2. Optionally set a passphrase for an extra layer on top of Face ID.
  3. Tap generate. The key is created entirely on-device.

Already have a key elsewhere? Use Settings → SSH Keys → Import to paste an OpenSSH-format private key — encrypted ed25519 and RSA keys are supported. Full coverage is in SSH keys.

5. Add the public key to authorized_keys

Copy the public key from the Key Vault and append it to your server's authorized keys file. You can do this over an existing password session, or from another machine:

mkdir -p ~/.ssh && chmod 700 ~/.ssh
echo "ssh-ed25519 AAAA...your-public-key... you@device" >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

Back in NetShell, edit the connection, set Auth to SSH key, and select the key you just generated.

6. Connect with a fail-closed host check

Tap the connection to start a session. The first time you reach a server, NetShell verifies its host key at handshake time using trust-on-first-use. Because the check is fail-closed, your credentials are never sent until you approve the host — review the fingerprint and tap to trust it.

On every later connection NetShell re-checks that fingerprint. If the host key has changed unexpectedly (a possible man-in-the-middle, or a rebuilt server), NetShell refuses to send credentials and warns you. Read more in Host verification.

Built-in safety. A destructive-command guard watches your input and intercepts dangerous lines — rm -rf, DROP/TRUNCATE TABLE, git push --force, git reset --hard, shutdown/reboot, kubectl delete namespace, helm uninstall, pipe-to-bash, and more — so a typo can't wipe a server. See Command guard.

7. Customize your workspace

Once you're connected, make NetShell yours:

  • Themes — the terminal ships with 16 themes; pick one in Settings or per session. See Terminal themes.
  • Snippets — save commands you run often and fire them with a tap; details in Snippets.
  • Groups & tags — organize many servers into folders and labels so your list stays manageable. See Groups & tags.

You can also run multiple sessions at once, browse files over SFTP or SMB shares, and chain through a bastion with jump hosts.

8. Sync across your devices

Your connections, snippets, folders, groups, and tags sync between your Apple devices over iCloud (KVS). Sensitive material is handled separately and more strictly: passwords and private keys sync only through Apple's end-to-end encrypted iCloud Keychain — never a NetShell server. Host (known-hosts) keys stay device-local and do not sync, so each device builds its own trust record. See Sync across devices and iCloud Keychain sync.

What's next

With a key-based, fail-closed session running, explore the rest: on-device Apple Intelligence (or bring your own model), Docker container and Compose management, server dashboards with custom alerts, and the app auto-relocking behind Face ID after idle — covered in Face ID lock.

Next
Add a connection → Related
SSH keys →