openfabriq
Deployment

Docker

One container on an always-on server runs the factory for the whole team. Teammates install nothing.

A team runs its factory with one engine, on an always-on server: a VPS (Hetzner, OVHcloud, DigitalOcean…) or a cloud instance (AWS EC2, Google Cloud, Azure). A small Linux instance is usually enough: the model runs at Anthropic, the server runs the agents' tools and your tests. Teammates install nothing: they label an issue, mention the factory in Slack or delegate a Linear issue.

How it works

You edit the factory
Your computer
  • openfabriq init, validate, plan
  • commit and push openfabriq/
git push
Your repository
GitHub
  • openfabriq/ reviewed and merged like code
cloned at each start
The engine, in Docker
The server
  • applies the default branch
  • openfabriq start, always on
  • tokens and logins stay here

The container holds Node, npm, pnpm, Python, git, gh, Claude Code, the Linux sandbox, agent-browser with Playwright's headless Chrome, and openfabriq. It is configured by environment variables only. Run it with docker compose, or on a platform that deploys a compose file, such as Coolify.

At each start, it clones the default branch of each repository, runs openfabriq apply --yes --project <owner/repo> (which refuses a factory.yaml naming another repository), then openfabriq start.

Before you start

You needWhy
A Linux server with Docker and Docker Composeit runs the container
An Anthropic API key, or a Claude subscription for a server only you useevery run of the team uses it: see which one
Your team's GitHub Apppull requests and comments appear under its name
An openfabriq/ folder on each repository's default branchthe container applies what is merged

Get the two credentials

Claude: API key or subscription

Pick one:

  • An API key (ANTHROPIC_API_KEY), for a team: create it in the Claude Console, ideally in a workspace for the factory alone, with a monthly spend limit.
  • A subscription token (CLAUDE_CODE_OAUTH_TOKEN), only on a server you alone use: run claude setup-token on your computer.
API keySubscription token
Meant fora team, a shared serverone person's own work, on a server only they use
Billingper token, on your Anthropic accountyour plan's quota, shared with your own sessions
Limitsyour Console limits and spend capthe plan's 5-hour and weekly windows

If both are set, the key wins, as in Claude Code itself; openfabriq start says which one the runs use. With a key, usd_per_run and usd_per_day in limits become real spend, estimated at Anthropic's list prices; the Console's spend limit on the factory's workspace is the hard cap.

The GitHub App

The engine works on GitHub as an app your team owns: it clones the repositories, watches issues and pull requests, pushes branches, opens pull requests and comments, under the app's name followed by [bot]. Unlike a token, it needs no second account, invitation, renewal or single sign-on authorization; it reaches only the repositories it is installed on; and it reads GitHub Actions' results, so a factory with a CI works. The engine gets a token per repository, valid for an hour, and renews it itself.

Create the app

On your computer, where a browser opens, with openfabriq installed:

openfabriq connect github --org acme

--org makes the organization the owner, which takes one of its owners or app managers; without it, the app is yours. The app is private, so every repository of OPENFABRIQ_REPOSITORIES must belong to its owner. Add --workflows if the agents change files in .github/workflows/.

GitHub's creation page opens, filled in. Check the name (GitHub wants one nobody has taken), then select Create GitHub App.

Install it on the repositories

On the install page that follows, choose Only select repositories, the ones of OPENFABRIQ_REPOSITORIES, then Install: All repositories would let the engine reach every repository of the owner. To add one later, open https://github.com/apps/<the app's name>/installations/new.

Copy its two variables

The command saves the app on your computer, so openfabriq start there works as the app too, and prints GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY for the server's .env. The key is the app's private key in base64 on one line (a PEM with \n for its line breaks works too). Keep it as secret as a password: whoever holds it acts as the app on every repository it is installed on.

The app has no webhook: the engine asks GitHub every minute. With its two variables, the engine uses the app even if GH_TOKEN is set. Commits carry the app's name and GitHub address, so GitHub links them to the app; GIT_USER_NAME and GIT_USER_EMAIL override them. At each start, the logs say whether the app is installed on each repository: ✓ GitHub: the engine works as the app acme-factory[bot], installed on acme/web-app.

Install

Once you have the credentials, paste this prompt in Claude Code, on your computer. It does the By hand steps on the server over SSH, and asks you to write the credentials into .env yourself.

Let Claude Code install it on your server. Paste one prompt into Claude Code on your computer: it sets the server up over SSH and starts the engine. It never asks for your tokens: you type them into .env yourself.

