Environment Variables

Every environment variable the Cat Factory backends read, grouped by purpose and annotated with the deployment modes each applies to. This page is generated from the canonical list in the code repository, which a CI guard reads on every change, so the two cannot drift.

That canonical list is the backend's own, and a deployment needs a few things it does not carry — frontend build variables, and integration credentials that are entered in the UI rather than read from the environment. For the narrative on how to configure a deployment (what to set first, what refuses to boot without it), read Configuration, which is the authoritative page for standing a deployment up.

These names are RESERVED

Every variable in this reference belongs to the platform, and none of them can be the KEY a capability credential is looked up by. A tool server (MCP) or a generative binary integration declares the credential it needs by name, and the default resolver reads that name off this same environment before the value is injected into an agent process: a declaration of ENCRYPTION_KEY would hand a prompt-injectable agent the key every stored credential is sealed with. Such a declaration is refused at boot and again at dispatch. Look the credential up under a name of the integration's own (ACME_IMAGE_API_KEY) and set it beside these.

The rule is enforced by isReservedPlatformEnvKey (backend/packages/contracts/src/reserved-env-keys.ts), which reserves the platform's prefix families (AUTH_, GITHUB_, LOCAL_, …) plus the remaining exact names, case-insensitively, because process.env lookup is case-insensitive on Windows. scripts/check-reserved-env-keys.mjs fails CI when a variable documented below is not covered, so adding a row here is also how the reserved set stays current.

The model-provider keys are reserved too. That looks like over-reach and is not: OPENAI_API_KEY is billable and exfiltratable, and an integration that wants to call OpenAI on the deployment's account should say so in its own variable rather than silently inherit the one the model router spends.

A credential's OTHER name is not reserved

The floor above binds the LOOKUP name, because that is the one that can read this environment. It does not bind the variable a resolved value is INJECTED under in the agent's or the MCP server's process, which reads nothing at all. A declaration keeps them apart with envName:

secretKeys: [{ key: 'ACME_GITHUB_TOKEN', envName: 'GITHUB_PERSONAL_ACCESS_TOKEN' }]

That escape is why the prefix families can be as broad as they are. The GitHub MCP server's client reads GITHUB_PERSONAL_ACCESS_TOKEN, the Slack one reads SLACK_BOT_TOKEN, and an AWS one reads AWS_ACCESS_KEY_ID: the platform reads none of those, but each falls inside a family it does own, and no deployment can rename what a vendor's own SDK looks for. Injection names have their own, narrower rule instead (isToolchainEnvName): not PATH, NODE_OPTIONS, npm_config_* or the other names that would reconfigure the process rather than authenticate a call.

Name a capability credential under a prefix of your own

The lookup name is yours to pick, so pick a family and stay in it. The convention this repo's own registrations follow is MCP_… for a tool server's credentials and GEN_… for a generative binary integration's, or a house prefix (ACME_…) where one deployment owns both. Two reasons, and the second is the one that bites:

• Every family the platform uses is reserved (AUTH_, GITHUB_, LOCAL_, SLACK_, the model-provider keys, …), so a name that reads naturally is quite often refused. MCP_SLACK_TOKEN is not, and envName puts the value into the variable the vendor's own client insists on.
• allowKeys is set PER DEPLOYMENT, not per capability, and it gates every subject the resolver serves. An allow-list holding only MCP_… silently resolves nothing for a registered image or music generator, and the failure surfaces as the agent reporting that integration unavailable with nothing pointing back here. List a prefix per family, or the exact keys your registrations declare.

Whether a name resolves at all is answerable without starting a run: Infrastructure → Capability credentials lists every key the deployment's capabilities declare, and the tool-server rows above it carry a Test button that resolves the credential through the real chain and speaks MCP to a remote server. See custom-agents.md.

The environment is the FALLBACK, not the primary home

Capability credentials are resolved from the per-workspace capability-credential store first, falling back to this environment per key, so a multi-tenant deployment gives each workspace its own vendor account instead of sharing one variable. See ADR 0041. Setting a variable still works and is the right mechanism for a single-tenant or local install.

Deployment modes

The same @cat-factory/server app ships to several targets. "Mode" is which facade boots plus a few switches:

In the tables below the Modes column uses: CF (Cloudflare), Node, Local, MS (mothership-specific). A variable marked Node is also read by Local and by a mothership-mode laptop, because Local reuses the Node config loader; the tables call out Local/MS only when a variable is exclusive to those modes.

Spend budgets

Budgets are tiered: a per-workspace monthly limit (configured in the UI), a per-account limit, and a per-user limit. The two variables below are operator hard ceilings on the account and user tiers. When set, a UI user cannot configure a value above the cap (it is also enforced server-side), the cap is shown on the budget configuration screen, and it acts as the effective tier limit when nothing is configured. How budgets behave for a user is on the website: Budgets. Amounts are in the base pricing currency (EUR by default).

Notes: these are read by the Node and Cloudflare config loaders, so they apply in the Node, Cloudflare, and mothership-hosted deployments. A single-user local deployment reads them too (Local reuses the Node loader) but they are rarely meaningful there. The per-workspace budget itself is not an env variable: it is configured per workspace in the UI (Workspace settings -> Budget) and defaults to about 100 EUR/month.

Core service & networking

Realtime (Node horizontal scaling)

Authentication

VCS integration (GitHub / GitLab)

Model providers

Web search

Execution tuning

Storage & retention

Integrations & observability

The *_ALLOW_URL_HOSTS variables below are all read by one SSRF guard, so their entry format is shared: a comma-separated list whose entries match the URL host case-insensitively, either exactly (envs.corp, 10.1.2.3) or as a dot suffix when the entry begins with . (.internal matches internal and a.b.internal). There is no glob syntax, so an entry like *.internal is not a wildcard and matches nothing. Each integration resolves its own list: a host allowed to one is not thereby allowed to another.

Local mode

Mothership mode

Next: Configuration for what to set first, or Upgrades & Data Retention for the retention windows in context.