Hosts and connections

Last updated: 2026-11-01

A host is a machine you log in to over SSH: a server, a NAS, a router, a cloud machine, another Mac. SpectaShell keeps your hosts in a host book, shown on the Hosts page, and opens a shell on one when you click it. Nothing needs to be installed on a host for that; where you allow it, SpectaShell also keeps its shells running there (see Shells that keep running).

The host book syncs to your other devices through iCloud: a host added on the Mac is on the iPad too. Passwords are never kept, on any device.

The Hosts page#

Choose Hosts in the sidebar, or Shell ▸ New Connection… (Shift-Command-K) on the Mac; on the iPhone, it is the Hosts tab. From top to bottom:

The search field, and New Host beside it.
Running: the shells kept running on your hosts and on your Mac (see Shells that keep running).
Groups, with New Group.
Hosts: the hosts of your book, each a card.
On the Mac, From ~/.ssh/config: the hosts of your SSH configuration file (see Hosts from ~/.ssh/config).

The search field narrows the page to the hosts whose name, address or user holds what you type, or whose user@address does.

A host's card#

A card shows the host's tile, its name, and under it its user and address, or the host it goes through ("via bastion"). In front of them, "2 shells kept" says how many of its shells are running there, and "not kept" says that its shells end with their connection.

The tile is the host's kind on its colour: Linux, a GPU server, a NAS, a router, a Raspberry Pi… Once SpectaShell has connected to a host and knows its system, the tile is that system's logo, such as Ubuntu's or macOS's; a host whose kind you chose keeps its kind's icon, with the logo at its corner. A small green dot at the tile's other corner means the host keeps shells: they go on running there when you leave.

The ⋯ button on a card opens its menu; so does a right click on the Mac, or touching and holding the card on the iPad and iPhone.

New Shell opens a new shell on the host, in a new tab, even when one is kept there already.
Running Shells…, for a host that keeps shells, lists the ones running there.
Keep Shells Running, or Stop Keeping Shells, changes whether the host keeps its shells (see What a first connection asks).
Let Agents Use Pages, or Keep Agents Off Pages, for a host that keeps shells: whether a coding agent there may use the pages beside its shell on this device (see Files, ports and pages).
Edit… opens the host editor.
Move to Group puts the host in one of your groups, or with Remove from Group takes it out.
Copy SSH Command copies the command that reaches the host from a shell, such as ssh -p 2222 -J bastion [email protected].
Who May Log In…, for a host of a team's group (see Teams).
Remove takes the host out of your book, after asking (see Removing a host).

On the iPhone, swipe a host's row to the left for Edit and Remove.

Adding a host#

Choose New Host. The host editor opens: on the Mac and the iPad, as a panel beside your hosts, where the new host's card shows among them as you type; on the iPhone, as a sheet. On the iPhone, New Host is in the + menu at the top of the Hosts tab.

The editor's fields, in its cards:

Address: the host's IP address or name, such as 192.168.1.20, nas.local or gpu-box.tailnet.ts.net. On the Mac, a name from ~/.ssh/config works too. The tile beside it follows what you choose below.
General: Label, the name SpectaShell calls the host by (left empty, the address names it), and Group, the group it is in.
SSH:
- The port, after SSH on: 22, unless the host's SSH server uses another.
- Username: your account on the host. On the iPad and iPhone it is needed. On the Mac it may be left empty: the host is then reached as your Mac's own user, and after the first login the user it logged in as is written in, so your other devices log in as that user too.
- Through: the hosts to go through on the way, such as stan@bastion (see Going through another host).
- Agent Forwarding: lets programs on the host use your keys while you are connected — to log in to another host from there, or to sign a git commit. On the Mac these are your SSH agent's keys, and anyone with root on that host can use them meanwhile, so turn it on only for a host you trust. This device's key goes along on every device, and it signs only when you say so: each time the host asks for it, Face ID, Touch ID or your password is asked first, saying which host asks and what for, such as "let gpu-box log in as sam on another host". Cancel it and that connection gets no more requests for it until you connect again. A shell the host keeps running gets the agent of the device that has it open, and none while no device does; a shell started before you turned this on gets it once it is started again.
Shells: Ask First, Keep Running or Plain Shells — whether the host keeps its shells running. Ask First asks the first time you connect.
Appearance: Kind, and the tile's colour, one of eight. Automatic is the kind the host is seen to be when SpectaShell connects to it.

There is no password field: a password is asked when you connect, or this device's key logs in.

On the Mac and the iPad, Save keeps the host and Connect keeps it and opens a shell on it. On the iPhone, and in an iPad window too narrow for the panel, the editor is a sheet: Save is at its top, and Cancel leaves without saving.

To change a host later, choose Edit… in its menu. The editor then also shows the host key SpectaShell trusts for it, under Trusted Host Key, and Remove Host at its foot. Changing a host's address, user or port keeps its choice of keeping shells.

Connecting#

Click a host's card (tap it on the iPad and iPhone) to connect. A new tab opens with a shell on the host. When the host keeps a shell already, the card takes you back to it rather than starting a second one:

