SynapseOrch

Build and run AI agent workflows: start runs, answer what they ask, search knowledge, edit agents.

GitHub
339

Hosted MCP Server

npx add-mcp 'https://api.synapseorch.com/api/v1/mcp'

Installs into Claude Code, Codex, Cursor and more

Documentation

SynapseOrch — AI automation you can read, approve and rely on

Website Docs Discord GitHub stars
PyPI npm Docker pulls License: AGPL-3.0

Hand AI the work your team repeats. Approve what goes out.

Describe a job in plain words. SynapseOrch turns it into steps you can read, runs them exactly as you approved, every time, and asks before anything goes out. Any model, your own tools and documents, on your laptop or your servers. Free and open source under AGPL-3.0, with no account and no licence check.

Install · Documentation · Discord · SynapseOrch Cloud

One sentence to Synapse AI: it asks where the notes live, shows a plan with its cost, and builds the workflow; then the workflow runs, waits for you to approve the summary and the save, and finishes with what each step cost

Describe it. Approve it. Rely on it.

  • Describe it. Tell Synapse AI the job. It writes the steps, picks a model for each and marks where you sign off, then shows you the plan before anything is built.
  • Approve it. Read every step. When a run reaches yours, it waits for your yes — in the app, or in Slack, Telegram or another chat channel.
  • Rely on it. It runs on schedule exactly as you approved, and shows what each step did and what it cost. A run never passes the spending limit you set.
Synapse AI's plan: the steps, the schedule, what a run costs, and what it asks you first
Describe it. Synapse AI shows the plan, what a run costs and what it will ask you — before it builds anything.		 Home: one run waiting on you, with this week's feedback summary to approve
Approve it. When a run reaches your step, it waits on Home for your yes.
A finished run: completed in 37 s, 12 steps, the time it waited on you, and what each step cost

Rely on it. Every run shows the path it took, how long it waited on you, and what each step cost.

What's inside

Synapse AIAn assistant that builds and changes agents and workflows from a sentence, and answers questions about your workspace.
WorkflowsSteps you can read on a canvas: agents, models, tools, code, branches, loops, parallel paths, sign-offs and other workflows. Runs follow the path you drew.
Agents and teamsAgents with their own model, tools, skills and memory. A team agent splits work among its members; any agent can start short-lived helpers.
Sign-offsA step that waits for a person — answered in the app or in a chat channel. Approvals for risky tool calls, too.
KnowledgeYour files and web pages, indexed; answers cite the passage they used. (Optional part — see below.)
BoardsA shared to-do board for people and agents, with each card's history. (Off until you turn it on in Settings.)
Apps and toolsMCP servers (local or remote, OAuth included), REST and OpenAPI, Python functions, SQL databases, web fetch and scraping.
ChannelsYour agents on Slack, Discord, Telegram, Microsoft Teams, WhatsApp, a website chat widget, or a phone number (Twilio).
Any modelYour own keys for 23+ providers, any OpenAI-compatible endpoint, local models through Ollama, or the Claude Code, Codex, Gemini and Copilot CLIs you already use. A different model at every step.
Costs you can readAn estimate before a run, what each step cost after it, and a hard limit per run.
Use it from anywhereA command line, a versioned REST API, an MCP server for Claude, ChatGPT and Cursor, and an OpenAI-compatible endpoint where every agent answers as a model.
Scale modeRedis queue, a worker fleet, Postgres checkpoints and S3 storage, for when one process is not enough.

Install

macOS / Linux

curl -LsSf https://synapseorch.com/install.sh | bash

Windows (PowerShell)

irm https://synapseorch.com/install.ps1 | iex

Nothing needs to be installed first: the installer brings its own Python and, if yours is missing or too old, Node.js — no sudo. It asks which AI to use (and whether to start on login) while it installs, and ends with the link. Your data and settings live in ~/.synapse. Add --yes (curl … | bash -s -- --yes) to take every default. The short addresses redirect to the scripts on the latest GitHub release: setup.sh and setup.ps1.

npm, pip or Docker 
npm install -g synapse-orch-ai && synapse      # the first run uses the same installer
pip install synapse-orch-ai && synapse         # Python 3.11–3.14 and Node.js 20.9+

docker run -d --name synapse -p 3000:3000 -p 127.0.0.1:8765:8765 \
  -v synapse-data:/data \
  -v /var/run/docker.sock:/var/run/docker.sock \
  synapseorchai/synapse-ai:latest

Then open http://localhost:3000. The backend's port (8765) is published on this machine only: it serves an internal API, so never publish it on 0.0.0.0.

Optional parts. Knowledge brings Docling and a CPU build of PyTorch, so it is added only when you ask:

