Language:
Sofia Master is a self-hostable orchestration and operations layer for AI product engineering.
It is designed to run above:
- OpenClaw for agent execution
- 9Router for model routing, fallback, and provider abstraction
Sofia adds:
- task and run lifecycle control
- policy-aware model selection
- multi-phase workflows such as
planner -> builder -> verifier - approval gates for risky work
- artifacts, decisions, usage evidence, and audit trail
- recovery, replay, and operator tooling for self-hosted runtime
See PRODUCT-OVERVIEW.md for the product-level summary.
- self-host first
- vendor-neutral runtime stack
- deployable on a single VPS
- built-in backup, restore, release, rollback, and diagnostics
- supports staging and production split on the same host
apps/API, worker, web, and admin surfacespackages/policy, adapters, routing, shared contractsdocs/architecture, install, release, and operations guidesinfra/Compose, Docker, systemd, and Nginx templatesprompts/canonical multi-agent role promptsscripts/doctor, smoke, conformance, release, backup, restore, diagnosticsskills/authored skill sources compiled into.sofia/skillssql/PostgreSQL schemaopenapi/HTTP contract
- Node.js 22+
- pnpm
- PostgreSQL
- Redis
- OpenClaw
- 9Router
For local Compose bootstrap, also install Docker.
Run the unified setup flow:
node scripts/setup.mjsIt supports:
- quick mode for new users
- advanced mode for custom ports / execution mode / token setup
- start everything in the same window
- or setup-only mode that prints the exact service start commands
- startup persistence options: run now, auto-start on boot, or manual mode
- tooling preflight + dry-run support before applying the full setup flow
- Copy
.env.exampleto.env - Run
node scripts/bootstrap.mjs - Run
pnpm install - Start the stack:
docker compose -f infra/compose/docker-compose.yml up -d postgres redis api web admin- Initialize runtime:
node apps/sofia-api/scripts/migrate.js
node apps/sofia-api/scripts/doctor.js
node apps/sofia-api/scripts/smoke.jsFull install detail is in 28-quickstart.md.
Open:
- Web:
http://127.0.0.1:3000 - Admin:
http://127.0.0.1:3001 - API health:
http://127.0.0.1:8080/health
Create a task:
curl -X POST http://127.0.0.1:8080/v1/tasks \
-H "content-type: application/json" \
-d "{\"title\":\"Add a simple login page scaffold to a demo app\",\"templateId\":\"default\"}"Then inspect:
/v1/tasks/v1/runs/v1/runtime/status.sofia/reports/.sofia/artifacts/
Use:
- systemd templates in
infra/systemd/ - Nginx template in
infra/nginx/sofia.conf - release scripts in
scripts/
Recommended deploy flow:
node scripts/release-bundle.mjs
node scripts/release-acceptance.mjs
node scripts/self-host-acceptance.mjs
node scripts/final-readiness.mjsOperational references:
- 31-vps-operations.md
- 32-staging-prod-layout.md
- 25-backup-and-restore.md
- 26-release-and-rollback-playbook.md
- 27-incident-response-playbook.md
The pack includes machine-readable gates for self-host readiness:
skills:validateskills:compileagent-system:conformancedoctorsmokeconformancerelease-readinessrelease-acceptanceself-host-acceptancefinal-readiness
These scripts are intended to prove that the deployable artifact, not just the source tree, is healthy.
This repository is structured to be publish-ready as a self-host implementation pack and runnable Sofia Master scaffold.
Primary docs:
- PRODUCT-OVERVIEW.md
- PRODUCT-OVERVIEW.vi.md
- Documentation Index (EN)
- Documentation Index (VI)
- 28-quickstart.md
- 31-vps-operations.md
- 32-staging-prod-layout.md
- 33-github-publish-checklist.md
- RELEASE-NOTES-v1.0.0.md
Additional public docs: