Environment variables
Every environment variable the engine reads, what it changes, and where to set it.
On your computer, openfabriq needs no environment variable: Claude Code and gh use their own logins, and openfabriq connect and openfabriq secret set save tokens and secret values in the engine's data folder.
Use variables to move that folder, to pass tokens or secret values without writing them to disk (on a server or in a container), and to configure the Docker image.
Where to set them
Set them for the process that runs the engine, and for every openfabriq command on the same machine:
| Where the engine runs | Where to set them |
|---|---|
| Your computer | Your shell profile, for example export OPENFABRIQ_HOME=/data/openfabriq in ~/.zshrc |
| A server, with systemd | Environment= or an EnvironmentFile= in the service |
| Docker | The .env file next to docker-compose.yml, or environment in that file. See Docker |
The data folder
| Variable | Effect | Values | Default |
|---|---|---|---|
OPENFABRIQ_HOME | The folder where the engine keeps all its data | a folder path: /data/openfabriq | ~/.openfabriq |
It holds everything the engine knows:
| Path in the folder | Contents |
|---|---|
projects/<owner>/<repo>/factory/ | The applied factory: the copy made by openfabriq apply, the one that runs |
projects/<owner>/<repo>/ | The engine's clone of the repository, the queue, the runs and their transcripts, and the chat history |
secrets.json | The tokens saved by openfabriq connect, and the GitHub App's key (mode 0600) |
secrets/<owner>/<repo>.env | The secret values saved by openfabriq secret set |
plan, apply, start, status, run, connect and secret set must all see the same OPENFABRIQ_HOME: a command run without it reads and writes ~/.openfabriq instead.
To make the engine forget a project, stop start and delete projects/<owner>/<repo>/. Its secret values stay in secrets/ until you delete them.
Service tokens
These replace the tokens openfabriq connect saves in secrets.json; when both exist, the variable wins.
| Variable | Service | Values | Replaces |
|---|---|---|---|
OPENFABRIQ_SLACK_BOT_TOKEN | Slack, bot token | xoxb-… | openfabriq connect slack |
OPENFABRIQ_SENTRY_TOKEN | Sentry, auth token | sntrys_… | openfabriq connect sentry |
GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY replace the GitHub App that openfabriq connect github saves: with either, the engine works as that app instead of gh's own login, wherever it runs. See A GitHub App instead of a token.
Linear needs no variable: its tokens stay in the relay, which refreshes them. The relay also needs its own copy of the Sentry token, given by openfabriq connect sentry.
Agents never receive them: their environment drops every OPENFABRIQ_*, GITHUB_*, SLACK_*, LINEAR_* and SENTRY_* variable. Restart openfabriq start after changing one.
Values of the factory's secrets
Each name a factory lists under secrets in factory.yaml can also be an environment variable of the engine, which wins over the value saved by openfabriq secret set:
export TEST_DATABASE_URL='postgres://test:test@localhost/app_test'
openfabriq startThese values go to setup, commands and checks, never to the agent. Names the engine keeps for itself (GH_*, GITHUB_*, ANTHROPIC_*, GIT_*, OPENFABRIQ_*…) are refused. See Environment variables and secrets.
Every factory on the machine can name any variable of the engine's environment in its secrets. Keep that environment free of production keys, and give each project its values with openfabriq secret set.
Claude and the studio, on any machine
| Variable | Effect | Values |
|---|---|---|
ANTHROPIC_API_KEY | Runs and the chat use this Anthropic API key, billed per token, instead of the Claude Code login. openfabriq start says which one it uses. The agents never see it | sk-ant-api03-… |
OPENFABRIQ_STUDIO_PASSWORD | The password of the studio's sign-in form, described under the Docker image below; openfabriq start reads it wherever it runs | 16 characters or more: the output of openssl rand -base64 24 |
OPENFABRIQ_STUDIO_URL | With the password or GitHub: the studio's https address, which it then accepts; openfabriq start reads it wherever it runs | an https:// address: https://factory.example.com |
GITHUB_APP_CLIENT_ID, GITHUB_APP_CLIENT_SECRET | With the GitHub App and OPENFABRIQ_STUDIO_URL: who can write to a repository of the factory signs in to the studio with GitHub, described under the Docker image below | the app's client id, Iv23…, and a client secret |
OPENFABRIQ_MAX_RUNS | How many runs openfabriq start runs at once, all projects together, 4 when unset; the others wait their turn. A run with a browser takes about 1 to 1.5 GB of memory | a number from 1 to 32: 2 |
OPENFABRIQ_INTERVAL | How often openfabriq start reads GitHub, in seconds, 60 when unset; --interval wins. Each read costs about 3 calls per repository, from GitHub's hourly allowance | 10 or more: 15 |
NO_COLOR | The CLI prints plain text, without colors | any non-empty value: 1 |
TERM | With the value dumb, the CLI prints plain text too | dumb |
The Docker image
Nobody logs in inside the container, so the Docker image reads its configuration from variables only:
| Variable | What it is | Values | Where to get it |
|---|---|---|---|
ANTHROPIC_API_KEY | The Claude credential of every run, billed per token | sk-ant-api03-… | Claude Console, API keys |
CLAUDE_CODE_OAUTH_TOKEN | Instead of the key: the Claude subscription of every run | sk-ant-oat01-… | claude setup-token, on any machine with Claude Code |
GITHUB_APP_ID | The id of your team's GitHub App, which the engine works as on GitHub | a number: 1234567 | openfabriq connect github: see The GitHub App |
GITHUB_APP_PRIVATE_KEY | With GITHUB_APP_ID: the app's private key, on one line | base64: LS0tLS1CRUdJTi…, or the PEM with \n for its line breaks | Printed by openfabriq connect github |
GH_TOKEN | Instead of the app: the GitHub account the engine reads and writes with | ghp_…, a classic token | GitHub, see A token instead of the app |
GIT_USER_NAME | Optional with the app, whose name the commits carry otherwise; with a token, the name of the author of the factory's commits | any text: Acme factory | Your choice: a bot name makes it clear |
GIT_USER_EMAIL | Optional with the app, whose address the commits carry otherwise; with a token, the email of the author of the factory's commits | an email address: factory@acme.dev | Your choice |
OPENFABRIQ_REPOSITORIES | The GitHub repositories whose factory the engine runs | owner/name, comma-separated: acme/web-app,acme/api | Each must have an openfabriq/ folder on its default branch, and the app, or GH_TOKEN, must have access to it |
OPENFABRIQ_STUDIO_PASSWORD | Optional: the password of the studio's sign-in form | 16 characters or more: the output of openssl rand -base64 24 | Your choice |
OPENFABRIQ_STUDIO_URL | Optional, with the password or GitHub: the studio's https address, which it then accepts | an https:// address: https://factory.example.com | A domain your proxy sends to the engine service, port 4311: see Open the studio |
GITHUB_APP_CLIENT_ID | Optional, with the app and OPENFABRIQ_STUDIO_URL: sign-in with GitHub to the studio | Iv23… | The app's settings on GitHub: see Sign in with GitHub |
GITHUB_APP_CLIENT_SECRET | With GITHUB_APP_CLIENT_ID: the app's client secret | a long hexadecimal text | Generate a new client secret in the app's settings, or printed by openfabriq connect github --url |
OPENFABRIQ_APT_PACKAGES | Optional: Debian packages your factory's commands need, installed when the image is built | package names, separated by spaces: php-cli composer | What openfabriq doctor lists in the logs: see Programs your factory needs |
OPENFABRIQ_MAX_RUNS | Optional: how many runs go at once, all projects together; the others wait their turn | a number from 1 to 32: 4 by default. About 1 to 1.5 GB of memory each, with a browser: 2 under 4 GB, 6 to 8 on 16 GB | Your choice, by the server's memory (free -h) |
OPENFABRIQ_INTERVAL | Optional: how often the engine reads GitHub, in seconds | 60 by default, 10 or more. Each read costs about 3 calls per repository; a GitHub App allows 5,000 an hour, shared by the repositories it is installed on: 15 fits a few repositories | Your choice |
One of the two Claude variables is required, and OPENFABRIQ_REPOSITORIES, with either the app's two variables, or GH_TOKEN, GIT_USER_NAME and GIT_USER_EMAIL: the container says which one is missing and stops. A password shorter than 16 characters, an address without the password or GitHub, or one of the two GitHub client variables without the other, stops the engine too.
On the same server, the relay reads ENGINE_TOKEN and RELAY_DOMAIN too, with the relay profile: see Add the relay on the same server.
The studio from the sources
| Variable | Effect | Values | Default |
|---|---|---|---|
PORT | The port of pnpm --filter @openfabriq/studio serve, the studio without the engine | a port number: 4320; 0 for any free port | 4310 |