Configuration

For whoever owns the deployment's secrets and toggles. It is the reference for every environment variable you set when deploying Cat Factory, grouped by concern: authentication, model providers, infrastructure, service wiring, and feature toggles. The full generated list of variables, including ones no page here narrates, is Environment Variables.

When a required value is missing

A mandatory variable that is missing or invalid does not crash-loop the container. The backend starts anyway and serves a minimal fallback: the health check returns 200 with status misconfigured (so the orchestrator keeps the container alive instead of restarting it in a loop that hides the problem), and the SPA branches to a full-screen Backend not configured screen listing each problem with the variable name, what it is for, how to fix it, and a link to the matching documentation. Only variable names and remedies are shown, never any secret value, so the screen and the matching boot log are safe to share. The same structured problem list is returned as a 503 to non-browser callers.

The values validated this way include DATABASE_URL, ENCRYPTION_KEY (present, valid base64, decodes to ≥ 32 bytes), AUTH_SESSION_SECRET, HARNESS_SHARED_SECRET, TELEMETRY_DB (on the Worker), the primary DB binding (on the Worker), a login provider on a remote deployment, the container-executor wiring, a DB_SCHEMA that isn't a valid Postgres identifier, and malformed AGENT_MODELS JSON. GITHUB_APP_PRIVATE_KEY (and the privileged App key) must be a PKCS#8 PEM; a GitHub-issued PKCS#1 BEGIN RSA PRIVATE KEY is rejected with the exact openssl pkcs8 -topk8 conversion to run. Setting REDIS_URL without the optional ioredis package installed is also fatal, with the pnpm add ioredis fix. Fix the listed values and reload.

Warnings that don't block boot

Some misconfigurations are logged as a single structured warning (with a doc link) and boot continues on the built-in default rather than stopping:

• A numeric knob set to a non-numeric value (for example AGENT_MAX_OUTPUT_TOKENS, CONTAINER_MAX_AGE_MINUTES, or any of the retention-day vars) logs NAME is set to "…", which is not a number — ignoring it and using the built-in default and falls back.
• Only one half of CLOUDFLARE_ACCOUNT_ID / CLOUDFLARE_API_TOKEN being set names the missing half.
• REDIS_URL set but unreachable: a boot probe logs the credential-free host:port and a redis-cli -u <REDIS_URL> ping check to run, then continues (cross-node coordination stays off until Redis answers).
• In local mode, a GITHUB_PAT that fails a quick GET /user probe (revoked, forbidden, or missing the repo/workflow scopes) logs a warning with a pre-scoped token-creation link.

One boot check is deliberately fatal-then-recoverable: when the database refuses the connection on a loopback host (a localhost that resolves to IPv6 ::1 on Windows or Docker Desktop, a common footgun), the misconfigured screen names DATABASE_URL and the 127.0.0.1 fix, rather than crash-looping. A refused connection to a remote database still crashes and retries, so a transient outage isn't frozen behind the screen.

Elaborated failure messages

Runtime failures an operator has to act on now carry a structured cause, a fix, and a doc link while preserving the original error text: rejected GitHub/GitLab API calls (per HTTP status), GitHub App installation-token mint failures, webhook signature rejections (logged operator-side with the env var to compare, while the caller still gets a terse 401), credential-decryption failures (which name whether the ENCRYPTION_KEY was rotated or a stored secret is corrupted), unsupported model or Bedrock models, and container/runner dispatch failures (a 404 names a stale executor-harness image). These surface in the boot log and, where they belong to a run, on the run's step (see Observability → Run and step diagnostics).

Health vs. readiness

The Node backend exposes two public endpoints. GET /health is a static liveness signal (200{status:"ok"}, or misconfigured above) that your orchestrator restarts on. GET /ready is a readiness signal a load balancer drains on: it round-trips the Postgres pool with a bounded SELECT 1 and checks the pg-boss worker, returning 200 {status:"ready"} or 503{status:"not_ready"} with a per-check breakdown, and flips to not-ready the moment graceful shutdown begins. The Cloudflare Worker has no long-lived process and no readiness endpoint.

Authentication

