Docs / Getting Started

Sync across your devices

Set up NetShell once and your connections, snippets, and keys follow you to every iPhone, iPad & Mac signed into the same Apple ID.

Two channels, one Apple ID

NetShell keeps your devices in step using two separate, complementary Apple technologies. Knowing which channel carries what makes the privacy model easy to reason about, because the split is deliberate — your secrets ride a different, stronger path than your organisational data:

  • iCloud key-value store (KVS) carries your connections, snippets, folders, groups, and tags. This is your organisational data — host addresses, ports, usernames, command snippets, and the structure you've built around them.
  • iCloud Keychain (end-to-end encrypted) carries your passwords and SSH private keys. These never touch the key-value store and never pass through a NetShell server — only Apple's E2E-encrypted Keychain, which replicates exclusively to your own devices.
No NetShell account, no NetShell server. Nothing about your sync passes through NetShell's infrastructure — there isn't any. Sync is entirely between your devices and your iCloud.

What syncs via iCloud KVS

The key-value channel mirrors the things you create and organise inside the app:

  • Connections — host, port, username, and the auth method you chose (the password or key material itself rides the Keychain channel, not this one).
  • Snippets — your saved commands and command sequences.
  • Folders, groups, and tags — the structure you use to keep dozens of hosts tidy.

Edit a tag on your iPad and it appears on your iPhone and Mac; add a connection on your Mac and it's waiting on your iPhone. See groups & tags and snippets for what travels.

How passwords and keys sync (separately)

Your SSH private keys and passphrases live in the hardware-backed iOS Keychain, protected by Face ID. When they sync, they move only through Apple's end-to-end encrypted iCloud Keychain, which replicates to the devices that share your Apple ID, two-factor authentication, and a device passcode. NetShell never sees, stores, or relays the plaintext. The keys are not locked to a single device — they sync end-to-end across your own devices — but they only ever travel over the encrypted Keychain path, never the key-value store. For the full picture, see iCloud Keychain sync and encryption.

What does NOT sync

A few things stay device-local on purpose:

  • Host keys (known-hosts). Trust-on-first-use fingerprints are pinned to the device that approved them, so a compromised or swapped device can't silently spread trust to your others. You'll approve each new host once per device. See host verification.
  • Discovered network and Bluetooth devices, and live dashboards. These are transient scan results, not saved data.
  • Per-device settings like your chosen terminal theme remain local to each device.

Requirements

For sync to work, on every device you want kept in step:

  1. Sign in to the same Apple ID (Settings → [your name] on iPhone/iPad, or System Settings → [your name] on Mac).
  2. Enable iCloud Drive for NetShell so the key-value data syncs.
  3. Enable iCloud Keychain (iCloud → Passwords / iCloud Keychain). This is what carries your passwords and SSH private keys — without it, organisational data still syncs but credentials won't.
  4. Be online. Sync is opportunistic; it needs a network connection to push and pull changes.

NetShell runs on iPhone and iPad with iOS/iPadOS 17 or later, and on Mac. Keep each device on a current OS release for the smoothest sync.

Turning it on

  1. Open Settings → Sync inside NetShell.
  2. Toggle iCloud Sync on.
  3. Confirm iCloud Keychain is enabled at the system level (see Requirements) so your credentials travel too.
  4. Open NetShell on your second device with the same Apple ID — your connections, snippets, folders, groups, and tags appear automatically once iCloud syncs.
Tip. The very first sync can take a minute or two and may need the app foregrounded. If your second device looks empty at first, give it a moment with NetShell open and online. NetShell is free with no subscription, so every device you own can stay in step at no cost.

Conflicts and deletions (tombstones)

When the same item is edited on two devices before they've reconciled, NetShell resolves to the most recent change so your devices converge on one consistent state rather than spawning duplicates.

Deletions use tombstones: when you delete a connection, snippet, folder, group, or tag, NetShell records a deletion marker and propagates it, so the item is removed from your other devices too instead of reappearing on the next sync. Tombstones are garbage-collected after a retention window, keeping the sync store small while still guaranteeing a deletion sticks everywhere.

Why tombstones matter. Without them, a device that was offline during a delete would re-upload the "missing" item and resurrect it. The deletion marker tells every device "this was intentionally removed."

Troubleshooting

  • Second device shows nothing. Confirm both devices are on the same Apple ID, iCloud Drive is enabled for NetShell, and you're online. Open NetShell and wait a minute.
  • Connections synced but I'm prompted for the password/key. iCloud Keychain isn't enabled on one device. Turn it on in system Settings — credentials ride that channel, not the key-value store.
  • A deleted item came back. Give both devices time online so the tombstone propagates; a brief reappearance can happen if a device was offline during the delete.
  • New host warns me again on the second device. Expected — host (known-hosts) keys are device-local by design. Approve the host once per device.
  • Nothing syncs at all. Check that iCloud isn't out of storage and that NetShell has iCloud permission in system Settings.
Next
iCloud Keychain sync → Related
SSH keys →