https://github.com/aureliolo/synthorg
SynthOrg — Framework for building synthetic organizations with autonomous AI agents
https://github.com/aureliolo/synthorg
agent-framework ai-agents ai-orchestration autonomous-agents litellm litestar llm mcp multi-agent pydantic python react-dashboard synthetic-organization
Last synced: about 17 hours ago
JSON representation
SynthOrg — Framework for building synthetic organizations with autonomous AI agents
- Host: GitHub
- URL: https://github.com/aureliolo/synthorg
- Owner: Aureliolo
- License: other
- Created: 2026-02-27T07:34:13.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-11T14:22:54.000Z (6 days ago)
- Last Synced: 2026-04-11T14:26:39.995Z (6 days ago)
- Topics: agent-framework, ai-agents, ai-orchestration, autonomous-agents, litellm, litestar, llm, mcp, multi-agent, pydantic, python, react-dashboard, synthetic-organization
- Language: Python
- Homepage: https://synthorg.io
- Size: 12 MB
- Stars: 4
- Watchers: 0
- Forks: 0
- Open Issues: 27
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Security: .github/SECURITY.md
- Roadmap: docs/roadmap/future-vision.md
- Agents: AGENTS.md
- Cla: .github/CLA.md
Awesome Lists containing this project
README
> [!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](https://github.com/Aureliolo/synthorg) or check the [roadmap](docs/roadmap/).
SynthOrg
A framework for building synthetic organizations -- autonomous AI agents orchestrated as a virtual company.
-blue)
---
## What is SynthOrg?
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.
## Capabilities
**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 retrieval pipeline, 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.
## Quick Start
### Install CLI
```bash
# Linux / macOS
curl -sSfL https://synthorg.io/get/install.sh | bash
```
```powershell
# Windows (PowerShell)
irm https://synthorg.io/get/install.ps1 | iex
```
### Setup & Run
```bash
synthorg 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 images
```
Open [http://localhost:3000](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.
### Development (from source)
```bash
git clone https://github.com/Aureliolo/synthorg.git
cd synthorg
uv sync # install dev + test deps
uv sync --group docs # install docs toolchain (zensical)
```
### Docker Compose (manual)
```bash
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 # stop
```
## Architecture
```mermaid
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]
API[REST & WebSocket API] --> Engine
Observability[Observability] -.-> Engine
Persistence[Persistence] -.-> HR
Persistence -.-> Security
Persistence -.-> Engine
```
## Documentation
| Section | Description |
|---------|-------------|
| [Design Specification](docs/design/index.md) | Vision, agents, communication, engine, memory, operations, brand & UX, page structure |
| [Architecture](docs/architecture/index.md) | System overview, tech stack, decision log |
| [API Reference](docs/rest-api.md) | REST API reference (Scalar/OpenAPI) |
| [Library Reference](docs/api/index.md) | Auto-generated from docstrings |
| [Security](docs/security.md) | Security architecture, hardening, CI/CD security |
| [Developer Setup](docs/getting_started.md) | Clone, test, lint, contribute |
| [User Guide](docs/user_guide.md) | Install, configure, run via Docker |
> **Contributors:** Start with the [Design Overview](docs/design/index.md) before implementing any feature -- it is the mandatory starting point for architecture, data models, and behavior. [`DESIGN_SPEC.md`](docs/DESIGN_SPEC.md) serves as a pointer to the full design set.
## Status
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](docs/roadmap/) for what's next.
## License
[Business Source License 1.1](LICENSE) -- 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](LICENSE). See [licensing details](https://synthorg.io/docs/licensing/) for the full rationale and what's permitted.