SynthOrg
Build AI teams that actually collaborate, with roles, budgets, memory, and governance.
-blue){kind=icon}
SynthOrg is a Python framework for building synthetic organizations, autonomous AI agents orchestrated as a virtual company. Unlike task-queue or DAG-based agent frameworks, SynthOrg models agents as members of an actual organization with roles, departments, hierarchies, persistent memory, budgets, and structured communication.
Define your company in YAML. Agents collaborate through a message bus, follow workflows (Kanban, Agile sprints, or custom), track costs against budgets, and produce real artifacts. The framework is provider-agnostic (100+ LLMs via LiteLLM), configuration-driven (Pydantic v2 models), and designed for the full autonomy spectrum, from human approval on every action to fully autonomous operation.
Early access. Core subsystems are built and tested (27,000+ tests, 80%+ coverage). APIs may change between releases. See the roadmap for what's next.
Most agent frameworks give you functions that call LLMs. SynthOrg gives you a company that thinks.
- Roles, not functions. Agents are CEO, engineer, designer, QA, with personality, goals, seniority, and autonomy levels. 9 company templates and 23 personality presets get you started fast.
- Shared organizational memory. Hybrid retrieval pipeline (dense + BM25 sparse with RRF fusion), tool-based and context injection strategies, procedural memory auto-generation from failures, consolidation, and archival. Agents remember across sessions.
- Cost-aware by design. Per-agent token budgets, automatic model downgrade at task boundaries, spending reports, trend analysis, and CFO-level optimization with anomaly detection.
- Trust spectrum. From locked-down (human approves every tool call) to fully autonomous, with a fail-closed security rule engine, output scanning, progressive trust, and audit logging in between.
- Real workflows. Kanban boards, Agile sprints with velocity tracking, ceremony scheduling (8 strategies), visual workflow editor with starter blueprints and version history with diff/rollback, and workflow execution from graph definitions.
- Provider-agnostic. Any LLM via LiteLLM: Ollama, LM Studio, vLLM, and 100+ cloud providers. Local model management with pull/delete/configure for Ollama and LM Studio.
# Linux / macOS
curl -sSfL https://synthorg.io/get/install.sh | bash# Windows (PowerShell)
irm https://synthorg.io/get/install.ps1 | iexsynthorg init # interactive setup wizard (SQLite default)
synthorg init --persistence-backend postgres # auto-provision a Postgres container
synthorg start # pull images + start containersOpen localhost:3000; the setup wizard walks you through company config, LLM providers, agent setup with personality presets, and theme selection. Choose Guided Setup for the full experience or Quick Setup (company name + provider only, configure the rest later).
Persistence backends: SQLite (default) for single-node and development, Postgres for multi-instance and production 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.
git clone https://github.com/Aureliolo/synthorg.git
cd synthorg
uv sync # install dev + test deps
uv sync --group docs # install docs toolchainSchema 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.
cp docker/.env.example docker/.env
docker compose -f docker/compose.yml up -d
curl http://localhost:3001/api/v1/readyzAgent Orchestration: task decomposition, 6 routing strategies, execution loops (ReAct, Plan-and-Execute, Hybrid, auto-selection by complexity), crash recovery with checkpoint resume, multi-agent coordination, and multi-project support with project-scoped teams and isolated budgets.
Agent Evolution: continuous identity evolution based on performance trends with pluggable triggers (batched, inflection, per-task), proposers (separate-analyzer, self-report, composite), and guards (rollback, review, shadow evaluation).
Dynamic Workforce Scaling: closed-loop hiring and pruning with pluggable strategies (workload, budget cap, skill gap, performance), safety guards (conflict resolution, cooldowns, rate limits, approval gates), and a dashboard for manual evaluation triggers.
Budget & Cost Management: per-agent and per-project cost limits with hierarchical cascading, auto-downgrade to cheaper models at task boundaries, spending reports, budget forecasting, and anomaly detection.
Security & Trust: SecOps agent with fail-closed rule engine, progressive trust (4 strategies), configurable autonomy levels (4 tiers), approval gates, LLM fallback evaluator, and audit logging. Container images are cosign-signed with SLSA L3 provenance.
Memory: 5 memory types (episodic, semantic, procedural, working, organizational) with hybrid retrieval, three injection strategies (context, tool-based, and self-editing memory), query reformulation, procedural memory auto-generation from failures, consolidation, and pluggable backends.
Communication: message bus, hierarchical delegation with loop prevention, conflict resolution (4 strategies), meeting protocols (round-robin, position papers, structured phases), and A2A federation with external agent systems.
Tools & MCP: built-in tools (file system, git, sandbox, code runner) plus MCP bridge for external tools. SynthOrg's own MCP server exposes 200+ tools across 15 domains (agents, tasks, workflows, approvals, budget, memory, quality, organization, communication, coordination, analytics, integrations, infrastructure, signals, meta), split across read_tool / write_tool / admin_tool capability actions; destructive admin_tool calls enforce confirm + reason + actor guardrails with attributed audit trail. Layered sandboxing with subprocess and Docker backends. SSRF prevention with configurable allowlists.
Client Simulation: synthetic workload generation with AI, human, and hybrid clients. 5 requirement generators (template, LLM, dataset, procedural, hybrid), 4 feedback strategies (binary, scored, criteria-check, adversarial), multi-stage review pipeline, intake engine with lifecycle management, and batch simulation runner with configurable concurrency.
Web Dashboard: React 19 + shadcn/ui dashboard with org chart, task board, agent detail, budget tracking, provider management, workflow editor, ceremony policy settings, and setup wizard. Real-time WebSocket updates.
Notifications: pluggable notification sinks (console, ntfy, Slack, email) with severity filtering. Approval gates, budget thresholds, and timeout escalations emit alerts through a fan-out dispatcher.
Integrations: typed connection catalog (GitHub, Slack, SMTP, database, generic HTTP, OAuth apps) with pluggable secret backends (Fernet-encrypted SQLite or Postgres, auto-selected to match the persistence backend; env-var fallback; Vault/AWS/Azure stubs). Full OAuth 2.1 (authorization code + PKCE, device flow, client credentials) with proactive token refresh. Webhook receiver with pluggable signature verifiers (GitHub HMAC, Slack signing, generic HMAC) and replay protection. Per-connection health checks with background prober and status smoothing. Tool-side @with_connection_rate_limit decorator backed by a bus-coordinated sliding window. Bundled MCP server catalog and local-dev ngrok tunnel.
Self-Improvement: company-level meta-loop that observes 7 signal domains (performance, budget, coordination, scaling, errors, evolution, telemetry), evaluates 9 built-in rules plus user-defined custom rules (visual rule builder in the dashboard), and produces improvement proposals at 4 altitudes (config tuning, architecture, prompt tuning, code modification). Mandatory human approval, concrete rollback plans, staged rollout with canary selection and A/B testing (Welch's t-test for statistical significance, plus a practical-significance gate requiring a configured practical-improvement threshold on the relative mean improvement over control, not a standardized statistic like Cohen's d, before declaring a win), dispatcher-backed inverse-action rollback, and tiered regression detection (threshold + statistical). Chief of Staff agent with proposal outcome learning (EMA/Bayesian confidence adjustment), proactive org-level inflection alerts between scheduled cycles, and LLM-powered natural language explanations via chat interface. Feature is disabled by default.
CLI: Go binary with init, start, stop, status, doctor, config, wipe, cleanup commands. Cosign signature and SLSA provenance verification at pull time.
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
SynthOrg vs 44 agent frameworks across 14 dimensions: org structure, multi-agent coordination, memory, budget tracking, security, observability, and more.
| Section | What's there |
|---|---|
| User Guide | Install, configure, run, customize |
| Guides | Quickstart, company config, agents, budget, security, MCP tools, deployment, logging, memory |
| Design Specification | Agents, HR lifecycle, org structure, communication, engine, coordination, verification, memory, providers, budget, tools, security, observability, notifications, backup, deployment, brand & UX, strategy |
| Architecture | System overview, tech stack, decision log |
| REST API | Scalar/OpenAPI reference |
| Library Reference | Auto-generated from docstrings (14 modules) |
| Security | Application security, container hardening, CI/CD security (8 scanners) |
| Licensing | BSL 1.1 terms, Additional Use Grant, commercial options |
| Roadmap | Current status, open questions, future vision |
Contributors: Start with the Design Specification before implementing any feature. See
DESIGN_SPEC.mdfor the full design set.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.
Business Source License 1.1: free production use for non-competing organizations 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's permitted.