Hosts

The Hosts screen

Hosts shows a tile for each machine, in your groups first (in the groups' order), then any not in a group under Ungrouped. Within a group, hosts are sorted by name.

• Search hosts, tags and addresses finds a host by its name, notes, tags or addresses.
• Check All, or pulling down on iPhone and iPad, checks every host shown again.
• Export Hosts... and Manage Groups... are in the toolbar too.
• You can drop a .conn file on Hosts to import it.

What a tile shows

A tile has the host's icon with a status dot, its name and address (with :port when SSH isn't on 22), and a status line. Its Screen, Terminal and Files buttons open those straight away; tapping the tile opens the host's page.

Dot	Means
Grey dotted circle	Not checked yet.
Amber dashed circle	Checking.
Green dot	It answers.
Amber exclamation mark	Part of it answers: for example Screen only when SSH is refused but the screen answers.
Red cross	It doesn't answer.

The status line adds how Conn reached it and how fast:

• via LAN, via VPN or via Public, by the kind of address that answered, and trying LAN (or VPN, or Public) before one has. via Tailscale appears only when Conn has proved the traffic goes over Tailscale.
• The time it took to answer, such as 12 ms.
• When it doesn't answer, why: Port closed, Not reachable, Name not found, No answer, No network or Needs permission (Local Network is off for Conn).

Conn checks a host's main port every 20 seconds or so while it's on screen, and its other ports every two minutes. The status is for SSH when the host has Terminal, and for its screen otherwise.

A tile's menu

Touch and hold a tile (right click on a Mac) for its panels, Wake (when it has a hardware address), Check Again, Host Details, Move to Group, Copy Link and Export Host...

Adding a host

Add Host (the + button, or ⌘N on a Mac or iPad keyboard) has three tabs.

Discover

Discover lists machines on your network that announce SSH, SFTP or screen sharing (Bonjour), such as a Mac with Remote Login or Screen Sharing on. Each shows its name, its .local address and what it offers. Add adds it with what it offers turned on; it becomes Added.

Conn looks only while Discover is open, never in the background. If it can't, it's usually because Local Network is off for Conn in your device's Privacy settings; machines reached over a VPN or a public address still work, added by hand.

Manual

Field	What to put
Icon	Desktop, Laptop, Network Storage, Router, Firewall, Cloud Server, Container, Single Board Computer or Home Hub.
Name	Whatever you'll recognise, such as "Home Lab 101".
Address	An IP address (IPv4 or IPv6) or a name such as mini.local or server.example.com. Conn tells you whether it looks like a local network, VPN or public address.
Connections	Screen, Terminal and Files, all on to start. Turn off what the machine doesn't offer. Conn checks each one's port to tell whether the machine is up.
Ports	SSH port (empty means 22) and Screen port (empty means 5900).
Sign in	Add Sign In..., or leave it and Conn asks when you connect.
Tags	Up to 12 words to search by.
Group	None, a group, or New Group...

Import

• Choose a .conn File imports hosts someone exported from Conn. See .conn files.
• SSH Config: paste the contents of your ~/.ssh/config and press Read This Config. Conn shows each Host it found with its address and port, and adds only the ones you pick, with Terminal and Files on. A user name or key path is shown but not saved. Conn never reads your keys or runs anything; if you paste a private key by mistake, it refuses it and clears the box.
• Hosts already in Conn show Already here.

Up to 500 hosts can be read from one config. A ProxyJump naming one machine becomes the host's jump host when that machine is in the same paste or already in Conn; see Jump hosts. A Host with a ProxyCommand, a ProxyJump chain, or settings Conn can't use, can't be picked: its switch is greyed, with a note saying why.

The host's page

A host's page has its status at the top, then these cards:

• Status: whether it answers, and how, such as Answered in 12 ms via LAN. When it doesn't answer, Test Reachability tries every address on every port the host uses and shows each result. A screen port open to the internet is flagged. For a Tailscale address, Conn offers to open Tailscale or its admin console.
• Connect: Terminal, Screen and Files, and Wake.
• Live Sessions: tmux sessions running there, terminals and screens open here. See Sessions.
• Addresses, then Port Forwards when the host has saved forwards, to start and stop (see Port forwards).
• Sign Ins. A Needs password or Needs key chip means this device has no password or key for it: it was saved on another device, or came in a .conn file.
• Organise, and Delete Host at the bottom.