Read the prompt
Install the openfabriq engine on a server. openfabriq runs AI agents described in an openfabriq/ folder of GitHub repositories; the engine is one Docker container: https://github.com/openfabriq/openfabriq

Go step by step. Never install system packages, use sudo, log in, accept an SSH host key or change my settings for me: when something is missing, tell me the command that fixes it and stop. Never ask me for a token or a password, never print them, and never read the .env file: I write the secrets in it myself.

1. Ask me, in one message: the server's SSH address (user@host), or "this machine" if you already run on the server; which GitHub repositories the engine runs (owner/name, comma-separated; each needs an openfabriq/ folder on its default branch); and whether the factory works on GitHub as my team's GitHub App (the default) or, if I cannot create one, with a token; only with a token, what name and email the factory's commits carry (a bot name makes it clear).

2. Every command below that runs on the server goes through `ssh <address> '…'`, or runs directly when this machine is the server. First check that `ssh -o BatchMode=yes <address> true` works. If it does not, tell me to connect once by hand (it asks me to accept the host key) and stop.

3. On the server, check that it runs Linux, and that Docker, Docker Compose and git are installed (`docker --version`, `docker compose version`, `git --version`) and that my user can run docker without sudo. If not, tell me what to do and stop.

4. Get the sources on the server, in ~/openfabriq unless I say otherwise:
   git clone https://github.com/openfabriq/openfabriq.git <folder>

5. Write <folder>/.env on the server with my answers (OPENFABRIQ_REPOSITORIES, and with a token GIT_USER_NAME and GIT_USER_EMAIL) and these lines left empty, each with a comment on where to get the value:
   ANTHROPIC_API_KEY=    # a Claude Console API key (or CLAUDE_CODE_OAUTH_TOKEN, from `claude setup-token`, for a server only I use)
   With the app:
   GITHUB_APP_ID=           # printed by `openfabriq connect github` (add --org <organization> for an organization's repositories), which I run myself on my computer: it opens GitHub in my browser to create and install the app
   GITHUB_APP_PRIVATE_KEY=  # printed by the same command
   With a token instead:
   GH_TOKEN=             # a classic token of the factory's GitHub account, with the repo scope
   Then tell me to fill them in myself, in my own terminal: `ssh -t <address> nano <folder>/.env` (or the editor of my choice), and to say "done". Wait for me.

6. In <folder>, run `docker compose up -d`, then `docker compose ps` and `docker compose logs --tail 100 engine`. Report each line that starts with ✗ (it comes from `openfabriq doctor`, with its fix) and any "was not applied". Never run `docker compose down -v`: it deletes the engine's data.

7. Finish with what runs, what is left for me (the studio's password and domain, the relay for Slack and Linear: both are in the documentation's Docker page), and nothing else.

The queue, the runs, the connections and the secrets live in the engine-data volume: a restart loses nothing.

Then stop the engine on your laptop for these repositories: two engines on one repository each start a run for the same event, so you get two pull requests, and nothing prevents it yet.

Open the studio

The studio shows the runs and runs a chat that spends your Claude credential, so it is always locked. Its address also serves Claude Desktop, claude.ai and Claude Code, which read the factories, runs and numbers at https://factory.example.com/mcp: see Connect Claude.

With a password and a domain

The simplest way in. Add to .env:

.env
OPENFABRIQ_STUDIO_PASSWORD=…   # 16 characters or more: openssl rand -base64 24
OPENFABRIQ_STUDIO_URL=https://factory.example.com

Then send that domain to the engine service, port 4311, with an https proxy. On Coolify: in the resource's settings, give the engine service the domain with the port, https://factory.example.com:4311, put the two variables in Environment Variables, and deploy; Coolify's proxy gets the certificate.

Open https://factory.example.com: the studio asks for the password, then stays open in that browser until the engine restarts. openfabriq start prints where to sign in, never the password:

studio: sign in at https://factory.example.com with OPENFABRIQ_STUDIO_PASSWORD

The studio answers only on 127.0.0.1:4310, localhost:4310 and that address; any other domain gets 403. After 10 wrong passwords in 10 minutes from one address, that address waits out the 10 minutes; after 100 from anywhere, every sign-in does. The address is the last one of X-Forwarded-For, which your proxy adds: behind a second proxy, such as Cloudflare's, it is that proxy's.

Keep the domain private too. The password locks the studio, but its sign-in page is on the Internet if the domain is. Point the domain at the server's Tailscale (or VPN) address only, or allow only your team's IP addresses in the proxy. Claude Desktop also needs Anthropic's addresses.

Sign in with GitHub

