Architecture

There are three parts: the server, an agent on each managed host, and a small privileged executor that the agent talks to locally. Agents only ever connect out. The server never connects in to a host, so every channel below is started by the agent.

On this page: Diagram· Trust boundaries· Transport

Component diagram

Solid lines are implemented, dashed lines are planned. The dotted box is one physical or virtual host. The agent and executor are separate processes on the same machine.

Admin (Browser) WebAuthn / FIDO2 key Vitrinode Server Internal CA · persistent state Proxmox API (read-only) Vitrinode-HSM Signing device · in development Managed host Vitrinode Agent unprivileged · reads host facts Executor (privileged, local-only) Docker Engine inventory only via Docker CLI WebAuthn / FIDO2 Heartbeat, inventory, attestation → mTLS ← Signed jobs mTLS Read-only API calls USB · integration planned Unix socket · typed ops Docker facts Admin (Browser) WebAuthn / FIDO2 Vitrinode-HSM in development Vitrinode Server Internal CA · persistent state Proxmox API (read-only) Managed host Vitrinode Agent unprivileged · reads host facts Executor privileged · local Docker Engine inventory via CLI WebAuthn USB · planned API calls ↑ Heartbeat, inventory, attestation ↓ Signed jobs mTLS Unix socket typed ops Docker facts
Implemented Planned Same host, separate processes

Trust boundaries

Each boundary below uses its own mechanism, so if one of them fails the others still hold.

Human ↔ Server

WebAuthn/FIDO2 plus a server-side session. This is the only boundary a person crosses directly, and there's no password fallback in normal operation.

Server ↔ Agent

Mutual TLS with device certificates issued by the server. Neither side trusts DNS or where a connection comes from. Identity is checked cryptographically at both ends, and a revoked certificate is refused on every request, not just at the handshake.

Agent ↔ Executor

A local Unix socket with permission checks, limited to a fixed set of typed operations. If the agent is compromised it still can't run whatever it likes as root. The executor checks each job's signature and target device itself and doesn't take the agent's word for it.

Server ↔ Proxmox

A dedicated read-only Proxmox API token over TLS, with the certificate explicitly trusted. VM and container details are synced periodically. Start, stop and other lifecycle actions aren't implemented.

Administrator ↔ managed host over SSH in development

After a security-key check tied to the request, the server issues a short-lived OpenSSH user certificate for the principals that administrator is allowed. From there it's a normal OpenSSH session. Vitrinode doesn't proxy or record it. Each certificate names one managed device. On that host, a helper run by sshd checks the device, that the account is set up for certificate login, the lifetime and the extensions before the login is accepted. The executor installs the CA public key only if it matches a fingerprint pinned at provisioning. The development build signs with a development-only software CA.

Server ↔ HSM prototype

A Vitrinode-HSM device holds the SSH user CA key and will only issue OpenSSH user certificates that pass its policy, over a framed binary protocol on a local USB link. It generates the key itself and never exports it, and there's no raw signing operation to misuse. Once integrated, the server will refuse to issue if the device is missing or isn't the one it was commissioned with, but that isn't implemented yet. Signing works on real hardware. The device isn't connected to the server yet.

Transport

Four channels are implemented, all started by the agent. The planned HSM link is local USB between the server and the device, not a network channel.

Heartbeat

Small and frequent. Shows the host is alive and picks up big state changes. It never writes a full inventory record.

Inventory

Bigger and less often: system, storage, network, systemd, APT and Docker facts. Deduplicated by content hash, so a host that hasn't changed doesn't create a new record every cycle.

Job poll

A long poll delivers signed, typed jobs almost immediately without needing a message broker. Expiry and nonce checks stop old or replayed jobs running.

Attestation

The agent asks for a fresh challenge and sends back a TPM quote over measured-boot PCR state, or the weaker software evidence on hosts without a TPM. The server checks it and sets the device's trust state, which decides whether it can get privileged jobs.

HSM signing link planned

Not an agent channel. It's a local USB link between the server and a Vitrinode-HSM device, with framed request and response messages and one operation at a time. No key material goes over it, just the certificate request and the certificate that comes back.