Appearance
SSH (Connection Manager)
The SSH view is a top-level manager for saving and launching SSH connections to remote servers - even servers that do not run the Clusto daemon (clustod). Most machines you want to reach over SSH will never have Clusto installed; this view lets a Clusto node act as the jump-off point, opening a normal Clusto terminal session that runs ssh user@host for you.
Open it from the SSH entry in the main menu (route /ssh). It is the overview of all saved connections. Running SSH terminal sessions are listed in their own SSH section of the main sidebar; see Where SSH sessions appear.
The same saved-connection list, Connect button, editor and credential manager also live on the SSH tab of Locations (/projects?tab=ssh). Run Manage SSH connections from the F1 palette to jump there.
Saved connections
A saved connection stores everything needed to open a session:
- Host (name or IP), listed first. You can paste a connection string instead of typing the fields:
user@host:port,ssh://user@host:port, or a wholessh -p 2222 -i key user@hostcommand. Clusto fills in the host, username and port from it. - Port (default
22) and Username. - Name (optional) - a label shown on the connection card. It defaults to the host.
- Authentication (see below).
- Under More options: Remote directory (optional, a directory to
cdinto on login) and Extra ssh arguments (optional, raw flags appended to thesshcommand line, e.g.-o StrictHostKeyChecking=accept-new).
A new connection has a Save & connect primary button that saves it and opens the terminal in one step. Ctrl+Enter (Cmd+Enter on macOS) triggers it, or Save when you are editing an existing connection.
Each connection card has Connect, Edit, and Delete actions. Deleting removes only the saved connection - it never touches anything on the remote server.
Authentication methods
Authentication is a three-way choice:
- Default keys - no secret is stored. Relies on a running
ssh-agentor the node's default~/.sshkeys. When the daemon runs as root or as the Windows LocalSystem service,sshruns as the node's session user (the same account its terminals use), so it uses that user'sssh-agentand~/.sshkeys. - Private key - then pick where the key comes from:
- From vault - reference a reusable key from the node's credential vault instead of retyping a secret per connection (see below).
- Paste key - paste or load a private key; the key material is encrypted and stored in the cluster, then written to a temporary
0600file only at connect time. - File on node - an absolute path to a private key on the node that runs ssh (not on the client), plus an optional passphrase. A Browse button opens the shared file picker, which has a node switcher so you can pick the key on any node, and fills in the path. The key itself is never copied into Clusto; it is referenced by path only.
- Password - then pick Type it (a stored password the daemon feeds to
sshvia an askpass helper) or From vault (a reusable password from the credential vault). Key-based auth is more reliable; treat the password method as a convenience.
The editor defaults to From vault when the vault already holds a credential of the matching kind.
Credential vault
The Manage credentials button next to New connection opens a reusable credential vault: named keys and passwords stored once, encrypted, and shared across saved connections.
- Add a credential with a name, a type (private key or password), the secret material, and - for keys - an optional passphrase. Keys can be pasted or loaded from a file on the node.
- In a connection's Authentication section, pick Private key > From vault or Password > From vault and choose the credential. Editing the credential updates every connection that references it.
- A credential cannot be deleted while a connection still uses it - reassign or delete those connections first.
- Like connections, credentials are cluster-global - one shared vault visible and usable from every node.
A key typed or pasted into a single connection stays on that connection until you move it to the vault. The dialog description says so, and the empty vault state points at the Stored on connections section below whenever connections hold their own secrets.
Stored on connections
Under the vault list, Stored on connections lists every saved connection that keeps its own secret: a private key pasted into the connection ("Private key (stored in cluster)"), a typed password, or a key file path. Connections that use default keys or a vault credential are not listed.
- Move to vault (stored key or password rows) copies the secret into the vault, switches the connection to the vault credential, and clears the connection's own copy. The copy happens inside the daemon, so the secret never crosses the wire to your client.
- If a vault credential already holds the identical secret, it is reused instead of duplicated. Keys are compared ignoring surrounding whitespace, and the passphrase must match too. Several connections that share one key therefore end up pointing at a single vault credential.
- A new credential is named
<connection name> keyor<connection name> password. Rename it in the vault list afterwards if you like. - Move all to vault appears when more than one connection can move.
- Key file rows only have Edit: a key file is a path on one node, so there is nothing to move.
- Every row has Edit connection, which opens the connection editor.
Moving a secret to the vault needs an admin connection to the node.
Cluster-global vault
Connections and credentials are replicated across the whole cluster - there is no node picker. Every node holds the same set, so you manage one shared list no matter which node you are connected to. Saving, editing, or deleting on any node propagates to the others (last-writer-wins), and the view refreshes on every client automatically.
To make the encrypted secrets readable on every node, the cluster converges on a single shared ssh_secret_key: nodes elect the key belonging to the lowest-node-id member and re-encrypt their local vault under it. This is automatic and needs no operator action.
Clicking Connect originates the ssh process on the node you are currently connected to.
Connecting
You can start an SSH terminal from the New terminal dialog (Mod+T, the SSH choice) or the sidebar's SSH +, without opening this view. Saved connections are listed there; typing user@host offers New connection to user@host, which opens the connection editor prefilled. The F1 palette has New SSH terminal. The gear in the sidebar and this view still manage, edit and delete connections.
Clicking Connect launches a normal Clusto terminal session running ssh user@host. Because the session is spawned by the daemon (not by the client), it behaves exactly like any other Clusto terminal session:
- It persists when you close or reload the app. Reconnect later and the SSH session is still alive.
- The app navigates you straight to that terminal.
Where SSH sessions appear
SSH terminal sessions sit under their own SSH section in the main sidebar. Its header collapses the list, its + opens the SSH connections view to connect, and its gear opens the SSH tab of Locations ("Manage SSH connections"). If you hide the SSH item in Customize navigation, or use the Simple profile, SSH sessions fall back to an SSH group at the bottom of Terminals. That group's + opens the SSH connections view, and its gear opens the same SSH tab.
With the workspace.unified Labs flag on, there is no separate SSH sidebar section: each saved connection is a row in the Workspace tree instead. See Unified Workspace.
Files for an SSH session
The right sidebar is available while an SSH session is open, with the Files panel on by default. It lists the files of the cluster node the ssh client runs on (the session's working folder there), not the files on the remote host; a note in the panel says so. Git and Run are off for SSH sessions. On phones the sidebar opens as a sheet from the terminal switcher button.
Pre-connect check
Before opening a terminal, the node runs a quick non-interactive ssh probe (BatchMode, 10 second connect timeout). If the login cannot succeed, no terminal opens - the terminal would only close instantly and hide ssh's error. Instead a dialog explains why:
- Server rejected the key - the server refused the connection's stored key or key file and offers no password fallback. The dialog shows the public key (with Copy) and its SHA256 fingerprint so you can add it to
~/.ssh/authorized_keyson the server, or use Install key and connect (below). - Server identity changed - the host key no longer matches the node's
known_hosts(reinstalled server, or interception). The dialog shows thessh-keygen -R '<host>'(or'[host]:port') command to run on the node you are connected to; run it, then Retry. - Server unreachable - timeout, connection refused, DNS failure or no route. Check the host, port, firewall, and VPN or Tailscale.
The dialog also has a collapsible ssh output section with ssh's last error lines, and a Retry button.
Cases the probe cannot judge still open the terminal as before: an unknown (new) host key, which you accept in the terminal; a server that also allows password login, where you type the password; passphrase-protected keys; saved passwords; and SSH agent auth (a key refusal is not treated as fatal for agent auth).
Install key and connect
For Server rejected the key, enter the server account's password in the dialog. Clusto logs in once with it (password and keyboard-interactive only), appends the public key to ~/.ssh/authorized_keys, verifies the key now works, and reconnects. This works like ssh-copy-id:
~/.sshis created with0700and the file with0600if missing.- A key is never added twice; the line is tagged with the comment
clusto. restoreconruns when present.- The password is used for that one login and is never stored.
- A new host key is accepted during this install login; a changed one still fails.
Security and credentials
- Passwords, key passphrases, and stored private keys are encrypted at rest in each node's SQLite database using XChaCha20-Poly1305, under a shared cluster master key (
ssh_secret_key) the nodes elect and converge on so the vault decrypts on every node. - Private key file connections reference the key by path only - that key is never copied into Clusto.
- Secrets are never sent back to clients. Listing connections reveals only whether a secret is set, not the secret itself. The daemon decrypts a secret only at the moment it launches the ssh session.
- When editing a connection, leaving the password / passphrase field blank keeps the previously stored secret; typing a new value replaces it.
Limits
This is a v1 feature. Worth knowing:
- Saved passwords and passphrases are filled in automatically on Linux and macOS nodes with OpenSSH 8.4+ (the daemon uses an askpass helper with
SSH_ASKPASS_REQUIRE=force). On Windows nodes and olderssh, ssh prompts in the terminal instead - you can simply type the secret there. - Stored keys work on every node. On Windows the daemon writes the key into a data folder only SYSTEM, Administrators and the daemon account can read, as Windows OpenSSH requires.
- Install key and connect needs the server to allow password logins, a Linux or macOS node (Windows nodes have no askpass helper), OpenSSH 8.4+ on the node, and a key Clusto can read without a passphrase (a stored key or key file).
- The pre-connect check is best effort. It stops only logins it can prove will fail; anything else still opens the terminal.
- No SFTP / file transfer, no ProxyJump / jump hosts, and no port forwarding.
known_hosts/StrictHostKeyCheckingbehaviour follows the node'ssshdefaults unless you override it via the extra ssh arguments field.