The toolbar has Check Again, Edit, and More with Test Reachability, Copy Link and Export Host...

Edit Host

Press Edit on a host's page. Changes save as you make them.

Section	What's in it
Machine	Name, each address with its SSH port, and Notes. A changed address or port counts as a new machine: Conn asks about its key again unless it already has it for this host.
Icon	The icon on its tile.
Connections	Screen, Terminal and Files.
Sign in	Add, change or remove the SSH sign in. A password stays on this device behind Face ID or Touch ID; a key stays in Keys. Screen sign in appears when a screen password is saved.
Jump host, Port forwards	Reach It Through another host, and this host's saved port forwards. See Jump hosts and port forwards.
Wake	The machine's hardware (MAC) addresses, for Wake-on-LAN.
Terminal	Runs In (Ask at first open, Single session or tmux) and Remember Commands Run Here.
Screen	How its screen is reached and opens. See Screen settings.
Tags, Group	Words to search by, and the host's group.

If a link or a menu would take you away while Edit Host has a change you haven't finished, Conn asks first. Edit Host changes a host's addresses, but can't add or remove one.

Groups

Groups become sections on the Hosts screen. A host can be in one group.

• Manage Groups... lists them: tap one to rename it or change its icon, drag to reorder, swipe to delete. New Group adds one.
• Move a host with Move to Group in its tile's menu, or in Edit Host.
• Deleting a group keeps its hosts; they become ungrouped.
• Group names are unique, ignoring capitals.
• Run on a Group... on a group's heading runs one snippet on every host in it. See Run on a Group.

Wake-on-LAN

Wake starts a sleeping machine over the network. Add the machine's hardware address (its MAC address, from its network settings) in Edit Host, Wake. Then use Wake on its page or in its tile's menu, the Connect menu on a Mac or iPad, the Mac's menu bar icon, or the Shortcuts app.

• Conn sends a "magic packet" to the network's broadcast address, on ports 9 and 7.
• It sends it from your device when the machine is on the same network. Otherwise, if the host has a jump host, Conn signs in to the jump host and sends it from there (the jump host needs perl, and its key must already be trusted).
• Conn then waits up to a minute for the machine to answer, and says Answered after so many seconds, or Nothing answered, with a reminder to check the machine is set to wake from the network.
• An address that looks randomised gets a warning, because it may change and Wake may not reach the machine.

The machine has to be set up to wake from the network. See Prepare your machines.

.conn files

A .conn file shares hosts between devices or people.

• Export Hosts... saves every host, group and snippet. Export Host..., in a tile's menu or a host's More menu, saves one host and any jump hosts it goes through.
• Never inside: passwords, private keys, screen passwords, or anything from the Keychain. A host imported from a file asks for its sign in the first time you connect.
• Inside: names, icons, addresses and ports, what each offers, user names, notes, tags, groups, hardware addresses, jump hosts, port forwards, sign in labels, and snippets. Edit Host's Screen settings and Runs In stay behind.
• The file is compressed, so a text editor doesn't show host names at a glance. It isn't encrypted.

To import, open the file from the Files app, Mail, AirDrop or the Finder, drop it on Hosts, or use Add Host, Import. You see what it holds before anything changes, and choose what happens to Hosts you already have:

Skip (the default)

Only hosts not already in Conn are added. Nothing you have changes.

Replace

Hosts in the file replace yours, field by field. Addresses and sign ins the file doesn't mention stay.

Keep Both

Every host in the file is added alongside yours.

Snippets from a file always ask before they run, whatever the file says.

Links to a host

Copy Link copies a link to the host, such as conn://host/mini. Put it in Notes, Messages or a web page, and tapping it opens that host in Conn. Add ?mode=terminal, ?mode=screen or ?mode=files to open that panel.

• A link only names a host you already have. It never carries an address, a port or a password.
• A link that opens a terminal, a screen or Files asks first, naming the host, because anyone can write a link.
• If no host has that name, Conn opens Add Host with the name filled in.

Deleting a host

Delete Host, at the bottom of its page, asks first, saying what goes. With it go:

• the host and its addresses, here and, with iCloud sync on, on your other devices;
• its saved passwords on this device, which can't be brought back;
• its open terminals and screens here (locking the Mac if it's set to);
• this device's notes about it, such as recent folders and allowed clipboard access.

Your SSH keys stay in Keys, and nothing on the machine itself changes.