Introduction
Relevant source files
The following files were used as context for generating this wiki page:
Opificia AI is an open-source software factory designed to automate the lifecycle of software changes using AI agents. These agents pick up tickets from a tracker, write code changes in a sandbox environment, run the associated test suite, and open pull requests for human review. The project prioritizes sovereignty, allowing operators to run the system on their own infrastructure using their choice of models, including open-weight models, without requiring vendor-hosted services.
The platform is currently in an early development stage, moving from foundational setup (Phase 0) to a first working loop (Phase 1). The architecture emphasizes human control, where no changes are merged or deployed by default without explicit person-in-the-loop approval. Documentation for contributing to this system can be found in CONTRIBUTING.md.
Sources: README.md:3-10, website/index.html:43-50, publiccode.yml:25-35, SOVEREIGNTY.md:65-68
Core Project Goals and Sovereignty
The project is built on eight central sovereignty commitments that ensure operators maintain control over their data, infrastructure, and legal jurisdiction.
Sovereignty Commitments
| Commitment | Description | Test Condition |
|---|---|---|
| Runs anywhere | Fully self-hostable and air-gap capable. | Every feature works without outbound internet access. |
| No phone-home | Telemetry is off by default and only sent to configured endpoints. | Default installation connects only to operator-configured endpoints. |
| Model-agnostic | Supports any model via open interfaces; open-weight models are first-class. | Reference tests pass with a local open-weight model. |
| Open standards | Uses open protocols and formats; proprietary integrations are optional plugins. | External interfaces follow published specifications. |
| Data Ownership | Prompts, code, and logs stay where configured; no central model training. | Nothing is sent outside operator-configured destinations. |
| Human Decision | Approval is required for merges and deployments by default. | No agent can merge/deploy without recorded human approval. |
| Supply Chain | Transparent builds with SBOMs and reproducible artefacts. | Independent rebuild produces the same artefacts. |
| European Infrastructure | Reference deployments use providers headquartered in Europe. | Providers and their countries are listed publicly. |
Sources: SOVEREIGNTY.md:21-77, website/index.html:78-125
Operational Workflow: The Working Loop
The system operates in a cyclical flow where an agent transforms a descriptive ticket into a verified pull request.
The diagram illustrates the intended workflow where a person reviews every automated action before final integration.
Sources: website/index.html:56-74, README.md:12-16
Technical Architecture
The Opificia stack is based on a TypeScript pnpm workspace environment. The target architecture utilizes a NestJS server and a React-based web interface.
Project Stack and Components
- Runtime: Node.js 24.
- Backend: NestJS, PostgreSQL with Prisma, Valkey.
- Frontend: Vite, React, Tailwind CSS.
- Agents: Claude Code is used as the initial harness, but the system is model-agnostic.
- Sandboxing: Code execution and changes happen within isolated sandbox environments to ensure security and network control.
Sources: AGENTS.md:9-15, AGENTS.md:46-48, CHANGELOG.md:20-25
Workspace Structure
| Package/Folder | Purpose | License |
|---|---|---|
apps/server | The core backend logic and run lifecycle. | AGPL-3.0-only |
apps/web | The administrative and reviewer web interface. | AGPL-3.0-only |
sdk/contracts | Common types and communication protocols. | Apache-2.0 |
plugins/ | Harnesses and external integrations (e.g., Claude). | Apache-2.0 |
docs/ | Architecture Decision Records (ADRs) and RFCs. | CC-BY-4.0 |
Sources: AGENTS.md:46-48, REUSE.toml:13-50, CONTRIBUTING.md:196-205
Development Roadmap
The project progresses through four defined phases to reach a stable first release.
The roadmap moves from establishing legal and governance policies to creating a secure, production-ready release where Opificia is used to build Opificia.
Sources: ROADMAP.md:7-60, website/index.html:142-166
Summary
Opificia AI provides a framework for sovereign software automation. It enables organizations to leverage AI coding agents while maintaining strict control over their code, data, and infrastructure. By combining an open-source core with a human-in-the-loop review process and a commitment to open standards, Opificia aims to serve as a reference for European-led automated software development.
Sources: README.md:18-23, SOVEREIGNTY.md:10-18