Caution
MASSIVE WORK IN PROGRESS -- SynthOrg is under active development and is not ready for production use. APIs, configuration formats, and behavior may change without notice between releases. Some features shown in the documentation are planned but not yet fully implemented. Follow progress on GitHub or check the roadmap.
SynthOrg
A framework for building synthetic organizations -- autonomous AI agents orchestrated as a virtual company.
SynthOrg lets you define agents with roles, personalities, budgets, and tools, then orchestrate them to collaborate on complex tasks as a virtual organization. Each agent has a defined role (CEO, developer, designer, QA), persistent memory, and access to real tools. Agents collaborate through structured communication, follow workflows, and produce real artifacts -- code, documents, designs, and more.
The framework is provider-agnostic (any LLM via LiteLLM), configuration-driven (YAML + Pydantic), and designed for the full autonomy spectrum -- from locked-down human approval of every action to fully autonomous operation.
|
Agent Orchestration Define agents with roles, models, and tools. The engine handles task decomposition, routing, execution loops (ReAct, Plan-and-Execute, Hybrid, auto-selection by complexity), crash recovery (checkpoint resume), and multi-agent coordination. |
Budget & Cost Management Per-agent cost limits, auto-downgrade to cheaper models at task boundaries, spending reports, CFO-level cost optimization with anomaly detection. |
Security & Trust SecOps agent with fail-closed rule engine, progressive trust (4 strategies), configurable autonomy levels, audit logging, and approval timeout policies. Container images are cosign-signed with SLSA L3 provenance, verified by the CLI at pull time. |
|
Memory Per-agent and shared organizational memory with hybrid retrieval pipeline (dense + BM25 sparse with RRF fusion), tool-based and context injection strategies, non-inferable filtering, consolidation, and archival. Pluggable backends via protocol. |
Communication Message bus, hierarchical delegation with loop prevention, conflict resolution (4 strategies), and meeting protocols (round-robin, position papers, structured phases). |
Tools & Integration Built-in tools (file system, git, sandbox, code runner) plus MCP bridge for external tools. Layered sandboxing with subprocess and Docker backends. |
# 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
synthorg start # pull images + start containers
synthorg status # check health
synthorg doctor # diagnostics if something is wrong
synthorg config set channel dev # opt in to pre-release builds
synthorg wipe # factory-reset with interactive backup and restart prompts
synthorg cleanup # remove old container imagesOpen http://localhost:3000 after synthorg start -- on a fresh install, the setup wizard starts with an admin account (if needed), then asks you to choose Guided Setup (template, company, providers, agents with personality presets, theme, and review) or Quick Setup (company name + provider only, configure the rest later in Settings). Providers are configured before agents so model assignment is available during agent customization.
git clone https://github.com/Aureliolo/synthorg.git
cd synthorg
uv sync # install dev + test deps
uv sync --group docs # install docs toolchain (zensical)cp docker/.env.example docker/.env
docker compose -f docker/compose.yml up -d
curl http://localhost:3001/api/v1/health # verify (replace 3001 if BACKEND_PORT was changed)
docker compose -f docker/compose.yml down # stopgraph 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]
API[REST & WebSocket API] --> Engine
Observability[Observability] -.-> Engine
Persistence[Persistence] -.-> HR
Persistence -.-> Security
Persistence -.-> Engine
| Section | Description |
|---|---|
| Design Specification | Vision, agents, communication, engine, memory, operations, brand & UX, page structure |
| Architecture | System overview, tech stack, decision log |
| API Reference | REST API reference (Scalar/OpenAPI) |
| Library Reference | Auto-generated from docstrings |
| Security | Security architecture, hardening, CI/CD security |
| Developer Setup | Clone, test, lint, contribute |
| User Guide | Install, configure, run via Docker |
Contributors: Start with the Design Overview before implementing any feature -- it is the mandatory starting point for architecture, data models, and behavior.
DESIGN_SPEC.mdserves as a pointer to the full design set.
Early development. The core subsystems (agent engine, security, communication, memory, tools, budget, HR, persistence, observability) are built and unit-tested, but the project has not been run end-to-end as a cohesive product. See the roadmap for what's next.
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.