Your first connection

Add a host, check its fingerprint and open a workspace with Files and a terminal. It takes about a minute, and nothing is written to the server.

Prerequisites

• ShellCanvas installed and open. See Installation and builds.
• A machine you can already reach with ssh, its user name, and either a private key file or the account password.
• For Files and the editor, the server's SFTP subsystem. Terminals work without it.

If you keep entries in ~/.ssh/config, ShellCanvas can read simple ones; you do not have to retype them.

Steps

1. Open the connection dialog. Choose Add host in the top right of the desktop, or Connect another host from the workspace switcher in the top bar. The dialog is headed Make yourself at home.

2. Pick a saved host, or fill in the fields. The Your hosts control at the top lists what is already on this device, including entries imported from ~/.ssh/config; it has a search box and shows a count such as 4 of 4 hosts. For a new machine, fill in:

   • Name — optional, only a label for the list.
   • Host and Port — the address and SSH port, for example server.example.com and 22.
   • Username — the account on the server.

3. Choose how you sign in. Switch between SSH key and Password.

   • For a key, give the Private key path, for example ~/.ssh/id_ed25519, and the Key passphrase if the key has one.
   • For a password, type it in the password field.

   Neither the password nor the passphrase is saved. The dialog says so: Passwords and passphrases are never saved.

4. Save the host if you want it again. Update saved host stores the connection details under the name you gave. Connecting alone does not save anything.

5. Choose Open workspace.

6. Check the fingerprint the first time. For a host key this device has not seen, ShellCanvas stops before authenticating and shows Verify this host. with the address, the key algorithm and the SHA-256 fingerprint, plus Copy fingerprint.

   Compare it with a source you trust — your provider's console, or ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub run on the server itself. Then tick I checked this fingerprint using a trusted source. and choose Trust and connect. Trust is stored by ShellCanvas on this device; your OpenSSH known_hosts file is not modified.

   If the fingerprint does not match, choose Cancel connection. A key that changed after being trusted is refused outright, and that is worth investigating rather than working around.

Expected result

The workspace opens with a Files window and a Terminal window already connected. You should see:

• The host's name in the pill at the top of the screen, with a dot showing it is connected.
• A heading such as A little closer to studio-server., with Known host verified and the system string underneath — for a Linux server that is uname -sr output, for example Linux 6.8.0-45-generic.
• Connected over SSH at the bottom left, and SSH workspace at the top right.
• A dock along the bottom: the app launcher, Text editor, Files, Terminal, Host details, App Manager, Connections and Desktop settings.

Type hostname in the terminal and browse a folder in Files to confirm both channels work. Nothing has been written to the server: the host key is remembered on your computer, and the saved host, if you saved one, lives in your local application data.

Limitations

• Key and password authentication only. SSH agents, hardware keys, host certificates and keyboard-interactive prompts beyond a single password are not supported.
• The fingerprint review expires. It is valid for five minutes and can be used once; if you leave it open too long, start the connection again.
• No automatic retry. A failed or cancelled connection leaves the dialog open with the error, so you can correct a field and try again.
• Recognising a dead connection takes about a minute when a machine disappears without closing the connection, because that is how long the keepalives need.
• Imported ~/.ssh/config entries are simple ones. Only explicit Host blocks with HostName, User, Port and the first IdentityFile are read. Patterns with *, ? or !, Match blocks and ProxyCommand are skipped, and ProxyCommand is never executed.

Related guides

• Saved hosts and SSH config — managing the list and what the importer reads.
• The desktop at a glance — what everything on screen does.
• Connection and host-key problems — when the connection fails.
• Trust and isolation model — why the fingerprint check comes first.