Secrets layout

This page lists where secrets live, what they are called and who owns them. It never holds a value. A build check fails the whole site if anything key-shaped appears here.

The rules

• Secrets are files in one secrets directory, outside the checkout, mode 0700 (local) with each file mode 0600. In the AWS tenant they are in /run/forelead/secrets, owner uid 10001, mode 0400.
• Put a secret there with forelead_secret_put NAME < source-file (single-host guide). It sets owner and mode and refuses an empty file. Never put a value in a command line, shell history or the checkout.
• The PKI directory (FORELEAD_PKI_DIR) is a different directory and must not sit inside the secrets directory.
• The agent and the sandbox never get these files. Provider keys are read only by the broker; the GitHub App key only by the control plane.

Local stack (FORELEAD_SECRETS_DIR)

Files	Owner inside the container	Mode
app_pgpass, migrator_pgpass, gateway_pgpass, modelwatcher_pgpass, broker_config.json, model-watcher.json, model_key, oidc_google_client_secret, oidc_microsoft_client_secret, and every *.crt and *.key named in compose.yaml	uid 10001 (platform image)	0600
runner-governance-profile.json, runner-governance-public-key.pem, reconciler-config.json, github-app-key.pem, session-object-access-key, session-object-secret-key, session-object-ca.crt (only with compose.agent.yaml)	uid 10001	0600
postgres_password	uid 999 (postgres:17)	0600
app_password, migrator_password	the root-run bootstrap process only	0600

What the main ones are:

Name	What it is	Read by
model_key	The model provider API key (a Console API key; subscription credentials are refused)	broker
broker_config.json	Model mappings and key file paths	broker
github-app-key.pem	The GitHub App's private key	control plane
reconciler-config.json	Board, repository and agent configuration	control plane, gateway (cache setting)
task-ca.crt / task-ca.key	The CA the broker signs task certificates with	broker (key), runner and gateway (cert)
client-ca.crt	CA that verifies runner and operator certificates	control plane
runner-governance-profile.json, runner-governance-public-key.pem	Signed agent rules and the trusted key that verifies them	control plane, runner
*_pgpass	Per-service Postgres password files	each service

Where the host files live (defaults in upgrade.sh)

Path	Holds
$FORELEAD_HOME (default $HOME/.forelead-96)	The stack's root on the local host
$FORELEAD_HOME/operator	The operator certificate pair
$FORELEAD_HOME/pki/ca	The client CA for issuing operator certificates
$FORELEAD_HOME/live/agent-runner, $FORELEAD_HOME/live/preflight	Runner working directories and their private key files

Instance-specific, non-secret configuration (env files, mirror allow-lists) is kept in the forelead-ai/ops repository under instances/.

AWS tenant secret files (names only)

Host	Files
app	app_pgpass, migrator_pgpass, gateway_pgpass, modelwatcher_pgpass, broker_config.json, model-watcher.json, model-watcher.crt, model-watcher.key, model_key, controlplane.crt, controlplane.key, client-ca.crt, broker.crt, broker.key, broker-ca.crt, gateway-ca.crt, gateway.crt, gateway.key, task-ca.crt, task-ca.key, task-cert-client.crt, task-cert-client.key, reconciler-config.json, github-app-key.pem, runner-governance-profile.json, runner-governance-public-key.pem, runner-model-ca.crt; may be empty: openai_key, oidc_google_client_secret, oidc_microsoft_client_secret
runner	controlplane-ca.crt, runner.crt, runner.key, preflight-runner.crt, preflight-runner.key, runner-preflight.key, task-ca.crt, runner-model-ca.crt, runner-governance-profile.json, runner-governance-public-key.pem; may be empty: ghcr_pull_token
mirror	cloudflare_token, packagemirror-ca.pem, packagemirror-server.pem, packagemirror-server.key

Technical notes

• deploy/cloud/start.sh refuses to start a role when a required secret file is missing or empty, and names it.
• Rotating model_key: forelead_secret_put model_key < replacement, then docker compose -f deploy/compose.yaml up -d --wait --force-recreate so the mounts pick up the new file. Delete a retired secret only after nothing in the current bundle references it. The broker validates Anthropic keys at startup and again when it reads a rotated key.

Sources

• deploy/README.md ("Prepare", "AWS tenant hosts")
• deploy/compose.yaml (the secrets: block), deploy/cloud/start.sh, deploy/upgrade.sh