# What happens when you type ssh

> A step-by-step walk through one Nokku connection, and the tricks that make it feel like plain ssh.

This page follows one connection from your keyboard to a shell on the server. It is the last page of this section, so it assumes you've read [Principals](/docs/learn/principals).

The goal behind everything here: you type the same `ssh` command you always did, and Nokku does its work where you don't see it.

## The setup nk does once

When you run `nk login`, `nk` fetches the list of servers you can reach and writes a regular OpenSSH config file for them in its own folder. It adds one `Include` line at the top of your own `~/.ssh/config` so `ssh` reads it. Your own settings stay untouched.

For every server there's a normal `Host` block. The interesting lines are two hooks that let `nk` step in at the right moments.

## The connection, step by step

Say you run `ssh ubuntu@web-01`.

Here is the whole flow at a glance. The steps below explain each part.

```mermaid
sequenceDiagram
  participant ssh
  participant nk
  participant Core as Nokku core
  participant Server as web-01 (nokkud)
  ssh->>nk: nk prepare
  nk->>Core: Renew certificate, if needed
  Core-->>nk: Fresh certificate
  ssh->>nk: nk proxy
  par Direct
    nk->>Server: Connect to port 4022
  and Relay, a moment later
    nk->>Core: Open relay
    Core->>Server: Over the daemon's connection
  end
  Note over nk,Server: The first path to connect wins
  ssh->>Server: SSH login with the certificate
  Note over Server: Checks CA, expiry and access list
  Server-->>ssh: Shell as ubuntu
```

1. **ssh reads the config**

   OpenSSH finds the `web-01` block that `nk` generated. It learns which certificate file to use, which server key to trust, and that it should reach the server through `nk`.

2. **nk renews the certificate if needed**

   Before `ssh` reads the certificate file, a `Match ... exec` line runs `nk prepare`. If your certificate is missing or about to expire, `nk` gets a fresh one from the core right now.

   **The trick:** `ssh` loads the certificate before it opens the connection. Renewing in the connection step would be too late for this login, so `nk` hooks in earlier.

3. **nk finds a way to the server**

   `ssh` hands the network part to `nk proxy`. It first refreshes your access list if it is a little old, so new grants work immediately.

   Then it tries **every address** of the server at the same time. For servers running `nokkud` it also starts a **relay** through the core a moment later. Whichever connects first wins, and the others are dropped.

   **The trick:** a server behind NAT or a firewall still works, without a VPN and without opening ports. And a reachable server never waits for the relay.

4. **Your client checks the server**

   The server presents its host certificate. `nk` wrote the workspace CA into its
   own `known_hosts` file, so `ssh` can verify the server on the spot. No "are
   you sure?" prompt.

5. **Your laptop proves who you are**

   The server sends its challenge. A small background **agent** started by `nk`
   signs it. On machines with a TPM chip, the private key lives inside the chip
   and can't be copied off the laptop. With a security key, `ssh` asks the key
   itself, and you touch it.

6. **The server decides**

   The server checks that the certificate is signed by the workspace CA and still valid, then checks that it names you, this server and `ubuntu`, and that the same entry is in its list for `ubuntu`. Both pass, so it starts a shell as `ubuntu`. If recording is on, the session is recorded.

## The relay can't read your session

The relay only passes bytes along. The SSH connection is encrypted from your laptop to the server, exactly as with a direct connection, so the core sees scrambled data it cannot decrypt. It's the same idea as a letter in a sealed envelope traveling through a post office.

Servers set up [without the daemon](/docs/servers/without-daemon) have no relay. They are always reached directly.

## When the core is down

Nokku is built so an outage of the core doesn't lock anyone out:

- `nk` keeps a copy of your access list and your certificates. While the certificate for a server is valid, `ssh` to it keeps working.
- Each server with `nokkud` keeps its list of who may log in. Logins are checked against that list, not against the core.
- What stops working until the core is back: new certificates, access changes, and the relay.

**Under the hood**

- The generated `Host` block sets `ProxyCommand nk proxy <target-id> %p`, `HostKeyAlias <target-id>`, `CertificateFile`, `IdentityAgent` and a `UserKnownHostsFile` that only `nk` writes. `known_hosts` entries are scoped to the target ID, never to `*`.
- `nk` keeps one certificate per server. `nk prepare` renews it once half of its lifetime is over. If that fails the certificate keeps working until it expires, and `nk proxy` tries once more when it no longer does.
- A certificate signed before a grant doesn't name the new account. `nk proxy` fetches a new one when the access refresh shows such an account. `ssh` may have read the old file by then, so the first login as a new account can need a second try.
- Direct dials start right away, each with a short timeout. The relay joins after a small head start, or at once when every direct dial has failed.
- A session through the relay has an upper time limit. A direct session has none.
- The agent is a hidden `nk agent` process on a unix socket (a named pipe on Windows). It stops after a while without use and starts again on the next connection.
- Without a TPM, `nk` uses a software key that is wrapped with a key derived from the machine, so the file is useless on another machine. `--require-tpm` refuses this fallback.
- Calls from `nk` and `nokkud` to the core are bound to a machine key with DPoP (RFC 9449). A stolen session token doesn't work from another machine.
