sodimo

Chapter 40 / 40

SSH basics

SSH — Secure Shell — is the tool a technical operator uses to log into the Framework Desktop from a laptop, type commands at it, and see what is happening inside the box. It is the admin door, not the front door. The CRM, the mail archive, the chat interface, the manual — none of these need SSH. You reach those through your browser, through the launchpad, through the Google Workspace login.

You encounter SSH in three situations:

  1. Thomas encounters it every day during the engagement — SSH is the main way he reaches the harness for configuration work.
  2. After handoff, one person at Sodimo needs the same capability — whoever inherits day-to-day maintenance of the box. This chapter is written primarily for that person.
  3. During onboarding of a new engineer (or a contractor standing in for Thomas), setting up their SSH key is the first step.

If you are Rani, Paul, Jack, or a non-technical teammate, you almost certainly will not touch SSH. You can read this chapter once to understand what it is, and move on.

Status: Planned — SSH access is live on Thomas’s side from day one of the engagement. The Sodimo-side setup — a second key held by whoever maintains the box after handoff — happens in the last week of the engagement.

What SSH actually is, in one paragraph

SSH is how you get a command-line into a remote computer over the internet, safely. You run ssh harness.sodimo.eu on your laptop; the laptop proves to the server that it is you (using a cryptographic key, not a password); the server opens a terminal that looks and behaves as if you were sitting in front of the box. Everything you type is encrypted. Nothing you type is visible to anyone between your laptop and the box. It has been the universal standard for remote administration for twenty-five years.

What an SSH key actually is

An SSH key is a pair of files — a private key (stays on your laptop, never shared) and a public key (shared freely, added to the server’s allowlist). When you connect, the server sends a challenge that only the holder of the private key can answer. If the answer is correct, you are in. No passwords cross the network; no passwords are stored on the server.

Two consequences follow:

  • The private key is the credential. Treat it the way you would treat your Vaultwarden master password — with the difference that it is one file, on your laptop, encrypted at rest by your laptop’s passphrase. (The private key also lives in Vaultwarden itself, in the SSH-keys collection — Vaultwarden is the authoritative copy; your local ~/.ssh/ is a working copy.)
  • Losing the laptop means losing the key. Which means: you rotate keys when a laptop goes missing (chapter Key rotation), and you keep the key set small (one key per person per laptop, not sprinkled across machines). The baseline rotation cadence is 90 days.

Setting up a new SSH key, from scratch

The walk-through assumes a new Sodimo laptop, a working internet connection, and Claude Code (or a terminal). Every step is something Claude Code can do for you — but the commands are spelled out so you can read what is happening.

Step 1 — generate the keypair.

In a terminal:

ssh-keygen -t ed25519 -C "yourname@sodimo.eu" -f ~/.ssh/sodimo
  • -t ed25519 picks the modern key algorithm. Short, fast, safe.
  • -C "yourname@sodimo.eu" is a comment that identifies the key — who it belongs to. This is cosmetic; it is visible when someone lists the server’s allowed keys.
  • -f ~/.ssh/sodimo names the output files. You end up with ~/.ssh/sodimo (private) and ~/.ssh/sodimo.pub (public).

ssh-keygen asks you for a passphrase. Set one. A passphrase on the private key means a stolen laptop cannot be used as your SSH identity even if the disk is unlocked. Pick something memorable — it is typed rarely, once per session, via ssh-agent.

Step 2 — configure ~/.ssh/config so the key is used for the right host.

Open (or create) ~/.ssh/config, add:

Host harness.sodimo.eu
  User sodimo
  IdentityFile ~/.ssh/sodimo
  AddKeysToAgent yes
  UseKeychain yes

This tells SSH: “when I ssh harness.sodimo.eu, use the sodimo key and remember the passphrase in the agent for the session.”

Step 3 — put the public key in the vault and on the server.

Ask Claude Code:

Add my new SSH public key — the one at ~/.ssh/sodimo.pub — to the vault under my name, and add it to the harness’s authorised keys.

Claude Code will:

  1. Read both keys — the public one (.pub) and the private one — from your file.
  2. Create a new Vaultwarden entry in the SSH-keys collection named yourname — harness, with today’s date and your initials stamped into custom fields, the public key in one field and the private key in a secure-note field. (Keeping the pair together makes Vaultwarden the single source of truth for “which key does yourname use”.)
  3. Append the public key to the harness’s /home/sodimo/.ssh/authorized_keys through a maintenance channel (during the engagement, Thomas does this step; after handoff, it is done via a short Cockpit action or a root SSH from Thomas’s still-live key).
  4. Ask you to test: ssh harness.sodimo.eu — it should prompt for the passphrase once, then drop you at a shell.

Step 4 — verify, then walk away.

Close the SSH session. Open a new one. You should only be prompted for the passphrase once per session (the agent remembers it). Type whoami — you should see sodimo. Type hostname — you should see the harness’s hostname. That is the whole setup.

If you get Permission denied (publickey), the public key did not land correctly on the server. Re-run step 3 and watch the output. The most common cause is copying the private key instead of the public one — the file you want ends in .pub.

Day-to-day use

Once the key is set up, SSH is nothing more than ssh harness.sodimo.eu. You land in a shell on the box. Every tool on the harness (Cockpit aside) can be administered from that shell — systemctl status ... to check a service, journalctl -u ... to read logs, podman ps to see what containers are running. The Harness chapter (Part 30) lists the common maintenance commands.

Two nudges:

  • Stay in SSH only as long as you need to be. Close the session when you are done. The open session is another point of risk.
  • Prefer Cockpit for read-only checks. Cockpit is a web UI on admin.sodimo.eu that covers 80% of the checks an operator runs — services, logs, disks, network. SSH is for the other 20%: changes, deep logs, emergency recovery.

Getting the key into the vault

Covered in step 3 above. The full mechanics — including how to grant someone else access to your SSH slice of the vault, and how to remove a key from the vault when a laptop is retired — are in the Account vault basics chapter and the Key rotation chapter. This chapter deliberately stays at the “your first SSH key, from scratch” level.

Sodimo’s SSH access model, in one glance

  • Thomas — has SSH during the engagement. Key lives on Thomas’s machines; public key is on the harness. Revoked at handoff per the Key rotation chapter.
  • Whoever maintains the box after handoff — one Sodimo person holds the post-handoff SSH key. Added in the last week of the engagement, tested, and stored in the vault.
  • Nobody else. Rani, Paul, Jack, future marketing hires, the intern — none of these need SSH. They reach the box through the launchpad (chapter The launchpad), same as everyone else.

The SSH door is deliberately narrow. Few keys, rotated every 90 days (see chapter Key rotation), audited in Vaultwarden. The front door — Cloudflare Access + Google Workspace — carries the rest of the traffic.