Synapse/Docs
GitHub

Installation

Verified installation commands for Linux, macOS, WSL2, Windows, Termux, npm, Docker, and Railway.

v0.20.5source on GitHub

Use the official installer for your platform. Commands below are taken verbatim from the repository README — nothing invented. The installer is idempotent: re-running it repairs or updates an existing install.

npm (all platforms)

The npm package synapse-ai-agent is a zero-dependency bootstrap: it detects your OS, downloads the official installer, and runs it with the right interpreter.

bash
npx synapse-ai-agent

# or pinned globally:
npm install -g synapse-ai-agent
synapse-ai-agent

Linux / macOS / WSL2 / Termux

bash
curl -fsSL https://raw.githubusercontent.com/johsua092-ui/synapse-ai-agent/main/scripts/install.sh | bash

source ~/.bashrc    # reload shell (or: source ~/.zshrc)
synapse              # start chatting!

What the script sets up for you: uv (Python package manager), Python 3.11, Node.js, ripgrep, ffmpeg, and a managed checkout of the repository. Everything lives under your Synapse home so it does not fight your system packages.

Windows (native PowerShell)

powershell
iex (irm https://raw.githubusercontent.com/johsua092-ui/synapse-ai-agent/main/scripts/install.ps1)

Native Windows is fully supported — CLI, gateway, TUI, and tools run natively. The installer handles uv, Python 3.11, Node.js, ripgrep, ffmpeg, and a portable Git Bash (MinGit) unpacked to %LOCALAPPDATA%\synapse\git. If you prefer WSL2, the Linux one-liner works there too.

Docker (self-host)

bash
SYNAPSE_UID=$(id -u) SYNAPSE_GID=$(id -g) docker compose up -d

See docker-compose.yml and the docker/ directory for the full supervised setup. A Windows compose variant ships as docker-compose.windows.yml. The container runs an s6-overlay supervised entrypoint and persists state through a mounted volume.

Railway (one-click)

  • Deploy from the official template at railway.com/template/synapse-agent
  • Attach a persistent volume mounted at /opt/data ($SYNAPSE_HOME)
  • Set SYNAPSE_DASHBOARD=1 plus an auth provider (Basic Auth vars or OAuth/OIDC) — without one the dashboard fails closed on the public bind
  • Add your provider API keys (OPENROUTER_API_KEY, OPENAI_API_KEY, etc.)
  • Health check is wired to /api/health

Verify your install

After installing, run the doctor. It checks the Python environment, Node tooling, provider reachability, and reports anything missing with suggested fixes.

bash
synapse doctor

Updating

The managed install updates itself in place — no reinstall needed:

bash
synapse update

Hit a snag? The Troubleshooting page lists per-platform fixes, starting with installation problems.