a shell open on this device is shown where it is;
a shell another of your devices holds is taken over: it moves here, and the other device lets go (see Shells that keep running);
with several kept there, SpectaShell asks which to continue, under "Continue a shell", or offers New Shell.

New Shell, in the host's menu, always starts a new one.

Typing an address#

To reach a host that is not in your book, type it in the search field: user@host, with :port after it for a port other than 22, such as [email protected]:2222. On the Mac, the user may be left out, and a name from ~/.ssh/config works too. When nothing in your book matches, a card offers "Connect to …": press Return, or click it, to connect. Add as Host… on it opens the host editor with what you typed, to keep the host.

More shells on a host#

A split or a new tab from a pane on a host opens another shell on the same host, over the same connection, so it asks for nothing again (see Working in the terminal).

What a first connection asks#

The first time you connect to a host, SpectaShell may ask a few things, each in a dialog. Cancel on any of them stops the connection.

Keep shells running? Unless you already chose for this host, SpectaShell asks "Keep shells running on host?". Keep Shells Running puts a small program, spectashell-keeper, in ~/.local/share/spectashell on the host, and your shells there keep running when the connection drops or SpectaShell leaves the screen. Plain Shells puts nothing there, and a shell ends with its connection. It is asked once for the host; change it in the host's menu or its editor. See Shells that keep running.
The host's key. SpectaShell has never seen the host, so it asks "Trust host?" and shows the key's type and fingerprint. If you can, compare it with the one the host shows for itself (the dialog names the command to run there), then choose Trust and Connect. A trusted key syncs to your other devices, so they do not ask again. On the Mac, a host already in your ~/.ssh/known_hosts is not asked about. When the key is already trusted for another address of the same machine (its Tailscale address beside its local one, say), the dialog says so, as "Already known key".
Logging in. SpectaShell tries the ways in by ssh's order: on the Mac, your SSH agent's keys and those in your ~/.ssh folder; then this device's key; then the host's own questions, and its password. A host that lets you in without any, such as one on Tailscale SSH, asks nothing. What you are asked depends on what the host takes:
- For this device's key, Face ID, Touch ID or the device's password, before the key signs. One check covers every connection made at that moment, such as the tabs coming back at launch.
- For a key file with a passphrase, "Passphrase for file" — asked only when the host takes that key. A wrong passphrase is asked again, up to three times.
- For a host that asks its own questions, such as a one-time code, "host asks", with the host's words as it sends them.
- Otherwise, "Password for host".
Nothing you type in these dialogs is stored anywhere. Your own password manager can fill them (AutoFill: Passwords, 1Password): a password or a passphrase as a password, a host's question for a code as a one-time code. It keeps them; SpectaShell does not.
This device's key. After a login with a password or a code, SpectaShell asks "Log in to host with this device's key from now on?". Add Key adds this device's public key to ~/.ssh/authorized_keys on the host, and removes this device's earlier keys there, so the next login needs no password. Not Now leaves the host as it is; you are asked again at the next password login. It is not asked on a host of a team someone else shares, whose keys its owner looks after (see Teams).

Then the shell opens. On a host that keeps shells, the keeper is put there first: the first time, and when an update of SpectaShell brings a new one.

While it connects#

When connecting takes more than a moment, the pane shows the host's tile, name and address, and a track of four steps that fills as they pass: "Reaching the host", "Checking its key", "Logging in" and "Starting the shell". Under it is the last thing the connection did.

Show Logs opens the Connection Log: each recent attempt, with the time it began, and each of its steps with how many milliseconds had passed — the host reached, its key, the keys offered and the one it took, what it asked (never what you answered), the keeper or the shell. The copy button puts the log on the clipboard, for a report. It holds addresses, user names and key fingerprints, never a password.

If the connection fails, the pane says "Could not connect to host" and why, with Reconnect and Show Logs. See When something goes wrong.

Groups#

A group gathers hosts, such as a home lab or the machines of one project. Choose New Group, in New Host's menu or beside the Groups heading, and give it a Name, a Colour and, if you like, a Through: the host its hosts go through, unless a host's own Through says otherwise.

To put a host in a group, choose the group in the host's editor, or Move to Group in its menu; on the Mac and the iPad, you can also drag a host's card onto a group. Click a group to open it. Its page lists its hosts; dragging a host onto Hosts, the way back, takes it out of the group. Edit Group… changes the group, and Delete Group removes it: its hosts stay, without a group.

A group can be shared with other people, as a team (see Teams).

Going through another host#

Some hosts are reached only through another one: a bastion, or a machine on a private network. Write the hosts on the way in Through, in the host's editor or its group's, as ssh -J takes them: user@host:port, and several separated by commas, in the order to go through them, such as stan@bastion, [email protected]. On the Mac, a name from ~/.ssh/config works there too; on the iPad and iPhone, write each host's user.

Each host on the way is reached over the one before it, and its key and login are asked about as the host's own are. A card shows "via bastion" in place of the address.

Hosts from ~/.ssh/config#

