Forelead handbook

Appearance

Preflight runner ​

Before agents work on a repository, a trusted runner checks that the repository's environment actually works at an exact commit: the declared gates run, and the result is signed. This is the preflight runner. It claims only preflight jobs and holds more power than the agent runner, so it is set up with care.

In plain words ​

  • It runs on a dedicated host account that can use Docker, which is root-equivalent. Keep nothing on that host the runner should not reach.
  • It has its own runner ID, its own certificate and its own evidence key. It has no database access: it signs each attempt and sends it to the control plane, which stores it only after checking the signature and that it names the exact leased repository, base commit, image and forelead.env hash.
  • Until an administrator approves the runner's evidence key, the control plane refuses everything it signs.
  • One preflight claim runs at a time on the static network the recipe creates.

Setup in short ​

  1. Install the reviewed runner binary outside agent workspaces; use the runsc runtime for gate containers and run the runner itself on the host.
  2. Preload the exact gateImage digest and postgres:16-alpine; gates run with --pull=never.
  3. Issue a runner certificate and an Ed25519 evidence key; approve the public key (deploy/pki.sh with RUNNER_GATE_PUBLIC_KEY_FILE, or POST /v1/runner-keys).
  4. Create the internal job network and its proxy (commands in the full recipe), then start the runner with RUNNER_LABELS=preflight.
  5. Check the registration log and confirm the only registered label is preflight.

Upgrade the control plane and this runner together: an old runner cannot store evidence, and a new one cannot reach the database. deploy/upgrade.sh recreates the preflight sandbox network and proxy and starts the preflight runner before the agent runner.

Technical notes ​

  • Evidence keys: 64-byte private key as 128 hex characters in a file readable only by the runner (0600); the 32-byte public key as 64 hex characters goes to the administrator. A key cannot be approved for two runners.
  • The recipe is a bounded operator procedure, not automatic per-job network provisioning. Host tests alone are not an acceptance check.

Sources ​