Installation
Choose a deployment path: Docker, native, desktop, or tunnel.
Pick the path that matches your machine. Every path converges on the same gateway, the same dashboard, and the same configuration model — so you can start with Docker on a laptop and move to native systemd in production without relearning anything.
Which path should I take?#
| Path | Best for | Time |
|---|---|---|
| Docker | Laptops, servers, evaluation — the shortest route | ~5 minutes |
| Native install | Linux hosts, systemd production, Windows services | ~15 minutes |
| Desktop app | Windows users who want a double-clickable app | ~5 minutes |
| Cloudflare tunnel | Temporary public access to a local stack | ~5 minutes |
If you are unsure, use Docker. It is the best-tested path and the one the troubleshooting guide assumes.
Prerequisites#
| Requirement | Docker path | Native path |
|---|---|---|
| Docker with Compose v2 | Yes | No |
| Go 1.27 toolchain | No | For building from source |
| A provider API key | For real answers | For real answers |
| Open ports | 3000, 8080, 3001 | 3000, 8080 |
PostgreSQL, Redis, ClickHouse, and NATS are started for you by Compose on the
Docker path, and provisioned by synapass native install on the native path.
You do not install them separately.
No provider key yet? The stack boots without one. Providers report unconfigured until a key is added, and the smoke suite verifies the whole pipeline without any key at all.
What every path gives you#
| Service | Default URL |
|---|---|
| Dashboard | http://127.0.0.1:3000 |
Gateway (/health · /ready · /metrics) | http://127.0.0.1:8080 |
| Grafana | http://127.0.0.1:3001 |
If port 8080 is taken, move the host port rather than the container port — gateway configuration does not change:
GATEWAY_PORT=18080
NEXT_PUBLIC_SYNAPASS_API_URL=http://localhost:18080After installing#
- Open the dashboard and create the console administrator — there are no default credentials. See Dashboard → Authentication.
- Add a provider key to
.env(OPENAI_API_KEY/ANTHROPIC_API_KEY). - Mint an API key and make your first call from Getting started.
- Run the smoke suite to verify the whole stack automatically — no provider key needed:
bash scripts/smoke.shpowershell -ExecutionPolicy Bypass -File scripts/smoke.ps1