---
id: ssh-keys
title: SSH keys
sidebar_label: SSH keys
---

Vantage holds a library of public keys and decides, per server, which ones
belong in `/root/.ssh/authorized_keys`. The agent makes the file match.

:::info root only
Vantage manages `/root/.ssh/authorized_keys` and nothing else. There is no
per-user key management. The agent runs as root because writing that file
requires it.
:::

## Adding a key

### Upload one you already have

**Keys → Add key**, paste the public half. Vantage stores the public key and its
fingerprint, and never needs the private half for this path.

### Generate one on a server

Vantage can have a managed machine generate a keypair for you. The public half
comes back to the library. You may optionally upload the private half too, in which case it is
stored **AES-256-GCM encrypted** under `KEY_ENCRYPTION_KEY`.

Vantage never displays stored private key material in a list. Retrieving one is
a separate, deliberate action, and it is written to the audit log.

:::tip Why store a private key at all
The [browser console](./browser-console.md) needs one to open an SSH session. If
you are not using the console, do not upload private halves.
:::

## Assigning

Assign a key to one or more servers. The agent picks up the change within about
30 seconds.

## Revoking

Revoking marks the assignment revoked, with a timestamp, rather than erasing it,
so the record of who had access to what, and when, survives.

The agent treats a revoked assignment as "not desired" and removes the line from
`authorized_keys` on its next sync.

:::warning Revoking does not close open sessions
It removes the key from the file. An SSH session already established stays up
until it ends. Kill sessions on the machine if that matters.
:::

## What the agent actually does

Each poll:

1. The control plane returns the desired set of public keys for that server.
2. The agent reads `/root/.ssh/authorized_keys` and computes fingerprints.
3. **If they match, it writes nothing.** That is true of almost every check.
4. If they differ, it writes the new file alongside the old one and swaps it in
   one step.

The swap cannot be interrupted halfway, so a machine that loses power mid-change
keeps its old, working file.

:::danger Vantage owns the whole file
The agent rewrites `authorized_keys` to match the desired set. Keys added by
hand on the machine are removed on the next change. If a key must survive, put
it in Vantage.
:::

## Recovering from a lockout

If you have removed every key from a machine and cannot get in, you still have
the console, provided a private key is stored, or whatever out-of-band access
your hosting provider offers. Vantage has no backdoor and does not keep a break-glass key.