synapse upgrade --with knowledge                              # an existing install
curl -LsSf …/setup.sh | bash -s -- --with knowledge           # a new one

Then turn it on in Settings → General. Every later upgrade keeps it.

Upgrading

synapse upgrade

It backs up the database, installs the newest version, updates the database and starts Synapse again if it was running. An npm install is upgraded with npm install -g synapse-orch-ai@latest; Docker by pulling the new image and running the same command.

Coming from 1.x? Run the install command above, or synapse upgrade. Your agents, workflows, chats, schedules, settings, API keys and vault files move into 2.0's store. Before anything changes, the upgrade backs up your 1.x data folder, logs and .env to ~/.synapse/backups/synapse-1.x-<date>.tar.gz, with a manifest.json that lists where each part came from; the old install's folder is removed once 2.0 is running. To go back, reinstall 1.9.3 and put each part of the backup back where manifest.json says. Don't run 2.0's synapse uninstall first: it removes ~/.synapse, backups included, unless you add --keep-data. Docker imports a 1.x /data volume on its first start. See Upgrading to 2.0.

The command line

One synapse command runs SynapseOrch on this machine, and drives any SynapseOrch — this one, one on your servers, or Cloud — with an API key. Everything you can do in the app, you can do from a terminal or a script.

This machine

synapse start                        # open it (-d: in the background)
synapse status                       # is it running? (--json for scripts)
synapse logs -f                      # follow the backend's log (frontend, install)
synapse upgrade                      # the newest version; data and settings stay
synapse autostart on                 # start when you log in

Build, run and answer

synapse agents list                  # list, show, create, update, delete
synapse workflows list               # list, show, export, create, validate, deploy, delete
synapse run NAME -m "…"              # run a workflow and follow it to its answer
synapse runs waiting                 # what waits on you: questions and held tool calls
synapse runs answer RUN_ID --approve # answer a sign-off (or --reject, or reply with text)
synapse chat --agent NAME -m "…"     # one message to an agent (bare `synapse chat` to talk)
synapse schedules create --workflow NAME --cron "0 9 * * MON"

Knowledge, Boards and the workspace

synapse knowledge upload --base Handbook ./policies/*.pdf --wait
synapse knowledge search "refund window" --base Handbook
synapse boards show BOARD            # a board's open cards; `boards card` adds and comments
synapse activity --days 7            # what ran, what failed, what waits
synapse usage --by model             # what the workspace spent, by day, agent or model

Every door a key has

synapse tools list                   # every product tool this key may call; `tools call NAME`
synapse api GET /agents              # call any route a key reaches, as `gh api` does
synapse mcp                          # serve SynapseOrch to Claude, Cursor… over stdio
synapse login --url https://api.synapseorch.com --api-key-stdin   # drive another SynapseOrch

For scripts, --json prints JSON (one event a line for a run) and -q lists ids only. Exit codes say what happened: 0 done · 3 waiting on a person · 4 run failed · 5 not found · 6 key refused · 7 busy or unreachable. synapse --help lists every command. CLI reference →

Use it from your own code and tools

  • REST API — start runs, stream their events, answer sign-offs, with an API key. API →
  • MCP server — build and run workflows from Claude, ChatGPT or Cursor. MCP server →
  • OpenAI-compatible endpoint — every agent answers as a model to any OpenAI client, with its own tools.

Scale mode

When one process is not enough: a Redis job queue, 1 to 100+ workers, per-step Postgres checkpoints (a worker that dies loses nothing), S3-compatible storage and per-team run limits — behind the same API.

docker pull synapseorchai/synapse-ai-api-server:latest   # stateless API server
docker pull synapseorchai/synapse-ai-worker:latest       # workers, as many as needed

docker compose --profile scale up runs the whole stack (with REDIS_URL set in .env); Kubernetes examples are in infra/k8s/. Scale mode →

Running it on a network

Everything an agent can do runs on the machine Synapse runs on, so treat a shared instance like a server:

  • turn on login (Settings → General) on anything reachable beyond your own machine;
  • publish only the web port (3000) on the network, never the backend's (8765);
  • local MCP servers and custom Python tools run commands: turn them off with allow_stdio_mcp if you do not trust every user, and give agents the narrowest tools that do the job.

Security issues: please report them privately — see SECURITY.md.

SynapseOrch Cloud

The same product, run for you: no servers, managed models, plans with a hard monthly limit, and teams with roles. synapseorch.com

Contributing

See CONTRIBUTING.md for the development setup, how the pieces fit, and the PR checklist. Questions and ideas are welcome on Discord.

License

SynapseOrch is licensed under the GNU AGPL v3.

Star History Chart