Forelead handbook

Appearance

Certificates and PKI ​

Every machine and operator proves who it is with a short-lived client certificate. Renewal is mostly automatic, but a missed renewal stops that runner or operator, so know what renews what.

What exists ​

CertificateLifetimeRenewed by
Runnerat most 24 hoursdeploy/renew-runner-cert.sh (Compose), or the host mint-cert.sh timer
Operator (browser)24 hoursdeploy/renew-operator-cert.sh --if-needed, from a timer
Service (control plane, broker, gateway)30 daysdeploy/pki.sh issues them; put the new files in the secrets folder
Task (agent to gateway)until the lease expiresthe broker, per lease

Steps ​

  • First time: run deploy/pki.sh once before bootstrap, then again after the workspace ID is known. It creates the CAs and certificate pairs in FORELEAD_PKI_DIR, which must be an absolute private directory outside the checkout and outside the secrets directory. The CAs use name constraints and a 10 year life.
  • Rotate only the runner pair: deploy/pki.sh --renew-runner.
  • Operator certificate: sh deploy/renew-operator-cert.sh --if-needed reissues once two thirds of the life has passed (16 of 24 hours). A browser cannot renew itself: set OPERATOR_CERT_IMPORT_CMD to load the new certificate into the browser store.
  • Runner restart during renewal: the script stops the runner only when idle, swaps the pair, restarts, and restores the old pair if anything fails. On failure it can send a fallback alert to the ntfy topic (NTFY_TOPIC_URL).
  • Install a service certificate: forelead_secret_put NAME < file from the single-host guide, which sets the right owner and mode (see Secrets layout).

Technical notes ​

  • Runner IDs may use only letters, digits, dots, dashes and underscores (1 to 128 characters); pki.sh refuses others.
  • Runner evidence keys are separate from certificates: an Ed25519 pair per runner, approved by an administrator (POST /v1/runner-keys or runnerkey enroll). Rotating needs no restart, but evidence signed under the old key is refused afterwards, so rotate between tasks. See Preflight runner.
  • The operator certificate needs OPERATOR_DIR, CLIENT_CA_DIR and RUNNER_WORKSPACE_ID.

Sources ​