1 · Install
Open Terminal (Applications → Utilities) and run:
curl -fsSL https://decentralised.si/install/synapse.sh | shThis works on Apple silicon (M1–M4) and Intel Macs; the right build is picked automatically. It installs to ~/.local/bin/synapse. If that folder isn't on your PATH yet, the installer prints the one line to add it.
You can also use SYNAPSE_INSTALL_DIR=/usr/local/bin for a system-wide install (that may ask for your password), or SYNAPSE_VERSION=synapse-v0.2.4 to pin a version.
In a terminal:
curl -fsSL https://decentralised.si/install/synapse.sh | shThese are static binaries for x86_64 and arm64 (Raspberry Pi 4/5 with a 64-bit OS, Graviton, Ampere), so any distribution works with no dependencies. No curl? The installer also works with wget -qO- https://decentralised.si/install/synapse.sh | sh.
Open PowerShell (Start → type “PowerShell”) and run:
irm https://decentralised.si/install/synapse.ps1 | iexIt installs to %LOCALAPPDATA%\synapse\synapse.exe and adds that folder to your user PATH, with no administrator rights needed. Open a new terminal afterwards. On Windows on ARM, the x64 build runs under emulation.
Prefer to read before you run? The scripts are short and commented: synapse.sh · synapse.ps1.
Direct downloads
Each archive contains the synapse binary, the README and example configs. Checksums are in SHA256SUMS.
macOS says “synapse” Not Opened (“Apple could not verify…”)? macOS blocks programs downloaded with a browser until they are notarized by Apple, which our macOS builds are not yet. Use the one-line installer above, which is not affected. Or check the download against SHA256SUMS and clear the browser's download flag: xattr -dr com.apple.quarantine ~/Downloads/synapse-aarch64-apple-darwin (Intel Macs: synapse-x86_64-apple-darwin).
macOS / Linux, by hand
tar -xzf synapse-<platform>.tar.gz
mkdir -p ~/.local/bin
mv synapse-<platform>/synapse ~/.local/bin/
# macOS only, if you downloaded with a browser:
xattr -d com.apple.quarantine ~/.local/bin/synapse
synapse init
Windows, by hand
# unzip, then in PowerShell:
mkdir $env:LOCALAPPDATA\synapse
move .\synapse-x86_64-pc-windows-msvc\synapse.exe $env:LOCALAPPDATA\synapse\
& $env:LOCALAPPDATA\synapse\synapse.exe init
If SmartScreen warns about an unrecognised app, choose More info → Run anyway. The binaries aren't code-signed yet; the checksums let you verify them.
Verify a download
shasum -a 256 synapse-aarch64-apple-darwin.tar.gz # macOS sha256sum synapse-x86_64-unknown-linux-musl.tar.gz # Linux Get-FileHash synapse-x86_64-pc-windows-msvc.zip # Windows PowerShell
Compare the output with the matching line in SHA256SUMS. Every release is built from the public source by this GitHub Actions workflow, and all releases are listed on the releases page.
2 · First run
Start the router. It listens on
127.0.0.1:7766, so only your own machine can reach it.synapse
Open the chat at http://127.0.0.1:7766/. Every answer shows where it was routed and why. You also see the model's reasoning as it streams, the score of every candidate provider, and live stats. Switch the mode per message to compare fast, balanced and deep.
Or use the API. In a second terminal, ask something. Tokens stream back as the answer is generated, starting with a
routeevent that explains which expert was chosen and why.curl -N 127.0.0.1:7766/v1/ask -H 'Content-Type: application/json' \ -d '{"prompt": "Explain Black-Scholes implied volatility."}'On Windows PowerShell, use
curl.exeand escape the inner quotes:-d '{\"prompt\": \"Explain implied volatility.\"}'See a decision without running a model:
curl 127.0.0.1:7766/v1/route -H 'Content-Type: application/json' \ -d '{"prompt": "Write a Rust async TCP server."}'
Out of the box, ~/.synapse/providers.yaml contains three simulated experts, so you can watch routing, fallback and privacy work right away. The answers themselves are canned. Connect real models in the next step.
3 · Connect real models
Edit ~/.synapse/providers.yaml (on Windows, %USERPROFILE%\.synapse\providers.yaml). Replace the simulated entries with your own, telling the router what each one is good at. Then reload without restarting:
curl -X POST 127.0.0.1:7766/v1/providers/reload
A local model with Ollama
Install Ollama, then run ollama pull llama3.1:8b.
providers:
- id: llama-local
adapter: ollama
endpoint: http://127.0.0.1:11434
model: llama3.1:8b
domains: { general: 0.85 }
expected_ttfi_ms: 300
expected_quality: 0.84
Any OpenAI-compatible API
Works with llama.cpp, vLLM, LM Studio, hosted APIs, or DSI Axon, the network's blind router. The key comes from an environment variable and is never written into the file.
- id: dsi-gateway
adapter: openai
endpoint: https://api.decentralised.si/openai/v1
model: auto
api_key_env: DSI_API_KEY
local: false
domains: { general: 0.93 }
expected_ttfi_ms: 500
expected_quality: 0.93
Specialist nodes from the network
Add this to ~/.synapse/router.yaml and set DSI_API_KEY. Synapse then reads the network's public directory every 30 seconds and adds each specialist node as a provider, with its declared expertise, such as the law and accounting nodes. The routing decision is still made on your machine.
discovery:
network:
gateway: https://api.decentralised.si
api_key_env: DSI_API_KEY
hedging:
skip_modes: [deep] # quality-first: wait for the specialist
Declare specialists with domain scores, such as finance.quant.derivatives: 0.97 or technology.software.rust: 0.96, and the router will send matching questions to them. The architecture page explains how scoring works. Get a gateway key in the console.
4 · Keep it running (optional)
Start at login with launchd:
cat > ~/Library/LaunchAgents/si.decentralised.synapse.plist <<EOF <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"><dict> <key>Label</key><string>si.decentralised.synapse</string> <key>ProgramArguments</key><array><string>$HOME/.local/bin/synapse</string></array> <key>RunAtLoad</key><true/> <key>KeepAlive</key><true/> <key>StandardErrorPath</key><string>$HOME/.synapse/synapse.log</string> </dict></plist> EOF launchctl load ~/Library/LaunchAgents/si.decentralised.synapse.plist
Stop it with launchctl unload ~/Library/LaunchAgents/si.decentralised.synapse.plist.
Run it as a systemd user service:
mkdir -p ~/.config/systemd/user cat > ~/.config/systemd/user/synapse.service <<'EOF' [Unit] Description=Synapse local router [Service] ExecStart=%h/.local/bin/synapse Restart=on-failure [Install] WantedBy=default.target EOF systemctl --user daemon-reload systemctl --user enable --now synapse journalctl --user -u synapse -f # logs
Start at sign-in with Task Scheduler, from PowerShell:
$exe = "$env:LOCALAPPDATA\synapse\synapse.exe" $action = New-ScheduledTaskAction -Execute $exe $trigger = New-ScheduledTaskTrigger -AtLogOn -User $env:USERNAME Register-ScheduledTask -TaskName "synapse" -Action $action -Trigger $trigger Start-ScheduledTask -TaskName "synapse"
Remove it with Unregister-ScheduledTask -TaskName synapse.
Useful commands
| Command | What it does |
|---|---|
synapse | Start the router on 127.0.0.1:7766 |
synapse init | Write starter ~/.synapse/router.yaml and providers.yaml (--force to overwrite) |
synapse paths | Show which config files are in use |
synapse --port 7800 --providers ./my.yaml | Override the port or config files (or use SYNAPSE_PORT, SYNAPSE_PROVIDERS…) |
curl 127.0.0.1:7766/v1/providers | Provider health, observed latency and success rate |
curl 127.0.0.1:7766/v1/routes | Recent routing decisions |
Uninstall
# macOS / Linux rm ~/.local/bin/synapse rm -r ~/.synapse # config, history and statistics # Windows (PowerShell) Remove-Item -Recurse $env:LOCALAPPDATA\synapse, $HOME\.synapse
Build from source or use Docker
git clone https://github.com/Decentralised-si/DSI-Synapse cd DSI-Synapse cargo run --release docker build -f docker/Dockerfile -t synapse .
Preview release. Synapse is new: it has passed 36 automated tests and the acceptance demos, but it has not had wide use yet. Binaries are not code-signed. Please report problems on GitHub Issues.