Docker

Single container (quickstart)

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

Once the container is running, open the access link it prints in its log — docker logs synapse shows [entrypoint] Access link (used while login is off; …) and the http://localhost:3000/?token=… address below it. See The access link.

The image generates an internal token and an access link on first start, so neither the backend's internal routes nor the UI is left open. Don't publish port 8765 beyond 127.0.0.1, and turn on sign-in (Settings → General) before exposing port 3000 to a network.

Passing API keys

Model provider keys are not read from environment variables — -e ANTHROPIC_API_KEY=… does nothing. After startup, open Settings → Models, fill in the provider's card and click Save. Keys are stored in the database on the /data volume. See Cloud Providers.

Docker Compose

The repository's docker-compose.yml runs the backend, the frontend and a Postgres database as separate services:

# Clone the repo
git clone https://github.com/synapseorch-ai/synapse-ai.git
cd synapse-ai

# Copy the env file — the defaults work as they are
cp .env.docker .env

# Start services
docker compose up -d

Leave SYNAPSE_INTERNAL_TOKEN blank in .env: the containers generate one and share it through a volume. Open the access link the backend prints in its log (docker compose logs backend).

Compose file overview

The backend also mounts the Docker socket, for the Python sandbox. docker compose --profile scale up -d, with REDIS_URL=redis://synapse-redis:6379/0 set in .env, adds Redis and workers — see Scale Deployment.

To reach the backend from other machines, set SYNAPSE_BACKEND_BIND=0.0.0.0 in .env — usually unnecessary, since the external API is served through port 3000.

Custom port

Change the host side of the port mappings and leave the container's own ports alone:

docker run -d \
  --name synapse \
  -p 4000: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:4000. The single-container image's frontend was built to reach its backend on port 8765 inside the container, so changing SYNAPSE_BACKEND_PORT there breaks it. Keep the backend on host port 8765 as well if you use OAuth sign-ins, whose redirect addresses name that port.

The access link in the log still says :3000; open it with your host port instead.

With Compose, set SYNAPSE_FRONTEND_PORT in .env and leave SYNAPSE_BACKEND_PORT at 8765: the backend's mapping, its health check and the frontend's address all name 8765.

Updating the image

docker pull synapseorchai/synapse-ai:2.0.0-rc3
docker stop synapse && docker rm synapse
# Re-run the docker run command above

Your data is persisted in the synapse-data volume and is unaffected by image updates.

Python sandbox inside Docker

The Python sandbox needs the Docker socket so it can start sandbox containers. Mount /var/run/docker.sock as shown above. Without it, execute_python, Python tools and Transform steps fail; all other tools continue to work.

Available images

Each is tagged with the release version and latest.

The images include neither the knowledge extra nor LibreOffice, so a knowledge base reads every format except images, HEIC photos and legacy Office files — see Formats and parsing.