Sync and your devices

iCloud sync

Sync Hosts with iCloud is off until you turn it on, in the welcome or in Settings, iCloud.

Syncs	Never syncs
Hosts, with their addresses, ports, user names, notes, tags, hardware addresses, jump hosts, port forwards, settings and sign in records	Passwords and keys: they stay in each device's Keychain
Groups	Command history
Snippets, with their commands	Settings: each device keeps its own

A sign in record is only a label, a user name, the kind of sign in, whether it needs Face ID or Touch ID, and the ID of its Keychain item (never the secret). Everything syncs through your own private iCloud database, which we can't see.

• Turning it on or off in Settings takes effect when you quit and reopen Conn, and Settings says so. The welcome's answer at first open applies straight away.
• Changes made with sync off, including deletes, reach your other devices once it's back on.
• On a new device, an empty Hosts list waits up to 45 seconds for your hosts to arrive (Getting your hosts from iCloud). You can add hosts meanwhile.
• Passwords on another device: a host synced from another device shows Needs password or Needs key. Connect, and Conn asks for it once and keeps it on this device.

Sync status

Settings, iCloud shows a Status line. It's green only when syncing is really happening.

Status	What to do
Up to date, Syncing, On	Nothing. Up to date says when it last synced.
Off	Hosts, groups and snippets stay on this device.
No iCloud account, Not signed in to iCloud	Sign in to iCloud in your device's settings.
iCloud is restricted	Screen Time or a device manager is blocking it.
iCloud is not ready	Your Apple Account may need your password in your device's settings.
iCloud is full	Free up iCloud storage.
Waiting for a connection	The device is offline; sync carries on when it's back.
Checking	Conn is asking iCloud.
Not syncing yet	Sync is on in Settings, but this launch isn't syncing. Quit and reopen Conn.
Not syncing	Conn opened your hosts without sync this time. The message at the top of the main window says what to do.
iCloud is busy, Cannot tell	Usually passes on its own. Check again later.
iCloud refused a change, Sync problem	Something went wrong; the detail line says what.

If your hosts file won't open

Before Conn changes a hosts file that won't open, it keeps a copy, and never deletes one. Settings, Store lists them, and Recover works when your hosts file didn't open, or when an older copy holds hosts your list doesn't.

Handoff

Handoff picks up what you're doing on another of your devices signed in to the same Apple Account: from the app switcher on iPhone or iPad, or from Conn in a Mac's Dock.

• A terminal in Conn's tmux, alone in its window: the other device opens the same tmux session. A single session, or one under Other tmux, can't be handed over.
• A screen: the other device opens the same screen, on the same display.
• Files: the other device opens the same folder.

The other device signs in with its own saved sign in, so both need the host, which means iCloud sync on both. If the other device signs in as a different account on that machine, Conn says so rather than opening someone else's session. Handoff never carries a password or a key.

Shortcuts, Siri and links

Conn adds three actions to the Shortcuts app:

Action	What it does
Connect	Opens a host in Conn, with its terminal, its screen or Files if you pick one. Say "Connect to host with Conn".
Wake	Sends a wake packet to a host, waits up to 25 seconds, and says whether it answered, usually without opening Conn. Say "Wake host with Conn".
Run Snippet	Opens a terminal on a host with a snippet's command shown. Nothing runs until you choose Run. Say "Run a snippet with Conn".

Shortcuts only ever see a host's name and group, and a snippet's name and category, never a command, an address or a password.

A conn:// link opens a host from Notes, Messages or a web page; see Links to a host. A link that opens a terminal, a screen or Files asks first, naming the host.

If a link, a Shortcut or Handoff would close something you've typed and not saved, Conn asks first. While Conn is locked, it waits and goes on once you unlock.

App lock

Turn on app lock in Settings, Security: Require Face ID to Open Conn (or Touch ID, or your passcode, by device), or on a Mac, Require Touch ID or Apple Watch to Open Conn. It takes one check to turn on or off.

• When it locks: when Conn opens; on iPhone and iPad after a minute or more away (a quick trip to another app doesn't lock it); on a Mac when the screen locks, the display sleeps or another user takes over.
• While locked: every window shows Conn is locked with Unlock. Your sessions keep running.
• What it hides: windows and sessions are titled just "Conn"; the app switcher shows a plain cover; Shortcuts, Siri and Spotlight name no host; Handoff is titled "Conn Session"; Mac notifications say only "A session needs you"; the Mac's menu bar icon shows only Conn is locked and Unlock.

Even without app lock, terminals, screens and Files are covered in the app switcher.

iPhone and iPad

• The tabs are Hosts, Sessions, Keys and Settings: along the bottom on iPhone, along the top on iPad.
• iPad Conn supports more than one window and Stage Manager. Each window keeps its own tab. Open in New Window moves a terminal or a screen into a window of its own, and New Window opens another main window.
• iPad With a keyboard, Conn has the same menus and shortcuts as on a Mac, apart from a few Mac-only items. Hold ⌘ to see them. See Keyboard shortcuts.
• iOS pauses apps soon after you leave them, so connections don't stay open in the background. With tmux, your terminal sessions carry on on the machine, and Conn reconnects when you come back.

Mac

• Windows: a main window with Hosts, Sessions and Keys in the sidebar; a window for each terminal and screen; a Transfers window (⌥⌘L); and Settings (⌘,). New Window (⌥⌘N) opens another main window.
• Menus: File, Edit, View, Connect, Screen, Window and Help. The Connect menu acts on the host in front, and its Hosts submenu lists every host by group.
• The menu bar icon lists your sessions (ones that need you first) and every host, with its status, panels, Wake and Check Again. It gets a dot when a session needs you. Turn it off with Show Conn's Menu Bar Icon in Settings.
• Notifications: Conn posts one when a session needs you, while it's running. Click it to open the session.
• Right click does what touch and hold does on iPhone and iPad.
• Quitting Conn doesn't end tmux sessions: they carry on on the machine.

iPhone Duo

Fold the inner display halfway, like a laptop, in portrait:

• Screen: with the Trackpad style, the picture is on the top half and the pad on the bottom half.
• Terminal: with the keyboard up, the terminal stays on the top half.

There's no switch: it follows the fold. Opened flat, Conn goes back to its usual layout.

Moving to a new device

1. Install Conn and, in the welcome, turn on iCloud sync. Your hosts, groups and snippets arrive.
2. Connect to each host. Conn asks for its password once and keeps it on the new device.
3. Make a new SSH key in Keys on the new device, and add its public key to your machines. A Secure Enclave key can never leave the device it was made on, by design.