The platform that builds itself. An open-source, AI-native operating platform for small businesses and product teams under human governance. A DPF install starts from a market archetype, gives the business a customer portal and internal workspace in its own vocabulary, and puts purposed AI coworkers at the center of daily work. Single-org install on your hardware; opt-in cross-install contribution through the Hive Mind.
For potential users and customers, start at opendigitalproductfactory.com — the canonical product tour with capability inventory, archetypes, coworker workforce, maturity surface, and standards conformance.
This README is for people working with the project source — contributors, integrators, and anyone running the install scripts or modifying the codebase.
DPF's user story is now archetype-led rather than module-led:
- Pick the business type first: HVAC, clinic, retail, nonprofit, HOA, professional services, software platform, and other small-business categories.
- The selected archetype shapes the customer portal, internal workspace vocabulary, worker home, marketing posture, and feature-contribution applicability.
- AI coworkers are the primary interaction surface. They are purposed by role and route, but every side effect still goes through role checks, agent grants, approval gates, and audit logs.
- WWMD is the trust-building autonomy path: coworkers can consult the founder-kernel wiki and principle vectors for ambiguous decisions, then return a confidence-scored recommendation, arbitration, escalation, or deferral with sources and an audit ledger.
- Voice is an optional coworker modality: speech-to-text for input, text-to-speech for narrated decision/profile output where consent and provider setup allow it.
- Build Studio is the governed self-development surface, but it is still being hardened. Use it honestly: ready for guided platform work and evidence capture, not a claim that every complex source change is fully autonomous today.
User-facing narrative lives in Market Archetypes And Coworkers, with proof personas under docs/personas/.
This repository hosts a draft standards family for trustworthy AI-agent operation and identity. DPF is the first implementation and conformance case.
- Trusted AI Kernel (TAK) — runtime governance, authority mediation, HITL, delegation, audit, provider backpressure, queueing, failover
- Global AI Agent Identification and Governance (GAID) — identity, issuer / accreditation, badging, assurance, authorization classes, chain-of-custody
- Trusted AI Agent Governance White Paper — market, policy, and implementation case
- DPF Standards Conformance Assessment — how the platform maps to the proposed controls today
Publication outputs are generated from the Markdown sources of truth:
pnpm docs:tak
node docs/architecture/generate-gaid-docx.mjs
node docs/architecture/generate-agent-standards-white-paper-docx.mjsThese commands assume a fresh machine with no DPF repo yet. If you've already cloned the repo (contributors), skip to Step 2 from inside the repo.
The Windows installer is a self-contained PowerShell script that clones the repo for you.
# Step 1 — download the installer (run from any directory)
iwr -UseBasicParsing https://raw.githubusercontent.com/OpenDigitalProductFactory/opendigitalproductfactory/main/install-dpf.ps1 -OutFile install-dpf.ps1
# Step 2 - run it (prompts for install directory; may suggest a non-C drive)
powershell -ExecutionPolicy Bypass -File install-dpf.ps1macOS Apple Silicon — GA · full guide
Validated end-to-end on real Apple Silicon hardware (M-series, macOS 14+). The Unix installer sources helper libraries from inside the repo, so you must clone first.
# Step 1 — clone the repo and enter it
git clone https://github.com/OpenDigitalProductFactory/opendigitalproductfactory.git
cd opendigitalproductfactory
# Step 2 — run the installer
bash install-dpf.shVoice works on macOS. Speech-to-text runs out of the box (bundled speaches / faster-whisper service — no GPU needed). For spoken output, Apple Silicon runs a native-host TTS sidecar (Docker can't reach the Neural Engine); enable it once with bash scripts/tts/setup-chatterbox-tts-macos.sh. See Voice (STT + TTS).
Linux (native Docker) — Early access · full guide
git clone https://github.com/OpenDigitalProductFactory/opendigitalproductfactory.git
cd opendigitalproductfactory
bash install-dpf.shCloud Single VM (AWS / GCP / Azure) — Early access · pilots wanted · full guide
Inside the VM:
git clone https://github.com/OpenDigitalProductFactory/opendigitalproductfactory.git
cd opendigitalproductfactory
bash install-dpf.sh --headless --releaseTerraform modules for the cloud-VM path live under infra/terraform/single-vm/{aws,gcp,azure}/.
The installer asks one question — Ready to go (pre-built images; Build Studio is the governed development surface) or Customizable (full source clone; Build Studio and a local IDE share the same workspace). Both modes include the full platform; the difference is whether direct IDE access is part of the supported workflow. For serious source changes while Build Studio continues hardening, use Customizable mode. Login credentials are saved to .env / .admin-credentials at the end of installation.
AI toolchain readiness. If you have Claude Code or Codex CLI installed on the host, the installer wires them automatically — DPF skills, MCP tools, and kernel-tier memory all available on the first turn of every new contributor session. Re-running the installer is a no-op when nothing has drifted. See Install operations for the readiness states and what each one means.
Releases & versions. Stable versions are published on the Releases page — each carries a changelog and downloadable source archives (.zip / .tar.gz). The install scripts above (which track main) remain the recommended path; the Releases page is where you see what changed between versions and pin a specific one. Releases are cut automatically from each vX.Y.Z tag.
If you hit a wall — happy-path success stories and "the installer hit a wall at step X" failures are equally useful — open an issue using the Install verification report template and attach the bundle produced by bash install-dpf.sh doctor.
If you want to contribute to the codebase rather than just run it:
- Developer Setup — native
pnpm+ Docker sidecars, IDE debugging, hot reload. - Dev Container Setup — fully containerized; only Docker Desktop and VS Code required.
- Development Workspace — how Build Studio, VS Code, policy states, and validation environments fit together.
Self-developing installs use one shared workspace per install:
- Build Studio always works from that workspace.
- In customizable installs, VS Code works from the same workspace.
- Production promotion is governed through the portal.
- Contribution policy (
fork_only/selective/contribute_all) is configured later in the portal.
Worktrees created by scripts/new-dev-worktree.sh give you source-control isolation — your branch, your working tree, your commits — so concurrent sessions and the self-upgrade loop don't reset your work. They are not a second runtime.
For each change:
- Edit and commit from the worktree.
- Cheap source-local checks (targeted Vitest,
pnpm typecheckon the changed package) can run in the worktree if its deps resolve cleanly. - For anything that exercises the live platform — portal routes, server actions, MCP tools, DB-bound behavior, Build Studio flows — verify against the canonical install at the root clone (or a leased shared nonprod environment), and capture that evidence in the PR.
- If the worktree can't run a build/test because pnpm/corepack isn't on PATH, workspace symlinks point outside the worktree, the Prisma client is missing, or Turbopack rejects a cross-workspace symlink — that's a harness limitation, not a product defect. Route the verification through the shared local-CI convergence sandbox (one runtime every worktree leases sequentially via
local-integration-ci); per-worktree runtimes don't scale at DPF's expected 1k–10k concurrent worktrees.
Full rule: AGENTS.md §5 and worktree-is-source-control-not-runtime. The Quick dev commands below assume you're either in the root install or a worktree whose dep graph already resolves — they are not a claim that every worktree is a standalone runtime.
| Task | Command |
|---|---|
| Install dependencies | pnpm install |
| Start the dev server | pnpm dev |
| Typecheck | pnpm typecheck |
| Run tests | pnpm test (Vitest) |
| Generate TAK Word doc | pnpm docs:tak |
| Diagnostic bundle | bash install-dpf.sh doctor |
| Verify the install | bash scripts/verify-install-edge.sh |
| Stop / start the running stack | bash dpf-stop.sh · bash dpf-start.sh |
Pre-commit hooks run typecheck. Run pnpm test locally before pushing — CI runs the full Vitest suite and breaks for everyone if a test regresses.
apps/
web/ Next.js portal — the platform surface
mobile/ React Native 0.83 / Expo SDK 55 / React 19.2 companion app
packages/
db/ Prisma schema, seeds, migrations, model profiles
api-client/ Typed client for the portal API
validators/ Shared Zod validators (incl. edge event envelope)
types/ Cross-package type-only exports
finance-templates/ AI provider supplier contract templates
storefront-templates/ Storefront archetype scaffolds
integration-shared/ Shared adapter contracts
services/
edge-node/ Linux container Edge Node runtime
edge-node-go/ Mode 4 native Edge Node binary (Windows / macOS / embedded)
adp/ ADP payroll connector (early)
browser-use/ Headless browser MCP service
integration-test-harness/ E2E test harness
infra/
terraform/single-vm/{aws,gcp,azure}/ Cloud Single-VM modules
docs/
index.html Public homepage (opendigitalproductfactory.com)
README.md Documentation index
user-guide/ Operator-facing pages, also bundled into in-app help
install/ Per-platform install runbooks
architecture/ TAK, GAID, white paper, conformance, diagrams
superpowers/specs/ Dated design specs (the "why" record)
superpowers/plans/ Dated implementation plans (the "how" record)
founder-kernel/wiki/principles/ Tiered platform principles (retrievable via wiki_query MCP)
scripts/ Install, lifecycle, build, backup, hardware detection, verification
.github/ Workflows, issue templates, DCO config
Three buckets matter when filing new contributor material:
docs/superpowers/specs/— design rationale, dated, append-only history of decisionsdocs/superpowers/plans/— implementation plans, also dated, tracked through to shipdocs/user-guide/— operator-facing pages, bundled into the portal's in-app help
Specs and plans are historical context; user-guide pages are onboarding material.
The deployment architecture keeps Windows, macOS, native Linux, customer-cloud, and TAPPaaS aligned to the same canonical contracts while each target carries its own maturity level:
- Deployment Contracts — 10 canonical contracts every deployment target wraps (release artifacts, runtime config, lifecycle, identity, edge, build execution, observability, secrets, LLM / agent routing, client / API surfaces)
- Cloud Deployment Design — substrates (Single VM, Managed container service, Managed Kubernetes) and packaging targets
- DPF Edge Node — host-resident trust + connectivity for discovery, MCP / A2A gateway, identity brokering
- Edge Node Deployment Matrix — Mode 1 container vs. Mode 4 native binary per host substrate, with the verified-2026-05-20 Docker Desktop finding
- Build Execution Provider — sandbox lifecycle abstraction so Build Studio runs on substrates beyond local Docker
- Mac / Linux Installer-Parity Roadmap — 10-phase implementation plan for native macOS (Apple Silicon) + native Linux installs
For runtime topology — container layout, hardware tiers, Docker Compose breakdown, monitoring stack — see docs/architecture/platform-overview.md.
- Install and run your own instance.
- Add capabilities for your context.
- Share back what's useful to others.
Every extension — a new role, a new route, a new agent skill — follows the same pattern. No special access needed. Fork, build, contribute.
AGENTS.md is the canonical operating contract for any AI agent working in this codebase, and it doubles as the durable operating rules for human contributors. Tool-specific files (CLAUDE.md, .cursor/rules/, .clinerules/, .github/copilot-instructions.md, CONVENTIONS.md, .continue/rules/) are pointers to it — do not duplicate rules into them.
Durable governance also lives as tiered principles under docs/founder-kernel/wiki/principles/, retrievable at runtime via the wiki_query MCP tool.
- Topic branches off
origin/main— short-lived, one PR per branch - All changes land via PR;
mainis the release branch, force-push protected - DCO sign-off required on every commit (
git commit -s) - For concurrent sessions: each runs in its own
git worktree; usegit commit --only <paths>with positional arguments so a parallel session's staged files do not sweep into your commit - Never
--no-verify, never--no-gpg-sign, never amend across sessions
| Gate | What it does | Notes |
|---|---|---|
| DCO | Confirms every commit carries Signed-off-by: |
Required. Use git commit -s. |
| signoff | App-tier sign-off check | Skipped if no concerns flagged. |
| Typecheck | pnpm typecheck against the merged tree |
Pre-commit hook only runs this; CI is the canonical run. |
| Unit Tests | Full Vitest suite | Run locally before pushing. |
| Production Build | next build |
Catches Turbopack / NFT cascade regressions. |
| Analyze (actions / go / javascript-typescript / python) | CodeQL across the multi-language tree | The Go agent under services/edge-node-go/ is in scope. |
| Routing Invariants Audit | Re-runs seed + invariant guards against the PR's merge-base | Failure typically means a seed contract drifted; rebase onto current main if a fix has since landed. |
| Routing Tier Contract | Verifies ModelTierPolicy cost-tier → model bindings are consistent |
Touches anything under packages/db/data/? Expect this gate. |
| Stall Detection Write Guard | Asserts stall-detection invariants for Build Studio recovery | Touches apps/web/lib/build-studio/? Expect this gate. |
| Dockerfile Node Version | Asserts the Node version in Dockerfile* matches the workspace |
Bumping Node? Update all three Dockerfiles. |
- TypeScript strict mode (
noUncheckedIndexedAccess,exactOptionalPropertyTypes) - New features need Vitest tests
- Follow existing patterns (server actions, React cache, auth gates)
- Stay current on dependencies — bump patch / minor proactively; capture blocked majors as tracked work
Longer-form contributor guidance — full branch model, PR checklist, local verification workflow, the cross-session etiquette — lives in CONTRIBUTING.md.
- docs/README.md — documentation index
- docs/user-guide/ — operator-facing guides, bundled into the portal's in-app help
- docs/user-guide/market-archetypes.md — archetype-led user narrative and coworker positioning
- docs/personas/ — persona proof library for archetype-led marketing and dogfood testing
- docs/install/ — per-platform install runbooks
- docs/architecture/ — runtime, deployment, standards, governance
- docs/superpowers/specs/ — dated design specs (the "why" record)
- docs/superpowers/plans/ — dated implementation plans
Licensed under the Apache License, Version 2.0.
Contributions are accepted under the Developer Certificate of Origin (DCO). By submitting a pull request, you certify that your contribution is your original work and you grant an irrevocable license under the project's Apache-2.0 license.
Required attributions for bundled open-source dependencies are listed in NOTICE. Credit to the standards bodies, frameworks, and authors whose ideas shaped DPF is in ACKNOWLEDGMENTS.md.