Beyond two or three people, or when the domain is open to Claude's connector, let each person sign in with their own GitHub account instead of sharing the password. It goes through the engine's GitHub App: whoever can write to one of the factory's repositories gets in, and someone removed from them is out within the hour. No database, nothing more to run.

  1. In the app's settings (Settings › Developer settings › GitHub Apps, your app; the organization's settings for an app it owns), under Identifying and authorizing users, add the Redirect URI (formerly Callback URL) https://factory.example.com/auth/github/callback, with its path and without wildcard matching, then Save changes at the bottom. Without it, GitHub answers "This GitHub App must be configured with a callback URL". Then Generate a new client secret, and copy the Client ID and the secret. For a new app, openfabriq connect github --url https://factory.example.com does both and prints the two variables.

  2. Add them to .env, beside OPENFABRIQ_STUDIO_URL:

    .env
    GITHUB_APP_CLIENT_ID=Iv23…
    GITHUB_APP_CLIENT_SECRET=…
  3. Deploy. The studio shows Sign in with GitHub. The first time, GitHub asks the person to authorize the app, which gives the studio their login and nothing else.

The password can stay, for someone without write access. A session lasts a week at most; the bottom of the studio's menu shows who is signed in and signs out. To sign everyone out, generate a new client secret and replace the variable.

Accounts for people not on GitHub, with an invitation list, are planned with Better Auth. Need them? Open an issue with your use case.

Without a domain, or with a second lock

Connect Slack, Linear, Sentry

These services go through the relay. Connect it first: on this server, or, for a relay hosted elsewhere, with openfabriq connect relay --url, which asks for the relay's ENGINE_TOKEN (relay.token in ~/.openfabriq/secrets.json of the machine that deployed it with connect relay). The openfabriq connect commands run in the container, and their tokens stay in its volume:

docker compose exec engine openfabriq connect slack
docker compose restart engine

Add the relay on the same server

Add RELAY_DOMAIN and ENGINE_TOKEN to .env, then:

docker compose --profile relay up -d
docker compose exec engine openfabriq connect relay --url https://<RELAY_DOMAIN>

Configuration

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.

A factory's secrets are kept in the container's volume once it runs, or passed as variables under environment in docker-compose.yml; a variable wins over the kept value.

docker compose exec engine openfabriq secret set DATABASE_URL --project acme/web-app

Programs your factory needs

At each start, after applying a repository, the container runs openfabriq doctor in it: the logs list every program that setup or a command starts and the image lacks.

docker compose logs engine | grep "is not installed"

To add one, name its Debian packages in .env, then rebuild the image:

OPENFABRIQ_APT_PACKAGES="php-cli composer"
docker compose up -d --build

The image's headless Chrome comes with its libraries and fonts, and AGENT_BROWSER_EXECUTABLE_PATH tells agent-browser where it is: the templates' browser-evidence skill uses it to screenshot the pages its agents build and show them in the pull request.

Keep it up to date

What changedDo
a change to openfabriq/ was mergeddocker compose restart engine: the container applies the default branch again
a new version of openfabriqgit pull && docker compose up -d --build in openfabriq's folder
a repository was removed from OPENFABRIQ_REPOSITORIESit stays applied in the volume, and the engine keeps running it

Security

No credential reaches an agent. The GitHub App's key or the GitHub token, the app's per-repository tokens and the studio's password stay with the engine: no agent, command or MCP server receives them, and a factory cannot name the password in its secrets. The Claude credential stays with Claude Code. See What reaches the agent.

One limit of the Agent SDK: an MCP server's token or secrets sit in the arguments of the claude process. In Docker, only this container's processes see them, not the sandboxed agents and commands.

What the sandbox costs the container

The sandbox of agents and commands, bubblewrap, creates Linux namespaces and mounts its own /proc. Docker forbids both by default, so docker-compose.yml turns off three protections:

Turned offWhat it means
The seccomp filterEvery system call is open, including user namespaces, the kernel's largest surface for a privilege escalation
The AppArmor profileDocker's default profile no longer applies to the container
The masked system paths/proc/kcore, /proc/keys, /sys/firmware… become visible

It does not use --privileged: the container has no capabilities at all, and nothing in it can gain privileges.

A kernel flaw reached through those system calls would still escape the container, as it would escape a user's session on a Linux machine. Run it on a server dedicated to the factory.

Ubuntu 23.10 and later restrict user namespaces on the host (kernel.apparmor_restrict_unprivileged_userns); this has not been tried yet. If runs with shell or checks fail with a bwrap error, the run says so: nothing runs outside the sandbox.

On this page