\n \n
\n ![\"Website\"](\"https://img.shields.io/badge/Website-synapseorch.com-0A0A0A?logo=vercel&logoColor=white\"){kind=icon}
![\"Docs\"](\"https://img.shields.io/badge/Docs-docs.synapseorch.com-blue?logo=readthedocs&logoColor=white\"){kind=icon}
![\"Discord\"](\"https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white\"){kind=icon}
![\"GitHub](\"https://img.shields.io/github/stars/synapseorch-ai/synapse-ai?style=social\")
![\"License\"](\"https://img.shields.io/github/license/synapseorch-ai/synapse-ai\")
![\"npm\"](\"https://img.shields.io/npm/v/synapse-orch-ai?logo=npm&label=npm\")
![\"PyPI\"](\"https://img.shields.io/pypi/v/synapse--orch-ai?logo=pypi&logoColor=white&label=pypi\")
![\"Docker](\"https://img.shields.io/docker/pulls/synapseorchai/synapse-ai?logo=docker&logoColor=white&label=docker\")
\n ๐ Website ยท \n ๐ Documentation ยท \n ๐ฌ Discord\n
\n\n---\n\n## Install\n\n### Quick Setup Script (recommended)\n\n**macOS / Linux:**\n```bash\ncurl -sSL https://raw.githubusercontent.com/synapseorch-ai/synapse-ai/main/setup.sh | bash\n```\n\n**Windows (PowerShell):**\n```powershell\nirm https://raw.githubusercontent.com/synapseorch-ai/synapse-ai/main/setup.ps1 | iex\n```\n\n### npm\n```bash\nnpm install -g synapse-orch-ai\nsynapse\n```\n\n### pip\n```bash\npip install synapse-orch-ai\nsynapse\n```\n\n### Docker\n```bash\ndocker run -d \\\n -p 3000:3000 \\\n -v synapse-data:/data \\\n -v /var/run/docker.sock:/var/run/docker.sock \\\n synapseorchai/synapse-ai:latest\n```\n\nThen open `http://localhost:3000`. See the [Docker guide](https://docs.synapseorch.com/getting-started/installation#docker) in the docs for custom ports and environment variable configuration.\n\n> **Security:** publish only the frontend port `3000` โ the backend (`8765`) serves an internal API and should not be exposed on `0.0.0.0` (docker-compose binds it to `127.0.0.1`). The container auto-generates a shared internal token so that surface is authenticated by default. For any network-reachable deployment, enable **login** (Settings โ Security) and/or set `allow_stdio_mcp=false`, since registering a stdio MCP server launches local commands.\n\n### Upgrading\n\n| Install method | Upgrade command |\n|---|---|\n| Bash / PowerShell installer (recommended) | `synapse upgrade` |\n| pip | `pip install --upgrade synapse-orch-ai` |\n| npm | `npm update -g synapse-orch-ai` |\n| Docker | `docker pull synapseorchai/synapse-ai:latest` |\n\n> **Upgrade note (security hardening):** the backend now auto-generates a shared internal token and, under docker-compose, binds its port to `127.0.0.1` by default. The UI and its API are unaffected (the frontend proxies the backend internally). If you previously called the **backend directly** on `:8765` (e.g. external API clients), either point them at the frontend instead โ `http://host:3000/api/v1|v2/...` โ or set `SYNAPSE_BACKEND_BIND=0.0.0.0` in `.env` to keep publishing `:8765`.\n\n---\n\n## Scale Mode\n\nRun unlimited agents and orchestrations concurrently. When you need to go beyond a single process, the distributed scale layer handles the load:\n\n- **Redis Cluster** โ job queue, SSE event streams, pub/sub cancellation signals, auto-failover\n- **ARQ worker fleet** โ 1 to 100+ independent workers, each running up to 20 concurrent orchestrations; autoscale with KEDA on queue depth\n- **PgBouncer** โ multiplexes hundreds of worker connections into a small, stable Postgres pool\n- **S3 artifact storage** โ stream large file outputs directly to AWS S3, Cloudflare R2, or MinIO\n- **Multi-tenant quotas** โ per-team or per-customer concurrent run limits with HTTP 429 enforcement\n- **Per-step checkpoint recovery** โ worker crashes don't lose jobs; the next worker resumes from the last completed step\n\nThree Docker images โ pull only what you need:\n\n```bash\ndocker pull synapseorchai/synapse-ai:latest # full app (standalone mode)\ndocker pull synapseorchai/synapse-ai-api-server:latest # stateless API server (scale mode)\ndocker pull synapseorchai/synapse-ai-worker:latest # worker process (scale mode, run as many as needed)\n```\n\nThe `docker-compose.yml` in the repo spins up the full stack. Production K8s manifests are in `infra/k8s/`.\n\n๐ [**Scale Mode docs โ**](https://docs.synapseorch.com/scale/overview)\n\n---\n\n## What Makes Synapse Different\n\n- **Multi-Model Orchestrations** โ Run a different LLM at every step. Use a fast model for routing, a powerful one for analysis. You control where the compute goes.\n- **Deterministic DAG Execution** โ Orchestrations follow the exact path you designed. No hallucinated detours.\n- **Turn Anything Into a Tool** โ Python scripts, REST APIs, webhooks, MCP servers, or entire orchestrations โ all become agent-callable tools.\n- **Human-in-the-Loop** โ Pause workflows for human review. Resumable across restarts. Connect via UI, Slack, Telegram, or any messaging channel.\n- **Scales to Millions of Requests** โ The distributed scale layer separates API servers, Redis job queues, and independent worker processes so you can run any number of agents or orchestrations concurrently. Start on one machine, grow to a Kubernetes cluster โ the V2 API never changes.\n- **Local-First, No Lock-In** โ Full local operation with Ollama. Mix local and cloud models freely. Your data stays yours.\n- **Built-In Scheduling & Messaging** โ Cron-based automation with results pushed to Slack, Discord, Telegram, Teams, or WhatsApp.\n- **14+ LLM Providers** โ Cloud, local, and CLI providers including Ollama, OpenAI, Anthropic, Gemini, xAI, DeepSeek, AWS Bedrock, and more.\n\n๐ [**Learn more โ**](https://docs.synapseorch.com)\n\n---\n\n## Synapse UI\n\nhttps://github.com/user-attachments/assets/7a5ab42c-5fae-4f13-876c-13aa9b5a0366\n\n## Demos\n\n### Content Writing Orchestration\nMulti-agent pipeline that researches a topic, drafts content in a Google Doc, and returns the shared link. *(Video is 2x speed)*\n\nhttps://github.com/user-attachments/assets/4eec5db8-70d0-47b6-8608-f52b1f7b7d68\n\n### Autonomous Code Development & PR Creation\nMulti-agent system with human-in-the-loop that writes code and generates pull requests autonomously.\n\nhttps://github.com/user-attachments/assets/95a511e1-e3e9-4812-b9ca-f7f4c28ef80f\n\n### Native Orchestration Builder\nChat with the AI builder โ describe what you want, and it creates the orchestration DAG for you.\n\nhttps://github.com/user-attachments/assets/282cc99d-cdea-4ad0-b648-f22112c6e295\n\n---\n\n## Key Concepts\n\n| Concept | Summary |\n|---|---|\n| **Agents** | Independent ReAct loops with their own system prompt, tools, model, and repos. [Docs โ](https://docs.synapseorch.com/agents/overview) |\n| **Orchestrations** | DAGs of steps โ wire agents together with routing, parallelism, loops, and human gates. [Docs โ](https://docs.synapseorch.com/orchestrations/overview) |\n| **Tool Ecosystem** | 10+ native tool servers, built-in MCP servers, remote MCP via OAuth/PAT, and custom HTTP/Python tools. [Docs โ](https://docs.synapseorch.com/tools/overview) |\n| **AI Builder** | A meta-agent that designs and materializes orchestrations from natural language. [Docs โ](https://docs.synapseorch.com/orchestrations/ai-builder) |\n| **Schedules** | Cron/interval automation with messaging notifications. [Docs โ](https://docs.synapseorch.com/integrations/scheduling) |\n| **Messaging** | Slack, Discord, Telegram, Teams, WhatsApp โ with multi-agent mode. [Docs โ](https://docs.synapseorch.com/integrations/messaging) |\n| **Scale Mode** | Distributed execution layer: Redis job queue, independent worker fleet, per-step Postgres checkpoints, S3 artifact storage, and multi-tenant quotas. [Docs โ](https://docs.synapseorch.com/scale/overview) |\n| **V2 API** | Stable versioned REST API for building products on top of Synapse โ enqueue, stream, cancel, webhooks. [Docs โ](https://docs.synapseorch.com/api/overview) |\n| **Vault** | Persistent file storage shared across agents and sessions. [Docs โ](https://docs.synapseorch.com/vault) |\n\n---\n\n## CLI\n\n```bash\nsynapse start # start backend + frontend, open browser\nsynapse stop # stop background processes\nsynapse upgrade # upgrade to the latest version\nsynapse uninstall # remove Synapse, wipe ~/.synapse, and uninstall the package\n```\n\n---\n\n## Roadmap\n\n- **Spawn Sub-Agent Tool** โ Agents natively spawn and delegate tasks to temporary sub-agents mid-execution.\n- **Compact Conversations** โ Automatic message history compression for large contexts.\n- **Global Variables** โ Dynamic variables injectable into prompts, orchestrations, tools, and MCP environments.\n\n---\n\n## Star History\n\n[](https://www.star-history.com/#synapseorch-ai/synapse-ai&type=date&legend=top-left)\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup, architecture details, how to add MCP tool servers, and the PR checklist.\n\n## License\n\nSynapse AI is licensed under AGPL v3 โ see [LICENSE](LICENSE)\n","readmeFilename":"README.md"}