openfabriq
Reference

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 runsWhere to set them
Your computerYour shell profile, for example export OPENFABRIQ_HOME=/data/openfabriq in ~/.zshrc
A server, with systemdEnvironment= or an EnvironmentFile= in the service
DockerThe .env file next to docker-compose.yml, or environment in that file. See Docker

The data folder

VariableEffectValuesDefault
OPENFABRIQ_HOMEThe folder where the engine keeps all its dataa folder path: /data/openfabriq~/.openfabriq

It holds everything the engine knows:

Path in the folderContents
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.jsonThe tokens saved by openfabriq connect, and the GitHub App's key (mode 0600)
secrets/<owner>/<repo>.envThe 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.

VariableServiceValuesReplaces
OPENFABRIQ_SLACK_BOT_TOKENSlack, bot tokenxoxb-…openfabriq connect slack
OPENFABRIQ_SENTRY_TOKENSentry, auth tokensntrys_…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 start

These 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

VariableEffectValues
ANTHROPIC_API_KEYRuns 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 itsk-ant-api03-…
OPENFABRIQ_STUDIO_PASSWORDThe password of the studio's sign-in form, described under the Docker image below; openfabriq start reads it wherever it runs16 characters or more: the output of openssl rand -base64 24
OPENFABRIQ_STUDIO_URLWith the password or GitHub: the studio's https address, which it then accepts; openfabriq start reads it wherever it runsan https:// address: https://factory.example.com
GITHUB_APP_CLIENT_ID, GITHUB_APP_CLIENT_SECRETWith 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 belowthe app's client id, Iv23…, and a client secret
OPENFABRIQ_MAX_RUNSHow 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 memorya number from 1 to 32: 2
OPENFABRIQ_INTERVALHow often openfabriq start reads GitHub, in seconds, 60 when unset; --interval wins. Each read costs about 3 calls per repository, from GitHub's hourly allowance10 or more: 15
NO_COLORThe CLI prints plain text, without colorsany non-empty value: 1
TERMWith the value dumb, the CLI prints plain text toodumb

The Docker image

Nobody logs in inside the container, so the Docker image reads its configuration from variables only:

VariableWhat it isValuesWhere to get it
ANTHROPIC_API_KEYThe Claude credential of every run, billed per tokensk-ant-api03-…Claude Console, API keys
CLAUDE_CODE_OAUTH_TOKENInstead of the key: the Claude subscription of every runsk-ant-oat01-…claude setup-token, on any machine with Claude Code
GITHUB_APP_IDThe id of your team's GitHub App, which the engine works as on GitHuba number: 1234567openfabriq connect github: see The GitHub App
GITHUB_APP_PRIVATE_KEYWith GITHUB_APP_ID: the app's private key, on one linebase64: LS0tLS1CRUdJTi…, or the PEM with \n for its line breaksPrinted by openfabriq connect github
GH_TOKENInstead of the app: the GitHub account the engine reads and writes withghp_…, a classic tokenGitHub, see A token instead of the app
GIT_USER_NAMEOptional with the app, whose name the commits carry otherwise; with a token, the name of the author of the factory's commitsany text: Acme factoryYour choice: a bot name makes it clear
GIT_USER_EMAILOptional with the app, whose address the commits carry otherwise; with a token, the email of the author of the factory's commitsan email address: factory@acme.devYour choice
OPENFABRIQ_REPOSITORIESThe GitHub repositories whose factory the engine runsowner/name, comma-separated: acme/web-app,acme/apiEach must have an openfabriq/ folder on its default branch, and the app, or GH_TOKEN, must have access to it
OPENFABRIQ_STUDIO_PASSWORDOptional: the password of the studio's sign-in form16 characters or more: the output of openssl rand -base64 24Your choice
OPENFABRIQ_STUDIO_URLOptional, with the password or GitHub: the studio's https address, which it then acceptsan https:// address: https://factory.example.comA domain your proxy sends to the engine service, port 4311: see Open the studio
GITHUB_APP_CLIENT_IDOptional, with the app and OPENFABRIQ_STUDIO_URL: sign-in with GitHub to the studioIv23…The app's settings on GitHub: see Sign in with GitHub
GITHUB_APP_CLIENT_SECRETWith GITHUB_APP_CLIENT_ID: the app's client secreta long hexadecimal textGenerate a new client secret in the app's settings, or printed by openfabriq connect github --url
OPENFABRIQ_APT_PACKAGESOptional: Debian packages your factory's commands need, installed when the image is builtpackage names, separated by spaces: php-cli composerWhat openfabriq doctor lists in the logs: see Programs your factory needs
OPENFABRIQ_MAX_RUNSOptional: how many runs go at once, all projects together; the others wait their turna 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 GBYour choice, by the server's memory (free -h)
OPENFABRIQ_INTERVALOptional: how often the engine reads GitHub, in seconds60 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 repositoriesYour 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

VariableEffectValuesDefault
PORTThe port of pnpm --filter @openfabriq/studio serve, the studio without the enginea port number: 4320; 0 for any free port4310

On this page