On the Mac, SpectaShell reads your ~/.ssh/config and shows its hosts under From ~/.ssh/config, each card marked "config", by the name the file gives it. They connect as ssh would: with the file's HostName, User, Port, IdentityFile, ProxyJump and its other settings. SpectaShell reads the file and never writes it, and these hosts do not sync.

Their menu has New Shell, Running Shells…, keeping shells and Copy SSH Command. To keep one in your book, and so on your other devices, import it.

Importing hosts#

Import from SSH Config…, in New Host's menu (the arrow beside it; the + menu on the iPhone), copies hosts from an SSH configuration file into your book. On the Mac it lists ~/.ssh/config; Choose File… picks another file, which is how you do it on the iPad and iPhone. Choose the hosts to copy and a Group for them, then Import.

Each host is copied with its address, user, port and the hosts it goes through. Its keys are not: this device's key logs in, as on every host. A host already in your book is marked "Added" and left as it is, and a host of ~/.ssh/config copied into the book shows once, in the book. On the iPad and iPhone, a host without a user says "no user: add one after": add it in the host editor.

Hosts from a cloud#

SpectaShell can list the machines of a DigitalOcean or AWS account as hosts, and keep the list current. In New Host's menu, choose DigitalOcean… or AWS…:

Credentials: for DigitalOcean a Token, for AWS an Access Key ID and its Secret Key. Use credentials that may only list your machines; the sheet says which permissions. SpectaShell only lists them, and never changes anything in your account.
On All Devices: on, iCloud Keychain brings the credentials to your other devices, so each lists the account itself; off, only this device lists it, and your other devices show the hosts it found.
Name: the name of the account's group. Log In As: the user to log in as; left empty, root on DigitalOcean, and the image's own user (ubuntu, ec2-user…) on AWS. Address: Public, or Private, reached through the group's Through. For AWS, Regions: left empty, every region the account has enabled.

Connect lists the account with the credentials before anything is kept, so credentials that cannot list are never saved. The machines become hosts in a group of the account's, which wears its logo and says how its last listing went.

The account is listed again when the Hosts page shows and its last listing is five minutes old, or when you choose Refresh on its group. A machine's address follows the account at each listing. The name, user, kind, colour, group and Through you give a host are kept. A host you remove with Remove in its menu is not listed again. Edit DigitalOcean… or Edit AWS… on the group changes the account, and Remove there takes the hosts it listed and its group away, on all your devices. Nothing changes in the cloud.

Known Hosts#

Known Hosts, in the sidebar (on the iPhone, in Settings), lists the host keys SpectaShell trusts, synced to your devices while iCloud sync is on. Each shows the host's name in your book and its address, the key's fingerprint and type, and when and on which device it was trusted. Forget Key forgets one, on all your devices: the next connection to that host asks you to trust the key it presents. On the iPhone, swipe a key's row to forget it, or tap it for its details.

On the Mac, the page also lists your own ~/.ssh/known_hosts, which SpectaShell reads and never writes.

When a host's key changes#

SpectaShell refuses to connect to a host whose key is not the one it trusts. The pane says "Could not connect to host" and "Its host key changed, so SpectaShell refused the connection.", and Known Hosts shows "host presented a different key at time and was refused." at its top, with Review….

Someone between you and the host could be presenting a different key, or the host was reinstalled. If you did not expect it, do not connect; ask whoever runs the host for its fingerprint. When you know why — the host was reinstalled, or its address now leads to another machine — choose Forget Old Key… under the pane, or Review… in Known Hosts. The dialog shows the key presented and the one trusted; its Forget Old Key… asks once more, and Forget Key forgets the old key on all your devices. From the pane, it then connects again and asks you to trust the new key; from Known Hosts, the next connection asks.

Keys#

Keys, in the sidebar (on the iPhone, in Settings), shows this device's key: made on this device and never leaving it, with Copy Public Key and Share Public Key, to add it to a host yourself, and the hosts SpectaShell put it on. It also lists your other devices, and on the Mac the keys in ~/.ssh and your SSH agent, which SpectaShell uses and never changes. See Your devices, keys and iCloud.

Removing a host#

Choose Remove in a host's menu, or Remove Host in its editor. The host is removed on all your devices; shells running there keep running. A cloud's host removed from its menu is not listed again.

Good to know#

On the iPad and iPhone, a host needs a user: there is no ~/.ssh/config there, and the device's own user is no one's on a host. Typed in the search field, an address needs user@ too.
~/.ssh/config, its keys and your ~/.ssh/known_hosts are the Mac's own: they are read there and never synced. On the iPad and iPhone, this device's key, a password or a code logs in.
A host's ProxyCommand runs a program, so it works only on the Mac; an iPad or iPhone cannot run one.
Agent Forwarding forwards the Mac's SSH agent and this device's key. An iPad or iPhone has no SSH agent, so it forwards this device's key alone. A shell the host keeps running uses the agent of whichever device has it open; a device watching it lends none.
A host of a team's group, shared with you to view only, cannot be edited or removed (see Teams).