Your first connection¶

This walkthrough connects to an SSH server you already have credentials for. If you don't have one, the easiest scratch target is localhost — turn on Remote Login in System Settings (macOS), sudo systemctl start ssh (Linux), or OpenSSH Server under Optional Features (Windows).

1. Open the Connections view¶

Launch Cleat. The left sidebar shows the connection tree. Click the + button at the top, or use the command palette (Ctrl+Shift+P / Cmd+Shift+P) and search for New Connection.

2. Fill in the basics¶

Field	Example
Name	`staging-web-1` (anything memorable)
Host	`staging.example.com` or an IP
Port	`22` (default)
User	`deploy`
Auth	Key or Password

If you pick Key, point Cleat at an existing private key or generate one on the spot.

OpenSSH-format keys

Cleat's current crypto backend (mbedTLS) doesn't parse OpenSSH-format private keys (-----BEGIN OPENSSH PRIVATE KEY-----). If you generated your key recently, it's almost certainly OpenSSH-format. Convert with:

bash ssh-keygen -p -m PEM -f ~/.ssh/id_rsa

This rewrites the key in PEM format in place. See Key formats for the full story.

3. Connect¶

Click Save & Connect. Cleat opens a new tab with a terminal session.

Host key verification — current behavior

Cleat reads and writes the OpenSSH known_hosts file at ~/.ssh/known_hosts.

First connection to a new host: the server's key is added automatically (TOFU — Trust On First Use). There is no fingerprint prompt today.
Host key mismatch on a known host: Cleat logs a warning and proceeds anyway in the current PoC build. An interactive blocking prompt is on the roadmap. Until then, watch the Activity Log (View → Activity Log) for HOST KEY MISMATCH lines.

If you need stricter behavior right now, remove or audit ~/.ssh/known_hosts outside of Cleat.

4. Try a few things¶

Now that you're connected:

Open a second tab to the same host: Ctrl+Shift+T / Cmd+T
Split the pane: View → Split Right (or your custom binding)
Open the SFTP browser: View → File Transfer, then pick a session from the panel
Open the Tunnels panel and start a port forward: View → Tunnels → + New Tunnel (see Port Forwarding)

What just happened¶

When you saved, Cleat wrote your connection profile to ~/.config/cleat/connections.json (or the platform equivalent — see Where things live). The private key was not copied — Cleat stores only a path reference, so rotating keys outside Cleat keeps working. Passwords, when used, go into the OS keychain.