Machines: enrollment and authentication
A machine cannot enrol itself, and there is no registration token that would let anything holding it become a runner.
There is no registration endpoint
A machine cannot enrol itself, and there is no registration token that would let anything holding it become a runner. Enrollment is a two-step owner act:
- On the prospective machine, a P-256 key pair is generated locally and a certificate signing request is produced.
- The owner admits the machine from the control plane, which issues a short-lived leaf from the intermediate.
Admission performs four checks, each with its own named refusal rather than a generic error:
| Check | What it proves |
|---|---|
| CSR self-signature validates | The requester holds the corresponding private key |
| Certificate is inside its validity window | Expired is reported as expired, not as a parse failure |
| Certificate Common Name equals the machine identifier literally | The cryptographic identity is bound to the fleet-visible name |
| Machine is not already admitted | No silent re-admission |
On success a root-signed record is appended to the signed identity log.
What is recorded
Machine identifier, host reference, transport (local or SSH), key suite, execution slot count, admitting actor, admission timestamp, and connection parameters — with any key referenced by path, never by value. Identity and transport are deliberately separate concerns: how a machine is reached can change without re-establishing who it is.
Transport and host authentication
The control plane connects outward only. Machines never dial the control plane, never poll it, and hold no credential to it. The product opens no listening port on a runner.
| Setting | Value | Why |
|---|---|---|
| Client | The system SSH binary, not an embedded library | Avoids a well-known class of host-verification defect in language-level SSH clients |
StrictHostKeyChecking | yes, unconditionally, including for machines on the permissive rotation tier | Host key pinning is the per-connection authentication |
BatchMode | yes | No interactive prompt can ever be what lets a connection through |
ConnectTimeout | 15 seconds | Bounded failure |
SendEnv | negated for all variables | No environment forwarding to a runner |
| Client process environment | Only PATH and HOME | The control plane's environment is not inherited by the SSH client |
| Configuration file | Generated by the engine from the machine registry, regenerable | Your own SSH configuration is never modified |
Host key rotation is handled by policy, not by hand. On a real fleet machines legitimately regenerate host keys — one of ours does so a few seconds after every boot. The alternative to policy is a human editing a trust file whenever it happens, which is exactly the habit that makes a genuine key substitution invisible.
Each machine carries a policy on a two-value closed set, validated when configuration loads, not on first use:
| Tier | Effect |
|---|---|
refuse (default) | A changed host key aborts the connection |
accept_rotation | The pin may be updated automatically, as a recorded event. Does not disable strict checking. |
The pin is reconciled before each connection, resolved against the effective SSH configuration and stored in the same form the SSH client uses. First contact with an unknown host is never treated as a rotation — the answer to an unknown host is to admit the machine.
The topology trade, stated plainly
In our favour: a compromised runner holds no credential to the control plane, cannot reach peers through it, and has no identity assertion to forge, since it never initiates.
Against us: the control plane holds the means to reach every machine, making it the asset to protect — and each runner must be reachable. Section 11 states what a compromised control plane can and cannot currently be prevented from doing.
Identity and PKI
The accepted algorithm set is closed, and the algorithm name is part of the signed material — so a signature produced under one algorithm cannot be reinterpreted under another.
Capability: what a machine is trusted to be able to do
Fleet configuration accumulates claims — "this machine has the toolchain", "this machine can run that backend".