Connecting to hosts

A connection profile is a saved target: where to connect and which vault credential to authenticate with. You build it once, then run commands, open shells, and move files through the brokered path. The credential comes from the vault — it is never stored on the connecting device.

Create a connection profile

1. Store the login secret first. Add the SSH key or password to the vault as a credential. SSH keys may carry an optional passphrase, also stored in the vault. See Credential Vault.
2. Add a connection. Give it a name and fill in the target:
   • Host — hostname or IP of the target (for example host.example.com or 192.0.2.10).
   • Port — the SSH port, default 22.
   • Username — the remote login user.
   • Auth method — select a stored credential from the vault. A credential of type SSH key uses the stored private key (and passphrase if present); a credential of type password uses the stored password. The broker injects whichever applies.
3. Save. The profile stores only a reference to the credential, not the secret itself. Access to the credential is re-checked on every use against the vault’s role permissions.

The connecting device holds none of this. The host, port, and username are metadata; the actual secret stays in the vault and is decrypted in memory only for an authorized session.

Confirming a new host’s key

The broker checks the host’s SSH key during the handshake, before it sends any credential. The first key it sees for a host and port is pinned for the whole organization, every later connection must match that pin, and a host that presents a different key is refused. A changed key is never accepted from the connection itself: an organization admin reviews and clears pins on the Host keys page, after confirming that the host was legitimately rebuilt or rekeyed.

What happens on that first connection is an organization setting, host_key_first_use:

• auto pins the first key silently and connects.
• confirm (first-use confirmation) refuses the first connection instead. No credential is sent. Kutrion shows you the key the host presented, and the key is pinned only once someone confirms it.

Organizations created from now on start with confirm. An organization that already existed, including the default organization of a self-hosted install, keeps auto until an admin changes it. An organization admin changes it in the web app under Organization settings, New host keys, or through the API with PATCH /org and the body {"host_key_first_use": "confirm"}.

What you see

In an organization that confirms first use, connecting to a host Kutrion has never seen stops with Confirm this host’s identity before connecting, followed by: “This host is new to your organization, so Kutrion paused before signing in and did not send your credential. Confirming records this key for the whole organization; every later connection must match it.” Below that are the host, the key’s fingerprint (SHA256:...) and its key type.

• Web and the desktop Terminal show this in the terminal, with a Fingerprint verified, trust and connect button. Confirming needs a fresh second-factor check, then reconnects.

• Mobile shows the same panel and button in the session screen, with the same second-factor check.

• The CLI prints the same text and the fingerprint, then the command that confirms it:

  kt ssh trust <connection> --fingerprint SHA256:...
  

  Pass the fingerprint exactly as it was printed. There is no flag that trusts a key without one. Then connect again with kt ssh <connection>.

The key Kutrion saw is held for you for a few minutes. If it has expired, or the host now presents a different key, you are asked to Connect again, which shows the current fingerprint.

Check the fingerprint on the host first

Before you confirm, ask whoever runs the host to read its fingerprint from the host itself, over a channel that does not go through the host. Confirm only if it matches exactly. On the host, pick the public key file that matches the key type Kutrion showed, for example:

ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub

The output includes a SHA256:... value; it must be identical to the one Kutrion showed. A fingerprint read through the same connection you are trying to verify proves nothing, because a machine impersonating the host would answer that too.

Who can confirm

Confirming trusts the key for the whole organization, so only an organization admin, or an editor of the vault that holds the connection, can do it. Anyone else sees: “Only an organization admin, or an editor of the vault that holds this connection, can trust a new host key. Ask one of them to confirm it; they should check the fingerprint above against the host itself first.”

Jump hosts

A connection that goes through a jump host checks every host on the way. If the unconfirmed key belongs to the jump host rather than the host this connection opens, or Kutrion cannot tell which host it belongs to, it cannot be confirmed from here. Open the jump host’s own connection and confirm its key there; that needs an organization admin, or an editor of the vault that holds that connection.

Step-up and risk gating

Sensitive operations can require a fresh WebAuthn step-up before they proceed. Social-login sessions must step up before reaching brokered SSH at all. When you run a single command from the run bar, Kutrion classifies its risk; a high-risk command is blocked until you complete a step-up proof, and the decision is audited. You can also pre-check a command’s risk without running it. What you type into an interactive shell is not risk-checked.

Run a command

Send a single command to the host. The broker authenticates with the vault credential, runs the command, and returns stdout, stderr, and the exit code. The command and its exit code are written to your command history and to the audit trail. If a secret leaks into the command output, Kutrion flags it.

Open an interactive session

Open a full interactive shell over a live connection. You type, the host responds, in real time. While the session is open:

• Terminal output can be recorded to the audit trail where session recording is enabled for your plan.
• Output is scanned for exposed secrets.
• The session can be shared read/write with teammates for real-time collaboration, with input control handed off explicitly. In the web app, Share session hands your running shell to the shared session rather than opening a new one: your screen and scrollback stay as they were, and guests see output from the moment you share, not what was on screen before. A shared session is recorded on the same rule as any other; see Session recording.
• If the connection drops, for example on a network change or when a laptop sleeps, the web app and the desktop Terminal reconnect to the same shell instead of opening a new one. The broker holds the shell for two minutes by default; output you missed meanwhile is shown, followed by Reconnected to the same session. Past that window the shell has ended, and connecting again opens a new one.

When the session ends, the in-memory credential is discarded.

Transfer files over SFTP

File transfer runs over the same brokered connection and the same credential — no separate keys. From a connection you can:

• List a remote directory.
• Download a remote file (streamed).
• Upload a file (up to 50 MB per file).
• Create, rename, and delete files and directories.

Every SFTP operation is audited with its path and size, exactly like a command.

Remote desktop (RDP) connections

An RDP connection is brokered the same way: the desktop’s password stays in the vault and is handed to the server’s RDP gateway when the session opens, never to the browser. Two behaviours affect how you set one up.

The broker connects to the address it checked

When a session opens, the broker resolves the desktop’s host name, checks every address against the same target policy as SSH, and connects to the first checked address rather than to the name. If the name cannot be resolved, the session is refused with host_not_found instead of being left to the gateway to resolve again.

Because the connection is made to an IP address, certificate checking runs against that address. A desktop with Ignore certificate off whose certificate names only its host name fails the TLS handshake. For such a desktop, do one of the following:

• Give the desktop a certificate that includes its IP address as a subject alternative name.
• Turn on Ignore certificate for that connection. On a desktop shared through a vault, this needs admin or owner on that vault.

Network Level Authentication that relies on Kerberos may fall back to NTLM when the target is an IP address, so check that the desktop accepts NTLM if you use NLA.

Recording-required desktops need a recording path

Record sessions is on by default for a new RDP connection. A desktop with recording on is refused with recording_unavailable when the server has no recording path configured (RDP_GATEWAY_RECORDING_PATH), rather than opening a session that would not be recorded. If the path is removed after a session is started but before the desktop opens, the viewer closes with “This desktop requires recording, and recording is not configured on this server.” To resolve either, an administrator sets RDP_GATEWAY_RECORDING_PATH on the server, or recording is turned off on the connection; on a desktop shared through a vault, turning it off needs admin or owner on that vault.

RDP recordings are stored as captured, without the secret filtering terminal recordings get; see Session recording.

Where to go next

• SSH broker overview — what “brokered” means and why no keys touch the device.
• SSH certificate authority — replace static keys on hosts with short-lived certs.
• Fleet commands — run one command across many hosts at once.