Install locally

For a walkthrough of each step — what the installer asks, the first start and upgrading — see Install on your computer.

Trying 2.0, a release candidate

These docs describe SynapseOrch 2.0, which is a release candidate: 2.0.0-rc3. The commands on these pages install it. The stable release is 1.9.3 until 2.0.0.

To try 2.0 on macOS or Linux, or in Windows PowerShell:

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

irm https://synapseorch.com/install/v2.0.0-rc3.ps1 | iex

Or npm install -g synapse-orch-ai@next, pip install synapse-orch-ai==2.0.0rc3, or the Docker image synapseorchai/synapse-ai:2.0.0-rc3. Already on 1.x? The same command upgrades it — see Upgrading to 2.0.

The stable release, 1.9.3:

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

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

Or npm install -g synapse-orch-ai, pip install synapse-orch-ai, or synapseorchai/synapse-ai:latest.

One-command install

macOS / Linux

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

Windows (PowerShell)

irm https://synapseorch.com/install/v2.0.0-rc3.ps1 | iex

The short addresses redirect to the scripts on the v2.0.0-rc3 GitHub release: setup.sh and setup.ps1.

What it needs: Linux or macOS with curl or wget, or Windows PowerShell, on x64 or arm64 — and port 8765 free. Nothing else: it brings uv, Python 3.12 and, if your Node.js is missing or older than 20.9, its own Node.js 22, all under ~/.synapse (%USERPROFILE%\.synapse on Windows), and the Chromium your agents' browser tools drive. It needs no sudo. On Linux its Node.js needs glibc 2.28 or newer; on Alpine (musl) or an older glibc, install Node.js 20.9+ yourself first.

While it installs, it asks two things:

1. Which AI should Synapse use? — one or more providers, each with its key (It stays on this computer.), checked by listing the provider's models (Add a key for another provider?). Ollama and the Claude Code, Gemini, Codex and Copilot command-line tools are offered when they are found on this computer. Then the Everyday model, which runs your agents and workflows, and Synapse AI's model, the assistant that builds them (Same as everyday model first). Skip for now leaves it for the app, which asks on its first start (below). synapse setup asks the same questions again later.
2. Start Synapse when you log in? — not asked on WSL, or on a Linux without a systemd user session.

It ends with one line, and opens it in your browser:

Synapse is running → http://localhost:3000/?token=…

That is the access link while login is off; synapse access-link prints it again.

If no AI answers yet — you skipped the question, or its key or server can't be reached — the app opens on Connect a model, in two screens:

1. Which AI should Synapse use? says what is missing, then offers what this computer has: under Found on this computer, no key needed, Claude Code, Gemini CLI, Codex and Copilot CLI, each Signed in or Not signed in (with its sign-in command, and Check again), and Ollama with its models. Or pick a provider and paste its key into its card: it reads Key saved, or Key refused. With nothing at all, it offers a free Gemini key or Ollama, each with its trade-off.
2. Pick your two models — the everyday model and Synapse AI's.

It closes from its ✕, Escape, Don't show again or Done, and doesn't open on its own again. Connect a model on Home's Getting started, or on Chat's Model not ready line, opens it again. If port 3000 is taken, the next free port is used. If it says Open a new terminal to use the synapse command., the synapse command is on a new terminal's path.

To ask nothing and keep every default — no AI chosen, no start on login — add --yes: curl … | bash -s -- --yes. --no-start installs without starting, --version 2.0.0 installs a given version, and --with knowledge adds Knowledge's PDF reader. In PowerShell, set each as a variable before the irm line — irm | iex passes no arguments:

For example, curl … | bash -s -- --yes --with knowledge, or in PowerShell $env:SYNAPSE_WITH='knowledge'; irm … | iex.

Everything the installer ran is in ~/.synapse/logs/install.log; a failed step says so, with the last lines of that log and the command to try again — for the release it was installing, a release candidate's own too.

Already on SynapseOrch 1.x? Run the same command — it finds your install, backs it up and moves your data across. See Upgrading to 2.0.

npm

npm install -g synapse-orch-ai@next
synapse

The npm package is a launcher. The first synapse runs the same installer into ~/.synapse; every later synapse passes its arguments to that install. The launcher needs Node.js 18 or newer.

pip

pip install synapse-orch-ai==2.0.0rc3
synapse

A pip install needs Python 3.11–3.14 and Node.js 20.9+ on your path. The first synapse in a terminal, with nothing set up yet, asks a few questions — the agent's name, the AI to use, the ports — then starts. Data lives in ~/.synapse.

Docker

No Python or Node.js required on the host. Ideal for teams deploying on shared infrastructure or servers.

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:2.0.0-rc3

Then open the link that docker logs synapse prints. The Docker socket is for Python tools, which run in sandbox containers; port 8765 is published on this machine only, for OAuth sign-ins. Provider keys are entered in Settings → Models once it is running — they are not read from environment variables. An Ollama on the host is reached like this:

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 \
  -e OLLAMA_BASE_URL=http://host-gateway:11434 \
  --add-host=host-gateway:host-gateway \
  synapseorchai/synapse-ai:2.0.0-rc3

See Docker for the flags.

Custom ports

Change the host side of the mapping and leave the container's ports alone:

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

The UI is then at http://localhost:8080; the link in the log still says :3000, so open it with 8080 instead. To move the UI's own port as well, set it on both sides: -p 8080:8080 -e SYNAPSE_FRONTEND_PORT=8080. Leave the backend on 8765 — see Docker.

From source

git clone https://github.com/synapseorch-ai/synapse-ai.git
cd synapse-ai
pip install -e .
synapse start

A source checkout keeps its data in backend/var/ and its settings in .env at the repository root. To run the two halves by hand instead:

Backend

cd backend
python3.11 -m venv venv
source venv/bin/activate         # Windows: venv\Scripts\activate
pip install -r requirements.txt
python3.11 main.py               # Starts on port 8765 (or $SYNAPSE_BACKEND_PORT)

Frontend

Open a second terminal:

cd frontend
npm install
npm run dev                      # Starts on port 3000 (or $SYNAPSE_FRONTEND_PORT)

System requirements

The one-command install brings its own Python and Node.js. The Python and Node.js rows are for pip and source installs.

Optional dependencies

Upgrading

synapse upgrade stops SynapseOrch, backs up its database to ~/.synapse/backups/, installs the newest release, updates the database and starts it again if it was running. The parts you added (--with knowledge, --with telemetry) stay. See the CLI.

Uninstalling

synapse uninstall

It asks you to type yes, stops SynapseOrch, removes start-on-login, uninstalls the program and deletes ~/.synapse — your agents, workflows, chats, settings and backups. synapse uninstall --keep-data removes the program but keeps your data (var/, .env and backups/). An npm install is removed with npm uninstall -g synapse-orch-ai; a source checkout, by deleting its folder.

Verifying the install

synapse status

Expected output:

backend: running
frontend: running

synapse status --json adds the version, the address, whether the UI answers (ready) and the access link.