Adding SSH Keys To a Site

SSH access to a Kapsule site is key-based only, so before you can open a shell or an SFTP session you need to register a public key against the site in KPanel. This guide covers where that lives, how to add a key you already have, how to have Kapsule generate one for you, and how to revoke a key you no longer trust.

Where the SSH Keys Page Lives

Open Websites, click the site, then open the Files menu in the site tab strip and choose SSH Keys. The page is titled SSH access and it holds two things: the connection details for this site, and the list of public keys currently authorised to use them.

There is no top-level SSH item in the main sidebar. Keys are per site, so a key you add here authenticates against this site only. If you run several sites, each one needs its own entry, even if it is the same key on your laptop.

Connection Details

The Connection details card at the top of the page shows everything your client needs:

Each row has a copy control, and the SSH and SFTP rows copy the whole command rather than just the value, so you can paste straight into a terminal. Use those two rather than typing the command yourself: they already contain the right user, host and port.

If the card does not appear at all, the site has not finished provisioning its shell user yet. The API returns a plain Site has no SSH user error in that case. Wait for the site status pill to read Active and reload.

Adding a Key You Already Have

Most people already have a key pair on their machine. Add the public half here.

1. On your own computer, print your public key. On macOS and Linux that is usually cat ~/.ssh/id_ed25519.pub, or cat ~/.ssh/id_rsa.pub for an older RSA key. On Windows with OpenSSH it is type %USERPROFILE%\.ssh\id_ed25519.pub.
2. Copy the whole single line, starting with ssh-ed25519, ssh-rsa or ecdsa-sha2-nistp256.
3. In KPanel, click Add key.
4. Put something memorable in the Label field, for example the name of the machine the key lives on.
5. Paste the public key into the second field.
6. Click Add key.

The key appears in the Authorised keys list straight away, with its fingerprint underneath the label. You can connect immediately.

Kapsule also emails the account address every time a key is added, quoting the label, the fingerprint and the site. That mail is deliberate: SSH access is high trust, so if a key appears that you did not add, revoke it and change your password straight away.

If You Do Not Have a Key Yet

Generate one locally with ssh-keygen -t ed25519 -C "your-label", accept the default file location, and set a passphrase when prompted. That produces ~/.ssh/id_ed25519 (keep it private) and ~/.ssh/id_ed25519.pub (paste that one).

Letting Kapsule Generate the Key Pair

If you would rather not run ssh-keygen, KPanel can make the pair for you.

1. Click Add key.
2. Fill in the Label field. Leave the public key box empty.
3. Click Generate keypair.

Kapsule creates an Ed25519 pair, installs the public half against the site, and shows a green banner: Keypair generated: download the private key now. Click Download .pem to save the private key. The file is named after the label you chose.

A generated key has no passphrase on it, which is what makes it usable from a script without prompting. That also means the file itself is the whole credential. If you want a passphrase, generate the pair yourself with ssh-keygen instead and paste the public half.

Once downloaded, move the file somewhere sensible and tighten its permissions, because SSH refuses to use a world-readable private key:

mv ~/Downloads/my-laptop_id_ed25519.pem ~/.ssh/kapsule-mysite.pem
chmod 600 ~/.ssh/kapsule-mysite.pem
ssh -i ~/.ssh/kapsule-mysite.pem <username>@<host> -p <port>

Substitute the username, host and port from the Connection details card.

Reading the Authorised Keys List

Each row in Authorised keys shows:

• The label you gave the key.
• The key fingerprint, which is how you tell two keys apart when the labels are similar.
• Added with the date it was registered.
• Last used with the date of the most recent authentication, or Never used if it has not authenticated yet.

The Last used column is the useful one during a clean-up. A key that has never been used, or has not been used in months, is usually a laptop that has been replaced or a contractor who has moved on.

Revoking a Key

Click the red bin icon on the key's row. KPanel asks you to confirm with Revoke SSH key? and a note that the key will no longer authenticate against this site. Click Revoke to finish.

Revocation takes effect for new connections. An SSH session that is already open is not killed by revoking the key, so if you are removing access from someone who may still be connected, revoke the key and then change anything they could have taken with them: database passwords, application secrets, and any tokens stored on the site.

Troubleshooting

Permission denied (publickey). The most common cause is your client offering a different key from the one you registered. Force the right one with ssh -i /path/to/private_key ..., or check with ssh -v which keys are being offered.

Connection refused or a timeout. Confirm you are using the port shown in Connection details and not the default 22. Copy the SSH command from the page rather than typing it.

Bad permissions on the private key. OpenSSH refuses a private key that other users can read. Run chmod 600 on the file.

The key works for SSH but not SFTP. They share the same credentials, so this is almost always the client rather than the key. Use the SFTP command copied from the page, which already carries the right port.

Where To Go Next

• Uploading Files With SFTP covers the file transfer side of the same credentials.
• Connecting To Your Database Over an SSH Tunnel uses the key you just added to reach MySQL from a desktop client.
• Site Activity Log records every key you add, so you can check later who added what and when.