Forelead handbook

Appearance

Architecture ​

Forelead turns a card on a board into a merged pull request, with a person approving the merge. A few services do the work, and they are kept apart on purpose: the part that thinks (an AI agent) never holds a credential, a key or a push right.

The parts, in plain words ​

  • Control plane. The one place that records everything. It serves the web app and the API, reads the GitHub board, hands jobs to runners, publishes commits and checks signatures. Its records live in Postgres.
  • Runner. A worker on a separate host. It asks the control plane for a job (the control plane never calls the runner), then runs the agent and the checks inside a locked-down sandbox.
  • Sandbox. A container run under gVisor (runsc) on a private network with no internet. It can only reach a per-job proxy.
  • Model gateway and credential broker. The agent calls the gateway for model answers. Only the broker holds the provider keys. The agent never sees one.
  • Package mirror. Sandboxes have no internet, so dependencies come from one mirror host that allows only reviewed package names.
  • Preflight runner. A separate trusted runner that proves a repository's environment works at an exact commit before agents start work on it.
  • Evidence store. Gate results, signatures and session logs are kept outside the sandbox (Postgres, and an object bucket in the AWS tenant), so a crash loses nothing.

Technical notes ​

  • One Go module, one binary per service: cmd/controlplane, cmd/runner, cmd/gateway (with cmd/egressproxy), cmd/broker, cmd/packagemirror, cmd/preflight, cmd/migrate, cmd/modelwatcher, cmd/sandbox. The UI is in web/ and talks only to /v1.
  • Ports in the Compose stack: control plane 8443 and 8081 (browser) and 8080 (machine mTLS, runners), broker 8083, gateway 8082 behind 443. See Broker and gateway.
  • The model watcher (cmd/modelwatcher) polls vendor model lists and records candidate alerts. It never changes gateway defaults.
  • The runner itself runs under the normal container runtime, not gVisor. Only the untrusted job containers run under runsc.
  • On a single host everything is one Compose stack. In the AWS tenant there are three hosts: app, runner and mirror (see AWS tenant).

Sources ​