---
url: https://clusto.app/docs/ssh-view.md
description: >-
  Save encrypted SSH connections and open persistent remote terminal sessions
  through Clusto.
---

# 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](#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
  whole `ssh -p 2222 -i key user@host` command. 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 `cd`
  into on login) and **Extra ssh arguments** (optional, raw flags appended to
  the `ssh` command 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-agent` or
  the node's default `~/.ssh` keys. When the daemon runs as root or as the
  Windows LocalSystem service, `ssh` runs as the node's session user (the same
  account its terminals use), so it uses that user's `ssh-agent` and `~/.ssh` keys.
* **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 `0600` file 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
  `ssh` via 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> key` or `<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](/unified-workspace#ssh-connections-in-the-tree).

### Files for an SSH session

The [right sidebar](/file-explorer#panels-per-view) 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_keys` on 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 the
  `ssh-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`:

* `~/.ssh` is created with `0700` and the file with `0600` if missing.
* A key is never added twice; the line is tagged with the comment `clusto`.
* `restorecon` runs 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 older `ssh`, 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` / `StrictHostKeyChecking` behaviour follows the node's `ssh`
  defaults unless you override it via the **extra ssh arguments** field.
