Docs / Getting Started

Import existing hosts

If you already run servers, you don't have to start from a blank slate — bring your existing hosts, reuse the SSH keys you already trust, and let NetShell organize and sync the lot across your iPhone, iPad & Mac.

Three ways to bring hosts in

There's no single right path — it depends on how many hosts you have and where they live today:

  • Add them by hand — best for a handful of servers, or when you want to set per-host options as you go.
  • Discover them on your network — let the network scanner find machines on your LAN and turn a result straight into a connection.
  • Reuse your existing keys — import the OpenSSH private keys you already authenticate with, so the hosts recognize you immediately.

Most people mix all three: scan to find the boxes, add a couple of remote ones manually, and import the one key that already opens every door.

Add a connection manually

Open the Connections tab and tap +. Fill in the host's address, port and username, pick how you authenticate, and save. Only the host and an authentication method are strictly required — everything else has a sensible default.

  1. Enter the host — an IP address like 192.168.1.20 or a hostname like web-01.example.com.
  2. Set the port (SSH defaults to 22).
  3. Type the username you log in with.
  4. Choose password or key authentication.
  5. Optionally name it, assign a group and tags, then tap Save.

The full field-by-field walkthrough lives in Add a connection. If a host sits behind a bastion, set a jump host so NetShell chains the hops for you, verifying each one independently.

Tip. Not sure of a host's address? The network scanner sweeps your LAN over Bonjour plus a port scan, flags which devices are running an SSH server, and lets you convert a result into a pre-filled connection in one tap.

Reuse your existing SSH keys

The fastest way to make your servers recognize you is to import the key you already use from your laptop or desktop. NetShell's Key Vault imports OpenSSH-format private keys — both ed25519 and RSA, including encrypted keys protected by a passphrase. You can also generate brand-new ed25519 or RSA keys on-device if you'd rather rotate to a fresh one.

  1. Open the Key Vault and choose Import.
  2. Paste the private key text, or pick the key file (for example id_ed25519).
  3. If the key is encrypted, enter its passphrase so NetShell can unlock it.
  4. Give the key a recognizable name and save it to the vault.
  5. When you add or edit a connection, choose Key authentication and pick this key.

Importing the private key is what lets NetShell authenticate. For a host to accept it, that key's public half must already be in the server's ~/.ssh/authorized_keys — which it already is if you've been logging in from another machine with the same key. If you generated a new key instead, copy its public half up first:

ssh-copy-id -i ~/.ssh/id_ed25519.pub user@host
# or append the public key line manually to:
# ~/.ssh/authorized_keys

Where imported keys are stored

Your private keys and their passphrases are written to the hardware-backed iOS Keychain and gated behind Face ID — never kept in plain text. They travel between your own devices only through Apple's end-to-end encrypted iCloud Keychain, never through a NetShell server. See Key sync for exactly how that works and Encryption for the storage model.

The first connection: host verification

The first time you reach a freshly imported host, NetShell shows its fingerprint and asks you to approve it — trust-on-first-use. Verification runs at handshake time and fails closed: your credentials are never sent to a host you haven't approved, or to one whose key has changed since you last connected. A sudden fingerprint change stops the login and warns you, because it can mean a man-in-the-middle. Approved host (known-hosts) keys are stored device-locally and, unlike your own keys, do not sync between devices. More in Host verification.

Organize with groups and tags

Importing a fleet is only useful if you can find things afterward. NetShell gives you two complementary tools:

  • Groups — a folder-style hierarchy. Sort hosts by environment (Production, Staging, Home Lab) or by project. Groups can be collapsed to keep a long list tidy.
  • Tags — lightweight labels you can apply across groups, such as web, db, raspberry-pi or client-x. Filter the list by a tag to see every matching host at once.

Assign a group and tags right in the connection form, or batch them later. Mark the hosts you touch most as favorites so they float to the top and surface faster in Siri Shortcuts and home-screen widgets. The full workflow is in Groups & tags.

Tip. A useful convention: groups for where a host lives (the environment), tags for what it does (the role). A box can then sit in the Production group while also carrying the db and backup tags.

How iCloud sync propagates to your other devices

Set a host up once and it appears everywhere you signed in with the same Apple ID. NetShell syncs your connections, snippets, folders, groups and tags through iCloud's key-value store, so the structure you build on your iPhone shows up on your iPad & Mac without re-entry.

Secrets are handled separately and more strictly. Passwords and SSH keys are deliberately kept out of the key-value store — they sync only via the end-to-end encrypted iCloud Keychain, which replicates to your own devices alone. The practical result: import a key on one device and, once iCloud Keychain has propagated it, your other devices can authenticate with it too — while the key material itself stays end-to-end encrypted the whole way. Deletions propagate the same way, so removing a connection on one device removes it on the others. Full detail in Sync across devices.

A sensible migration order

When bringing in an existing setup, this order saves the most retyping:

  1. Import your key first. Add it to the Key Vault before you create connections, so you can pick it as you add each host.
  2. Create your groups. A couple of empty groups (environments) up front means new connections land in the right place immediately.
  3. Add the hosts — scan the LAN for local ones, add remote ones by hand, choosing the imported key for authentication.
  4. Tag as you go so filtering works from day one.
  5. Approve each host's fingerprint on first connect, then confirm everything has reached your other devices.

Staying safe once you're connected

Imported access doesn't loosen NetShell's guardrails. The destructive-command guard still 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 — before they hit the wire, and the app auto-relocks behind Face ID after it sits idle.

NetShell is a free SSH client for iPhone, iPad & Mac running iOS / iPadOS 17 or later, with no subscription and no telemetry by default. Download it on the App Store to get started.

Next
Sync across devices → Related
SSH keys →