A deployment can offer three sign-in providers in any combination: GitHub OAuth, Google OAuth, and email/password. Auth turns on as soon as any provider is configured together with a strong AUTH_SESSION_SECRET; each provider stays off until its own credentials are present. Regardless of how people sign in, repository access comes from the Register the GitHub App installation unless a run's initiator has stored a personal token, so a Google- or password-only user works fully. See Which credential a run pushes with. For who is allowed to create an account and how roles and invitations work, see Invite and Manage Your Team.

New-user creation is invite-only unless an email domain is allowlisted: a person gets in by redeeming an email invitation or by signing up with an address on AUTH_ALLOWED_EMAIL_DOMAINS. With neither, signup is refused.

Password sign-in is rate-limited on a durable, cross-replica ledger rather than per process, so the throttle holds on a multi-replica deployment. It applies a burst cap per IP and email pair plus an aggregate per IP against credential stuffing. An in-process counter remains as the backstop for when the ledger itself is unreachable.

A remote (hosted) Node deployment has no anonymous tier: it fails to boot unless at least one provider is configured (GitHub OAuth, Google OAuth, or AUTH_PASSWORD_ENABLED with a strong AUTH_SESSION_SECRET). Users can also sign in with their own GitHub or GitLab PAT: they paste the token, the server resolves it to their account, and the same AUTH_ALLOWED_LOGINS / AUTH_ALLOWED_ORGS / AUTH_ALLOWED_EMAIL_DOMAINS allowlists decide who gets in (it fails closed when all three are empty). Local mode is the exception: it signs in with the deployment's configured PAT or a local password. GitLab PAT sign-in is offered only when the deployment has a GitLab connection configured (GITLAB_TOKEN, below); GitLab group membership then counts toward AUTH_ALLOWED_ORGS, matching GitHub.

What a personal access token can do on the run path

A PAT is the operational credential on two deployment shapes, not just a sign-in identity. In local mode one token is both the identity and what every agent step clones, pushes and merges with. On a hosted deployment, a run initiator's stored github_pat outranks the GitHub App installation on the run path, unless the workspace turns that off. On both, a token too narrow for the work would otherwise reach its first failure several steps into a pipeline, as a 403 out of a container.

Three surfaces report what the token in use can actually do, from one classification and one required-scope list: the connect form's warnings when a token is stored, the local deployment's boot log, and a check on board load that resolves the token a run would present through the same path the dispatch mint uses. That last one raises a banner only on an established blocking gap or a rejected token, and names whether the credential is the deployment's or the signed-in user's. See Troubleshooting → a step fails cloning, pushing or merging.

The token's raw scope list is deliberately not published on that response: any member can read it, and the breadth of a shared deployment credential is not a member-level fact. The per-capability verdict is what a reader can act on. None of this narrows a token either. Mint a fine-grained PAT restricted to the repositories the deployment works on rather than relying on a check to catch a broad one.

GitLab (source control)

GitLab is a first-class source-control backend on every runtime, not just local mode. It is opt-in and off until you set a token. With it configured, a GitLab repo clones, pushes, gates on real CI, and merges through a real merge request, and users can sign in with a GitLab PAT. See Connect a Repository → GitLab.

LLM providers

Direct provider API keys (OpenAI, Anthropic, Qwen, DeepSeek, Moonshot, OpenRouter, LiteLLM) are onboarded in the UI, scoped to an account, workspace, or user, pooled, and stored encrypted under ENCRYPTION_KEY. The same is true of vendor credentials: a coding-plan subscription (Claude, GLM, or Codex, kept per-user) or a poolable vendor credential (Kimi, DeepSeek), run through the Claude Code or Codex harness. None of these needs a provider env var; they only need ENCRYPTION_KEY set. Local runners (Ollama, LM Studio, …) are likewise pure per-user UI configuration with no deployment env var. See Connect a Model Provider.

What stays in the environment is the Cloudflare Workers AI fallback, AWS Bedrock, the aggregator-gateway base URLs, and routing defaults:

With no Cloudflare provider registered and no keys connected, a model has nothing to resolve to (the picker shows nothing selectable). Default routing is tunable with AGENT_DEFAULT_PROVIDER, AGENT_DEFAULT_MODEL, AGENT_DEFAULT_TEMPERATURE, AGENT_MAX_OUTPUT_TOKENS, and per-kind overrides via AGENT_MODELS; a workspace can override the model per agent kind at runtime (see Choosing models).

Credential encryption

One shared master key encrypts every integration's per-workspace credentials at rest: connected Jira sites, runner-pool API tokens, environment-provider auth, Slack bot tokens, and pooled or personal model subscriptions. The cipher domain-separates per integration internally, so a single key is safe across all of them.

Spend caps (operator ceilings)

Workspace, account, and per-user monthly budgets are set in the UI (see Control Spend with Budgets). Two optional env vars let an operator impose a hard ceiling that a user cannot exceed from the UI:

Each applies only when set to a finite number >= 0; unset means no operator ceiling for that tier. The caps are in the base pricing currency and are surfaced read-only in the budget UI, where the matching field is clamped to the cap and Save is refused above it.

Infrastructure

When a workspace is missing infrastructure a run needs, the app says so up front rather than failing mid-run. It raises a per-area setup banner, with a deep link to the right config screen, when ephemeral environments, the agent executor (self-hosted runner pool, remote Node), or binary content storage is undefined. Each banner can be dismissed for the session or permanently per user.

Content storage (binary artifacts)

The Tester's screenshots for the Visual Confirmation gate are kept in a binary-artifact store. This is configured per account in the UI (Account → Deployment settings), not through environment variables, and each account picks its own backend:

The default is fs on local, r2 on Cloudflare, and off on Node until an account configures one. A pipeline that includes an agent needing binary storage (the UI Tester, which uploads its screenshots) is refused at start when the account has no store configured, with a message that names the fix, rather than failing mid-run. Pipelines that don't use such an agent are unaffected. Switching an account's backend orphans artifacts stored under the previous one.

Node container execution

On the Node.js runtime, repo-operating agent kinds run on a runner pool, and that path only activates once the deployment can mint per-run GitHub tokens and dispatch jobs securely. All of the following must be set; otherwise inline kinds still work and container kinds fail loudly instead of faking success:

Multi-node coordination (Redis)

A Node.js deployment running more than one instance uses Redis to keep replicas in sync: live board events reach browsers on every node, and each node drops stale in-memory cache entries after a write on another node. A single instance and local mode need none of this; the Cloudflare Worker coordinates through its own globally-addressed primitives.

Redis is only ever a message bus for these signals, never a data tier: a node always repopulates its own in-memory state on a miss, and only keys travel on the wire, never values.

Private package registries

