SynthOrg
An autonomous product studio you operate: describe what to build, a synthetic organisation of AI agents plans and delivers it.

---

SynthOrg is a self-contained, self-hostable platform for synthetic organisations: role-based AI agents modelled as an actual company (roles, departments, hierarchies, persistent memory, budgets, governance, structured communication) rather than a task queue or a DAG of function calls. The goal is an autonomous product studio you operate: you describe a product or service to build, or hand it an existing codebase, and the organisation plans, executes, and delivers it under budgets and your steering.

It is provider-agnostic (2700+ LLMs via LiteLLM), configuration-driven (Pydantic v2 models), and licensed BUSL-1.1 (converts to Apache 2.0 at the Change Date).

Project status (read this). The framework and infrastructure are built and tested (31,000+ tests, 80%+ coverage): API, dashboard, CLI, dual-backend persistence, the provider layer, and every subsystem as importable, unit-tested components. The autonomous agent runtime that makes the organisation actually execute work is in active development and tracked openly on the roadmap and the issue tracker. Today, starting SynthOrg brings up the platform and dashboard; running a company end to end is the work in flight. We would rather you see exactly what is built versus in progress than discover it later.

What is available now

A tested platform you can run, inspect, and build on:

• REST + WebSocket API (Litestar) and a React 19 dashboard (org chart, task board, agent detail, budget tracking, provider management, workflow editor, ceremony settings, setup wizard) with live WebSocket / SSE updates.
• Go CLI for Docker orchestration: init, start, stop, status, doctor, config, wipe, cleanup, worker, backup, with cosign signature and SLSA provenance verification at pull time.
• Dual-backend persistence: SQLite (single-node default) and PostgreSQL (multi-instance), conformance-tested for parity, with in-process yoyo schema migrations and ISO 4217 currency stamping on every cost-bearing row.
• Provider layer: any LLM via LiteLLM with built-in retry and rate-limit handling; local model management for Ollama and LM Studio.
• Configuration and templates: define a company in YAML; importable/shareable agent, department, and company templates with personality presets.
• Subsystem libraries, tested as components: the engine, memory, budget, security, and coordination modules exist as importable, unit-tested code. Note honestly: these are exercised by their test suites, not yet by a running agent (see below).
• Client-simulation intake runtime: the intake engine is wired into boot via the client-simulation runtime and driven end-to-end by a deterministic simulation harness (synthetic clients, scripted provider, zero LLM spend), which is also the acceptance substrate for the runtime work in flight.
• Operations: structured logging with redaction and correlation, Prometheus metrics and OTLP, HttpOnly-cookie multi-user sessions with CSRF protection, Chainguard distroless images with Trivy + Grype scanning, cosign signatures, and SLSA L3 provenance.
• Distributed dispatch plumbing: NATS JetStream queue and a worker pool. The dispatch path exists; the task-execute endpoint currently advances task state and does not yet invoke an agent.

In active development

These are the capabilities that make SynthOrg an autonomous studio. They are designed and largely written as components, but not yet wired into a running product. Each is tracked in the open:

• Agent runtime online: agents actually executing tasks (LLM + sandboxed tools) under a minimal safety spine. This is the foundational item everything else depends on.
• Conversational org interface: talk to the company in natural language; it clarifies, proposes, and (later) acts under governance.
• Autonomous product studio substrate: persistent project workspace with pluggable git, brownfield codebase intake, living documentation, and a deep requirements interview.
• Best-in-class operate tier: a golden-company benchmark, mission control with run replay, a cost forecast/kill-switch dial, a measurable learning curve, deterministic replay, run narratives, and an adversarial red-team.
• Agent capability layer: a knowledge and provenance retrieval substrate, research mode, continual improvement, governed external API access, headless-browser and virtual-desktop testing, and more.

The multi-agent coordinator runs end to end behind the provider-present switch (decompose, route, parallel execution, rollup; /coordinate returns a real result when a provider is configured). Coordination metrics, autonomy/trust enforcement on a live run, and the self-improvement loop are designed and unit-tested but not yet exercised end to end. The design for each lives in the Design Specification.

