Environment reference

This is the complete reference for every environment variable, flag and operational parameter CFactory reads — backend, the copilot’s external secret, the frontend build-time bundle, and the frontend container runtime. A fresh operator needs nothing beyond this page plus the .env.example at the repo root.

Almost every backend value is a field on the Settings class in apps/backend/cfactory/config.py (env_prefix="CFACTORY_", .env file support), with one exception — CFACTORY_STALL_DEADLINE_SECONDS is read directly in store.py. Two backend values also accept a bare, un-prefixed alias so they can share the fleet-wide Ollama secret.

Conventions in the tables below:

• Required? — no means the built-in default is fine everywhere; in hosted means it must be set for any shared/multi-user deployment; if provider is X means it is only needed for a particular copilot provider.
• Server-side only secrets are never sent to the browser.

Backend (CFACTORY_*)

Registering the apps is a human step — GitHub shows the App ID and private key to the registrant and to nobody else, and there is no API for it. That is exactly why these are deployment configuration: a self-hosted operator registers their own rather than depending on somebody else’s credentials. The full runbook — permissions to select, events to leave unticked, the callback URL to enter, and what to do with the private key — is Registering the GitHub App and the GitLab OAuth application.

Azure DevOps has no install flow (RFC-0020 §3.4, deliberately). It keeps the pasted-credential path above, and no install button is offered for it.

CFACTORY_CREDENTIAL_KEY, in full

As an operator, I want per-tenant git credentials encrypted with a key I control and can rotate, so that a database dump is not a list of everyone’s tokens and “we have rotated” is something I can actually do.

RFC-0020 §3.4. Each tenant’s git credential is sealed with its own random 256-bit data key (AES-256-GCM); that data key is sealed with this value, and the row records which key version did the wrapping. This is the only thing standing between the tenant_git_credential table and plaintext credentials, so it belongs in the deployment’s secret store (agenix -> the factory-secrets Kubernetes secret), never in a values file or a commit.

Format.

CFACTORY_CREDENTIAL_KEY=v1:<base64 of 32 random bytes>

Bare base64 with no <key-id>: prefix is read as key id v1, so a single-key deployment need not invent one. During a rotation, list several — active key first, every older key still present:

CFACTORY_CREDENTIAL_KEY=v2:<new base64>,v1:<old base64>

How to generate one.

python3 -c "import base64,os;print(base64.b64encode(os.urandom(32)).decode())"

or, equivalently:

openssl rand -base64 32

It must decode to exactly 32 bytes. A passphrase, a truncated value or bad base64 is refused at load with an error saying so — it is never hashed or stretched into something key-shaped, because that would turn a typo into a weaker key nobody notices.

Rotating. Put the new key first and keep the old one listed. Each stored credential is re-wrapped onto the new key the next time it is used, which re-encrypts only the data key and never decrypts the credential. Watch the credential.key_version shown in Settings > Git integration: once every tenant reports the new id, the old key can be dropped from the variable. A tenant whose credential is never used never migrates, so check before you drop.

What happens when it is unset. Storing a credential is refused with a 503 naming the variable, and nothing is written — there is no plaintext fallback and no derived-from-nothing key. Existing deployments are unaffected: tenants keep using CFACTORY_GIT_PROVIDER_TOKEN, exactly as before.

What happens if it is lost. Every stored credential becomes permanently undecryptable. There is no recovery, no escrow and no backdoor — that is what authenticated encryption means. The board does not break: affected tenants report credential_missing, every read keeps serving, and each failed decryption is recorded in the audit chain. The fix is to store the credentials again. Back this value up wherever you back up CFACTORY_AUDIT_HMAC_SECRET.

Copilot external secret

Read by the Claude Agent SDK — not by CFactory code — when CFACTORY_COPILOT_PROVIDER=claude:

Frontend (VITE_*, build-time)

VITE_* variables are read at build time by Vite and inlined into the static bundle (import.meta.env) — they are not runtime container env. Set them as build args / build-environment when running npm run build (or in the frontend image build). Each has a hard-coded fallback, so all are optional.

Frontend container runtime (nginx)

The cockpit is served by nginx, whose config is templated with envsubst at container start. These are container runtime env — not VITE_*, not backend Settings — documented here for completeness.

Secrets checklist

Set these to real values in any hosted/shared deployment — never commit them:

• CFACTORY_AUDIT_HMAC_SECRET — overrides the clearly-labelled dev default; startup hard-warns if the default is left in a non-local posture.
• CFACTORY_CREDENTIAL_KEY — encrypts every per-tenant git credential. Without it, no credential can be stored; lose it and the stored credentials are unrecoverable. Back it up alongside the audit secret.
• CFACTORY_UPSTREAM_TOKEN / CFACTORY_AIFACTORY_TOKEN — upstream factory auth.
• CFACTORY_API_KEYS — scoped keys that gate the cockpit API.
• CFACTORY_MCP_SECRET — legacy full-scope credential for the MCP transport (CFACTORY_API_KEYS also gates /mcp, per declared tool scope).
• CFACTORY_INTAKE_PROJECT_ID — not a secret, and no longer where this is set: since RFC-0020 §3.3 it seeds the tenant’s git config once, and the AIFactory project autonomous card-driven builds land in is edited in Settings > Git integration. Still the one value a hosted deploy must decide deliberately.
• CFACTORY_OLLAMA_API_KEY / ANTHROPIC_API_KEY — copilot credentials.

Notes

• The three upstream endpoints (AIFACTORY/PFACTORY/TFACTORY_API_URL) and the copilot provider + model are also editable at runtime from the cockpit (Services and Settings views). Runtime edits persist to small JSON files under the workspace root and survive a restart; the copilot API key is never written to disk.
• The planning board reads CFACTORY_API_KEYS / CFACTORY_MCP_SECRET (board tool scopes) and CFACTORY_MULTI_TENANT (card partitioning). Each is written up with its user story, options and failure behaviour in the planning-board guide.
• Which git host and project the board syncs with is no longer an environment variable. RFC-0020 §3.3 made it a tenant resource, edited in Settings > Git integration and reachable at /api/tenants/{tenant}/git-config (with MCP twins). The four variables marked DEPRECATED above seed it once on first boot and are removed next release. Since RFC-0020 §3.4 the credential is a tenant resource too (/api/tenants/{tenant}/git-credential, write-only, encrypted with CFACTORY_CREDENTIAL_KEY); CFACTORY_GIT_PROVIDER_TOKEN remains the fallback for any tenant that has stored none.
• Deep operator detail — per-variable read location, Helm knobs and chart gaps — lives in the in-repo TechDocs at techdocs/dependencies.md.