Agent containers resolve private npm dependencies from registries you connect per workspace in the UI (the Infrastructure window's Private package registries tab), not through environment variables. The feature is available whenever ENCRYPTION_KEY is set (it seals the tokens at rest); with no key the panel and its API return a "not configured" state.

Each entry names an ecosystem (npm today), a vendor, the npm scopes it covers, and a token:

You pick the vendor rather than typing a URL: the host is fixed per vendor. Scopes are npm @org names the token can install. Tokens are write-only, shown afterward only as a …tail of the last four characters; to change one, remove the entry and re-add it. One entry per vendor per workspace. Before any agent runs, the harness renders these into a locked-down ~/.npmrc scoped to the two allowed hosts, read by npm, pnpm, and yarn v1. Tokens are registered for output redaction.

Capability credentials

A deployment's MCP tool servers and generative integrations declare the secrets they need by name. Fill those names in per workspace on the Infrastructure window's Capability credentials tab, which sits beside the package registries because what an agent's tools authenticate as belongs with where those agents run. The tab needs secrets.manage.

The panel is a checklist projected from the deployment's own registrations, never a blank key-value form. Each row names the key, who asks for it (a tool server or a generative integration), whether it is required, and when it was last set. Values are write-only: a stored value is replaced by typing a new one and is never read back.

An empty row means one of three things, kept apart because each needs a different reaction:

• Nothing stored for this board, but the deployment also reads the key from its own environment, so the capability may still be working.
• Nothing stored and no environment fallback, so the capability cannot authenticate.
• The deployment supplied its own credential chain, so whether the key is answered elsewhere cannot be described here.

Keys that are stored but that nothing registered asks for are listed separately as Stored but not asked for, which is what a retired integration or a renamed variable leaves behind. They stay sealed until you remove them. If the declaration list itself cannot be read, the panel says so and withholds the orphan list rather than reporting every credential as orphaned.

A multi-tenant deployment can drop the environment fallback entirely and make the per-workspace store the only source, so one process serving many workspaces never answers every tenant with one variable.

Service configuration

CORS fails safe in production. When CORS_ALLOWED_ORIGINS is unset, the API reflects any origin only when ENVIRONMENT is one of the recognized development values above. An unset, unknown, or production ENVIRONMENT with no CORS_ALLOWED_ORIGINS denies cross-origin browser calls rather than silently allowing them, so set CORS_ALLOWED_ORIGINS explicitly on any shared deployment.

Web search

Web search is opt-in and no-op until configured. It comes in two independent surfaces, and no provider key ever enters the per-run container: container agents reach search through a backend proxy.

Inline search only takes effect on providers with a hosted search tool (Anthropic / OpenAI).

Document & task sources

Document sources (Confluence, Notion, GitHub repo docs, the Figma and Zeplin design-context sources, and Linear Docs) and the Jira task source are always on: they ship enabled and each workspace connects its own site through the UI, with credentials stored encrypted under ENCRYPTION_KEY. There is no per-integration enable flag. The integrations fail loudly at boot if ENCRYPTION_KEY is missing rather than silently returning errors later.

Each workspace connects its own sites from the Integrations panel (sidebar → Integrations), which lists model providers alongside the document and task-tracker sources:

Task sources (Jira, GitHub Issues, and Linear) are configured per workspace. Each workspace turns its sources on or off in the UI (Workspace settings → Issue tracker); they work on every runtime, GitHub Issues rides the per-tenant GitHub App installation (or, in local mode, the PAT) with no env, and Linear connects per workspace via OAuth or a personal API key. See Connect Issue & Document Sources. The tech-debt recurring pipeline files its ticket through the workspace's chosen filing tracker.

Observability

Every model call is metered for the spend gauge and the in-app observability dashboard. Two optional settings tune what is recorded and where it is sent. Both are covered in depth in Observability.

Langfuse honours LLM_RECORD_PROMPTS: with prompts off, the traces carry only numeric telemetry.

Telemetry store

Call metrics and full agent-context snapshots live in an isolated telemetry store, separate from the main application database. On Cloudflare it is a dedicated D1 database; on Node and local it is a telemetry schema inside the existing DATABASE_URL database. A retention cron prunes it on a schedule. See Observability → The telemetry store.

The post-release-health gate and Agent-On-Call watch production through a pluggable observability provider (Datadog today) after a merge. They are opt-in and covered in Observability → Post-release health.

Notifications (Slack and webhooks)

Board notifications (merge reviews, pipeline completions, CI failures, requirement reviews) land in the in-app inbox by default. Slack and a per-workspace outbound webhook are optional extra transports. Both are opt-in and configured per workspace, and their secrets are encrypted under ENCRYPTION_KEY. Full setup is in Set Up Notifications.

Email (invitations)

Email carries invitation links. There is no separate enable flag: email is available whenever an encryption key is set (the per-account API key is sealed with it). The provider, API key, and From address are then onboarded per account in the UI and stored sealed in the database (like the Slack bot token). Adapters exist for SendGrid and Resend. With no sender connected, invitations still work: the accept link is returned for manual sharing.

Feature toggles

Optional integrations enabled by their own flag:

Ephemeral environments have no enable flag. The module assembles wherever ENCRYPTION_KEY is set (it seals environment-provider credentials under that key), the same always-on-where-the-key-is-present model as the document and task sources. It stays inert until a workspace registers an infrastructure handler and a pipeline includes a deployer/tester step, so there is nothing to turn on at the deployment level.

Next: scale execution with Run Jobs on Your Own Runners and Provision Ephemeral Environments, or check a value you set against Troubleshooting.