Your AI. Your Rules. Your Stack.
Current Release: v2.6.8-dev (Governance Reporting & Takedowns)
SYNAPSE is a self-hosted, provider-agnostic AI orchestration platform. Run it on your own infrastructure, connect local or remote model providers, manage workflows and runtime services, and extend everything through plugins, registries, and integrations — without depending on a third-party cloud or a built-in model.
- Extensible Plugin System — Add channels (Telegram, Discord, WhatsApp), model providers (OpenAI, Anthropic, DeepSeek, Ollama), skills (Claude Code Skills format), and MCP servers. Install community bundles or publish your own.
- Agent Teams — Compose multiple specialized agents into collaborative teams. Each team handles distinct domains and delegates tasks through platform routing.
- AI-Firm (Project Management Layer) — An optional orchestration layer that manages projects across teams, tracks goals, and coordinates long-running workflows.
- Heartbeat & Health Monitoring — Built-in heartbeat system keeps all agents and services in sync. Get notified when something goes offline.
- Self-Learning & Skill Publishing — Agents learn from interactions and can publish reusable skills to the community store (always with explicit user consent).
- Multi-User Support — Full role-based access control. Multiple users can interact with the platform simultaneously with isolated contexts.
- Plugin & Bundle Store — Browse and install community-contributed plugins, bundles, and skill packs from the integrated store. Separate community store from the curated official store.
- Advanced Agent Workflows — Collaboration sessions, inter-agent delegation, shared context, and goal-based planning with versioned plan artifacts.
- Native Java Tools Runtime — Built-in tool discovery and execution (
tool_registry_inspect,plugin_contract_validate) with caching and timeout controls. - Central Hardening Policies — Unified guardrails for delegation/planning/tooling with token-budget and concise-mode signaling.
- CLI + Web Dashboard — A Go-based Bubble Tea TUI for power users and a full Vue 3 web dashboard for everyone else.
- ECHO — Offline Debug Fallback — When all other agents are unavailable, ECHO activates (debug mode only, manual invocation). Never be left completely without assistance.
- Primary validation target: Ubuntu 24.04 on WSL2 or native Linux
- Recommended native toolchain:
- JDK 25+
- Maven 3.9+
- Node.js 22+
- Go 1.26+
- PostgreSQL 18+
- Redis 8+
- Qdrant 1.14+
- Docker Compose is supported as an optional path, not the only install path.
# Clone the repository
git clone https://github.com/FTMahringer/Synapse.git
cd Synapse
# Bootstrap the CLI and generate local config
./install.sh
# Or prepare environment variables manually
cp .env.example .env
# Start local dependencies first, then run the backend
cd packages/core
mvn spring-boot:run
# In another shell, run the dashboard
cd packages/dashboard/frontend
npm install
npm run dev
# In another shell, use the CLI
cd packages/cli
go run . health# Clone the repository
git clone https://github.com/FTMahringer/Synapse.git
cd Synapse
# Prepare environment variables
cp .env.example .env
# Start all services
docker compose -f installer/compose/docker-compose.yml --env-file .env up -d
# Check service health
docker compose -f installer/compose/docker-compose.yml ps
# View logs
docker compose -f installer/compose/docker-compose.yml logs -f backendServices will be available at:
- Backend API: http://localhost:8080
- Dashboard: http://localhost:3000
- PostgreSQL: localhost:5432
- Redis: localhost:6379
- Qdrant: localhost:6333
First-time setup will automatically:
- Create PostgreSQL database
- Run all Flyway migrations (current schema: v15)
- Initialize system metadata
- Sync plugin store registry
- Start backend and dashboard
Key environment variables are documented in .env.example (copy it to .env and adjust values):
# Required for production
JWT_SECRET=your-256-bit-secret-here
SECRETS_ENCRYPTION_KEY=your-32-byte-key-here
# Optional override (defaults to current application build version)
SYNAPSE_VERSION=v2.4.0
POSTGRES_PASSWORD=your-secure-password
ECHO_ENABLED=falseThe native path is the first target for Linux stabilization. Use the Docker path when you specifically want containerized services.
{SYSTEM_NAME} is organized into four distinct layers. Each layer is optional except the Main Agent, which is the core of the platform.
| Layer | Role | Multiplicity | Color |
|---|---|---|---|
| Main Agent | Primary orchestration agent. Handles user interactions, routes to teams, manages plugins and skills, and delegates model work to connected providers. | Exactly 1 | #7B9FE0 |
| AI-Firm | Optional project management orchestrator. Coordinates agent teams, tracks multi-step projects, manages goals and deadlines. | 0 or 1 | #B07FE8 |
| Agent Teams | Optional specialized agent groups. Each team has a domain (e.g., code, research, writing). Teams collaborate via the Main Agent or AI-Firm. | 0 to N | #E07B5A |
| ECHO | Optional local debug helper. Activates only in debug mode and only when invoked manually. Provides raw diagnostic output. | 0 or 1 (debug only) | #4CAF87 |
The platform uses a consistent color system across the dashboard, CLI, and logs to identify agent layers at a glance:
| Element | Hex |
|---|---|
| Background | #0F1117 |
| Surface | #181C27 |
| Main Agent | #7B9FE0 |
| AI-Firm | #B07FE8 |
| Agent Teams | #E07B5A |
| ECHO | #4CAF87 |
Plugins extend {SYSTEM_NAME} in four categories:
| Category | Examples | Notes |
|---|---|---|
| Channels | Telegram, Discord, WhatsApp | Route messages to/from external platforms |
| Model Providers | OpenAI, Anthropic, DeepSeek, Ollama | Swap or combine LLM backends per-agent |
| Skills | Claude Code Skills format | Reusable callable capabilities for agents |
| MCP Servers | Any MCP-compatible server | Extend agents with external tool protocols |
| Layer | Technology |
|---|---|
| Backend | Java 25+, Spring Boot 4.x |
| Frontend | Vue 3, Vite |
| CLI | Go, Bubble Tea TUI |
| Database | PostgreSQL 18+ |
| Cache / Pub-Sub | Redis |
| Containerization | Docker, Docker Compose |
synapse/
├── packages/core/ # Spring Boot 4.x application (Java 25+)
├── packages/dashboard/frontend/ # Vue 3 + Vite web dashboard
├── packages/cli/ # Go CLI with Bubble Tea TUI
├── backend/ # SQL schema, seed, migrations, vault spec
├── plugins/ # First-party plugin implementations
├── store/ # Store metadata and community bundle index
├── install.sh # Linux/macOS interactive installer
├── installer/ # compose files and setup scripts
├── packages/ # Shared packages and libraries
├── agents/ # Agent definitions and default configurations
├── docs/ # Full documentation
│ ├── architecture.md
│ ├── plugin-system.md
│ ├── agent-teams-system.md
│ ├── ai-firm-system.md
│ ├── echo-debug-agent.md
│ ├── store-concept.md
│ └── api-reference.md
└── installer/compose/
Roadmaps and release planning docs live in docs/roadmaps/:
- Implementation Roadmap - Versioned implementation sequence and fixed roadmap labels
- V3 Roadmap - Current feature-milestone execution path
- Docs Roadmap - Documentation planning track
Product/API/operator documentation is maintained in the separate docs repository:
- Live Docs: https://ftmahringer.github.io/Synapse/
- Docs Repo: https://github.com/FTMahringer/Synapse-docs
We welcome contributions of all kinds — bug fixes, new plugins, documentation improvements, and community bundles.
See CONTRIBUTING.md for the full guide, including:
- How to fork, branch, and submit a pull request
- Plugin and bundle submission process
- Skill publishing workflow
- Code style requirements
- Issue reporting guidelines
- Community store vs official store distinction
{SYSTEM_NAME} is released under the MIT License.
Copyright 2026 SYNAPSE Contributors.