Docker

Synapse AI ships a Docker image that bundles the Python backend and Next.js frontend into a single container. Docker Compose is also supported for multi-container deployments.

Single container (quickstart)

docker run -d \
  --name synapse \
  -p 3000:3000 \
  -p 8000:8000 \
  -v synapse-data:/data \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e SYNAPSE_DATA_DIR=/data \
  synapseorchai/synapse-ai:latest

Flag	Purpose
-p 3000:3000	Frontend UI
-p 8000:8000	Backend API
-v synapse-data:/data	Persist agents, settings, vault, logs
-v /var/run/docker.sock	Required for the Python sandbox tool
-e SYNAPSE_DATA_DIR=/data	Point Synapse at the mounted volume

Open http://localhost:3000 once the container is running.

Passing API keys

docker run -d \
  --name synapse \
  -p 3000:3000 -p 8000:8000 \
  -v synapse-data:/data \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e SYNAPSE_DATA_DIR=/data \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -e OPENAI_API_KEY=sk-... \
  synapseorchai/synapse-ai:latest

API keys passed as environment variables are picked up automatically by the backend. You can also set them via the Settings UI after startup.

Docker Compose

The repo includes a docker-compose.yml for a two-container setup (backend + frontend as separate services):

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

# Copy and edit the env file
cp .env.example .env

# Start services
docker compose up -d

The compose file sets BACKEND_URL=http://synapse-backend:8000 so the frontend can reach the backend by container name on the Docker network.

Compose file overview

services:
  synapse-backend:
    build:
      context: .
      dockerfile: Dockerfile.backend
    ports:
      - "8000:8000"
    volumes:
      - synapse-data:/data
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - SYNAPSE_DATA_DIR=/data

  synapse-frontend:
    build:
      context: .
      dockerfile: Dockerfile.frontend
    ports:
      - "3000:3000"
    environment:
      - BACKEND_URL=http://synapse-backend:8000
    depends_on:
      - synapse-backend

volumes:
  synapse-data:

Custom port

To run on a different port, set SYNAPSE_BACKEND_PORT and SYNAPSE_FRONTEND_PORT:

docker run -d \
  -p 9000:9000 -p 4000:4000 \
  -e SYNAPSE_BACKEND_PORT=9000 \
  -e SYNAPSE_FRONTEND_PORT=4000 \
  -e NEXT_PUBLIC_BACKEND_PORT=9000 \
  synapseorchai/synapse-ai:latest

note

NEXT_PUBLIC_BACKEND_PORT must match SYNAPSE_BACKEND_PORT and requires a frontend rebuild when changed in an existing image.

Updating the image

docker pull synapseorchai/synapse-ai:latest
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 tool needs access to the Docker socket so it can spin up child containers. Mount /var/run/docker.sock as shown above. Without it, the sandbox tool will be unavailable but all other tools continue to work.

Available images

Image	Description
synapseorchai/synapse-ai:latest	Combined backend + frontend
synapseorchai/synapse-ai:backend	Python backend only
synapseorchai/synapse-ai:frontend	Next.js frontend only