OpenFactory
OpenFactory continues as BeeverForge. 0.7.0 is the last OpenFactory release: the name is
another company's trademark, so the project was renamed. BeeverForge 0.1.0 is OpenFactory 0.7.0
under the new name, at github.com/BeeverForge/beeverforge-oss
and on PyPI as beeverforge. New issues and pull requests go there; the open issues here are
being moved across where they still apply.
An autonomous software factory. It takes tickets from your board and returns reviewed pull
requests — planned, implemented, validated by your test suite, independently reviewed, and
merged under the policy you chose. Humans stop authorising every step and start evaluating
results; production stays behind a human gate, always.
It is not a coding agent — it orchestrates the ones you already use (Claude Code, Codex,
Kimi, OpenCode) behind one adapter contract. It is not a SaaS — it runs on your machines,
against your board, with your credentials, and no cloud account is required.
Why this one
- Policies authorise, humans evaluate. The manifest declares the merge policy, the quality
floor and the promotion chain; the factory refuses vacuous green — a project with no declared
test command is held, not "passed".
- The box is proven before money is spent.
box prove runs your own setup: and
validate: inside the real sandbox before any ticket is picked up. A misconfigured
environment is a named finding, not a burned agent pass.
- Every stall speaks. A blocked job parks with executable options for a human; a silent
forever-wait is treated as the platform's own defect class.
- Provider axes, not provider lock-in. Tracker, board, forge, CI observer, notifier, coding
agent and sandbox are independent adapters — GitHub Issues + Projects, Jira, Azure DevOps
(work items → Azure Repos PRs, end to end), chosen per project in a registry.
- An independent review, structurally. The reviewer can run on a different engine from the
executor, so "you did not write this code" is true by construction.
- Honest docs. What does not work is written down (
docs/STATUS.md)
before you decide anything.
Quickstart — one machine
The shortest path is your own repository and the coding agent you already pay for: one
credential, no Docker, no account anywhere. The factory branches from your repository, opens a
pull request in it, reviews the change and fast-forwards your base.
Prerequisites: git, Python 3.12+, and a coding agent on your PATH already signed in (claude,
codex, kimi or opencode).
git clone https://github.com/Open-Factory-Digital/openfactory-core.git && cd openfactory-core
python3 -m venv .venv && source .venv/bin/activate # 3.12+; see docs/ONBOARDING.md §0
pip install -e '.[runtime]' # the durable engine's worker runs on the extra
openfactory init # press Enter twice: your code and your tickets live HERE
openfactory project init myapp ~/code/myapp # a path registers as itself — no owner, no board
openfactory doctor myapp # on this door, green IS the prerequisite list
openfactory act card_create -p myapp -P title="Add a health endpoint" -P body="## Objective
Serve 200 at /health
## Acceptance criteria
- GET /health returns 200"
openfactory act card_move -p myapp -i 1 -P column=TO-DO
openfactory poll myapp # one card, all the way to Done
openfactory serve serves the same thing in a browser at http://localhost:8787 — the Board, the
job, the pull request. The whole door is docs/setup/one-machine.md,
including what happens to your working tree when a merge lands.
Quickstart — with Docker, on a hosted forge
The other door: the compose stack, a real forge and a real board, several people watching the same
panel. Two credentials are irreducible here — the coding agent's
(CLAUDE_CODE_OAUTH_TOKEN from claude setup-token, or ANTHROPIC_API_KEY) and a forge
credential (a PAT to try things out, a GitHub App for real use). Docker is asked for at this hour,
not before.
Docker. Only Docker. No Python on the host, no sudo, one line:
curl -fsSL https://openfactory.digital/install.sh | sh
| |
|---|
| read it first | curl -fsSL https://openfactory.digital/install.sh -o install.sh && less install.sh && sh install.sh |
| no script at all | the four commands below |
The worker mounts the host's Docker socket — that is how sandbox: container starts a box, and
it is root-equivalent on the host. It is the same trade docker compose up has always made here.
The installer sends nothing anywhere. There is no telemetry in this project.
Re-running the installer with --force is the upgrade path: it resolves the newest release, pulls
it, and restarts the stack. Every value in your .env.compose survives it, credentials included,
and only the pinned version moves. Your data lives in named volumes, which only --uninstall
removes.
A specific version, or a release candidate. --version <tag> installs that release instead of
the newest (… | sh -s -- --version v0.4.2). A release candidate (v0.5.0-rc.1), published
before a version so it can be tested, is installed only this way: the one line above, the
wheel on PyPI and every other "newest" keep giving the last final release. How to install, test
and leave a candidate: Installing a candidate.
Prefer to do it by hand? These are the same four steps, and nothing else:
REPO=https://github.com/Open-Factory-Digital/openfactory-core
VERSION=$(curl -fsSLI -o /dev/null -w '%{url_effective}' $REPO/releases/latest); VERSION=${VERSION##*/tag/}
curl -fsSL $REPO/releases/download/$VERSION/docker-compose.yml -o docker-compose.yml
curl -fsSL $REPO/releases/download/$VERSION/SHA256SUMS | sha256sum -c --ignore-missing
docker run --rm -it -v "$PWD:/out" -u "$(id -u):$(id -g)" \
ghcr.io/open-factory-digital/openfactory-cli:$VERSION init --out /out/.env.compose
echo "OPENFACTORY_VERSION=$VERSION" >> .env.compose
docker pull ghcr.io/open-factory-digital/openfactory-sandbox:$VERSION
docker compose --env-file .env.compose up -d
Three of those lines look optional and are not. The version is resolved once and written into
.env.compose, because docker-compose.yml defaults to main — right for a contributor working
on the branch, wrong for anybody running a factory. The box image is pulled by hand because
docker compose up does not fetch it: the worker launches it as a sibling container on your own
daemon. And the checksums are verified, which is why the files come from the release rather
than from the website — a static host can serve a file and cannot checksum one.
Then open http://localhost:8787 in a browser — the panel (8080 is the engine's own UI).
Two credentials are irreducible for a real ticket — the coding agent's
(CLAUDE_CODE_OAUTH_TOKEN from claude setup-token, or ANTHROPIC_API_KEY) and a forge
credential (a PAT to try things out, a GitHub App for real use). openfactory init asks for
neither and names both; only the agent's cannot be postponed past the first hour.
openfactory preflight says what is still missing on this machine, one line each with a remedy.
Register a project inside the worker (the compose stack has its own registry; a
laptop-registered project is invisible to it). One command registers it and creates the board
with the platform's columns:
docker compose --env-file .env.compose exec worker \
openfactory project init myapp https://github.com/<owner>/myapp.git # your org or username
docker compose --env-file .env.compose exec worker openfactory doctor myapp
(project add is the variant for a board you already have, or for none at all. On Azure
DevOps, register with your dev.azure.com clone URL — it carries the
organisation/project/repository, and Azure Boards ships with the project, so there is no board
to create: docs/setup/azure-devops.md.)
doctor runs nine checks always and up to four more when they apply, naming every missing
prerequisite with its remedy — including the
agent credential and the forge credential. From there, the guided first hour is
docs/ONBOARDING.md: the environment session that reads your repository
and proposes its own manifest, the box proof, a costed rehearsal on a synthetic ticket, and the
first real card.
Your first ticket
An ordinary issue, in English or Portuguese:
## Objective
Users can export their report as CSV.
## Acceptance criteria
- a `GET /reports/{id}/export` endpoint returns text/csv
- the export respects the report's current filters
Drag it to TO-DO. The factory sizes it, proves the box, plans, implements, runs your
gates, opens the PR, has it independently reviewed — and with merge_policy: human (the
recommended start) waits for your merge. The panel at :8787 shows every step live.
The shape
openfactory/
├── contracts/ Pydantic models — the framework↔project↔agent↔board interface
├── registry.py the set of projects one deployment drives (add one = data, not code)
├── policy/ the quality floor: stack presets + org defaults + conformance
├── adapters/ the provider axes — a project mixes them freely; the core ships GitHub,
│ │ Azure DevOps and Jira on every axis below that has a vendor, and an
│ │ add-on package adds a kind through the `openfactory.adapters` entry points
│ ├── tracker/ GitHub Issues, Jira, Azure DevOps work items
│ ├── board/ GitHub Projects, Jira status, Azure DevOps boards
│ ├── forge/ GitHub, Azure Repos — branches, PRs, merges, tags
│ ├── environment/ CI / deploy / health, read-only — GitHub Actions, Azure Pipelines
│ ├── agent/ CodingAgentAdapter — Claude Code, Codex, Kimi, OpenCode
│ ├── reviewer/ the independent review
│ ├── channel/ the panel — the reference surface; a chat channel is an add-on package (openfactory-slack)
│ └── sandbox/ container = real; worktree = local/test; a cloud box is an add-on package (openfactory-aws)
├── orchestrator/ the deterministic state machine (the spine)
├── runtime/ the durable engine (Temporal): poller, jobs, promotion tail
└── cli.py `openfactory` — project-first commands
The roles you can switch on
| role | what it is | where it lives |
|---|
| engineering loop | ticket → reviewed PR → merge | on by default; this README |
| post-merge | watch your deploy, walk your stages, gate production | opt-in per project — ONBOARDING §13 says what silence means |
| tech-lead | diagnoses parked jobs, proposes the fix, acts on your yes | the panel; a chat channel such as Slack is an add-on package (openfactory-slack), never a prerequisite |
| product owner | requirements as reviewed docs in a context repo; accept/queue/release | /product/<name> on the panel — docs/reference/product-role.md |
| release gate | production is approved by a named human with a password, always | docs/reference/product-role.md §3 |
Documentation
One path, three references. The map is docs/README.md; this is the short
form:
Status
Working, and honest about where. The whole loop — sizing → box proof → agent → your gates → PR
→ independent review → merge — has run end to end on four stacks (Python,
serverless TypeScript, .NET, multi-repo) against real GitHub, real Jira and real Azure DevOps.
The suite runs in both orders on every change and new guards are proven by mutation before they
count — the current size, the commit it was measured at, and everything that is NOT settled are
in docs/STATUS.md, which is the one place any of those numbers live.
Taking part
Issues and pull requests are welcome, and the bar is written down rather than implied:
CONTRIBUTING.md explains the house rules (a guard for every behaviour, a
mutation for every guard) and how to add a provider to an axis without touching the core.
There is no CLA — Apache-2.0 §5 already covers what you submit, and you keep the copyright
on what you write. Everyone taking part is held to the Code of Conduct.
License
Apache-2.0. The NOTICE file separates the free code from the defended
brand. Security reports: see SECURITY.md. Contributions: CONTRIBUTING.md.