Quick Start

Install

# Linux / macOS
curl -sSfL https://synthorg.io/get/install.sh | bash

# Windows (PowerShell)
irm https://synthorg.io/get/install.ps1 | iex

Run

synthorg init                                   # interactive setup wizard (SQLite default)
synthorg init --persistence-backend postgres    # auto-provision a Postgres container
synthorg start                                  # pull images + start containers

Open localhost:3000; the setup wizard covers LLM providers, company config, agent setup with personality presets, and theme selection. Choose Guided Setup for the full experience or Quick Setup (provider + company name only). This brings up the platform and dashboard. Configuring a provider stores the company; running it as an autonomous organisation is the runtime work in active development, so skipping provider setup yields an empty company by design.

Persistence backends: SQLite (default) for single-node and development, Postgres for multi-instance deployments. The CLI orchestrates both. --persistence-backend postgres generates a dhi.io/postgres DHI service (image tag pinned via DefaultPostgresImageTag in cli/internal/config/state.go), random credentials, and a named data volume. synthorg stop preserves the data volume unless --volumes is passed.

From source

git clone https://github.com/Aureliolo/synthorg.git
cd synthorg
uv sync                  # install dev + test deps
uv sync --group docs     # install docs toolchain

Schema migrations run in-process via yoyo-migrations (installed by uv sync); no external binary required. Building the docs site locally (for D2 diagrams) additionally requires the D2 CLI on PATH.

Docker Compose (manual)

cp docker/.env.example docker/.env
docker compose -f docker/compose.yml up -d
curl http://localhost:3001/api/v1/readyz

Target architecture

The diagram below is the designed architecture. Components exist as code; the edges into and out of the agent engine are what the runtime work (above) brings online.

graph TB
    Config[Config & Templates] --> Engine[Agent Engine]
    Engine --> Core[Core Models]
    Engine --> Providers[LLM Providers]
    Engine --> Communication[Communication]
    Engine --> Tools[Tools & MCP]
    Engine --> Memory[Memory]
    Engine --> Security[Security & Trust]
    Engine --> Budget[Budget & Cost]
    Engine --> HR[HR Engine]
    Meta[Meta-Loop] --> Engine
    Meta --> HR
    Meta --> Budget
    API[REST & WebSocket API] --> Engine
    API --> Meta
    Dashboard[React Dashboard] --> API
    CLI[Go CLI] --> API
    Observability[Observability] -.-> Engine
    Persistence[Persistence] -.-> HR
    Persistence -.-> Security
    Persistence -.-> Engine

Loading

Compare

SynthOrg vs other agent frameworks across organisation structure, multi-agent coordination, memory, budget tracking, security, and observability. The comparison marks SynthOrg capabilities honestly as available now versus planned, matching the status sections above.

Documentation

Section	What's there
User Guide	Install, configure, run, customise
Guides	Quickstart, company config, agents, budget, security, MCP tools, deployment, logging, memory
Design Specification	The designed behaviour of every subsystem (the source of truth; states current wiring status per area)
Architecture	System overview, tech stack, decision log
REST API	Scalar/OpenAPI reference
Library Reference	Auto-generated from docstrings
Security	Application security, container hardening, CI/CD security
Licensing	BUSL 1.1 terms, Additional Use Grant, commercial options
Roadmap	Current status, what works today, what is in active development

Contributors: Start with the Design Specification before implementing any feature. See DESIGN_SPEC.md for the full design set. The design pages describe intended behaviour and mark per-area current wiring status; treat any gap between a spec and src/ as the work, not the spec.

Forking? CI runs out of the box for code changes; the release pipeline needs setup (environments, labels, branch protection, a release-bot GitHub App). On your first push, the CI Preflight workflow opens a tracking issue listing exactly what is missing; see Fork Setup for the long-form walkthrough.

License

Business Source License 1.1: free production use for non-competing organisations with fewer than 500 employees and contractors. Converts to Apache 2.0 on the change date specified in LICENSE. See licensing details for the full rationale and what is permitted.