Docker Deployment

Deploy Sophon with Docker Compose across all three tiers — Personal, Pro, and Enterprise.

Quick Start

Get Sophon running in under a minute:

docker-compose.yml

services:
  sophon-gateway:
    image: buildersoftdev/sophon:latest
    ports:
      - "8081:8080"
    volumes:
      - ${SOPHON_DATA}:/home/sophon/.sophon
    environment:
      - SOPHON__Tier=Personal
      - SOPHON__DataDirectory=/home/sophon/.sophon
    restart: unless-stopped

  sophon-dashboard:
    image: buildersoftdev/sophon-dashboard:latest
    ports:
      - "8080:80"
    environment:
      - SOPHON_GATEWAY_URL=http://sophon-gateway:8080
    depends_on:
      - sophon-gateway
    restart: unless-stopped

# Set your data directory (absolute path, forward slashes on Windows)
export SOPHON_DATA=~/.sophon

docker compose up -d
# Open http://localhost:8080 — the Setup Wizard guides you from here

No API keys, no config files to edit. Everything is configured through the Dashboard on first launch.

Prerequisites

Tier	RAM	Disk	CPU	Additional Services
Personal	2 GB	2 GB	1 core	SQLite (embedded)
Pro	4 GB	10 GB	2 cores	PostgreSQL, Qdrant
Enterprise	8 GB+	20 GB+	4 cores	PostgreSQL, Qdrant, Redis, RabbitMQ

Software:

Docker 24.0+ with Compose V2
curl (for health checks)
openssl (for generating passwords in Pro/Enterprise)

Personal Tier

Single-container deployment with SQLite. Ideal for individual use.

docker-compose.yml

services:
  sophon-gateway:
    image: buildersoftdev/sophon:latest
    ports:
      - "${GATEWAY_PORT:-8081}:8080"
    volumes:
      - ${SOPHON_DATA:?Set SOPHON_DATA in .env}:/home/sophon/.sophon
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - ASPNETCORE_URLS=http://+:8080
      - SOPHON__Tier=Personal
      - SOPHON__DataDirectory=/home/sophon/.sophon
      - SOPHON__Sandbox__HostWorkspacesPath=${SOPHON_DATA}/sandbox/workspaces
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/api/health"]
      interval: 5s
      timeout: 3s
      start_period: 15s
      retries: 5
    restart: unless-stopped

  sophon-dashboard:
    image: buildersoftdev/sophon-dashboard:latest
    ports:
      - "${DASHBOARD_PORT:-8080}:80"
    environment:
      - SOPHON_GATEWAY_URL=http://sophon-gateway:8080
    depends_on:
      sophon-gateway:
        condition: service_healthy
    restart: unless-stopped

Platform notes:

Windows/macOS: Docker Desktop handles socket permissions automatically. No extra configuration.
Linux: Add group_add: ["${DOCKER_GID:-999}"] to the gateway service and set DOCKER_GID to your Docker group ID (getent group docker | cut -d: -f3).

Pro Tier

Adds PostgreSQL 17 for multi-user auth and Qdrant for vector search.

docker-compose.pro.yml

services:
  sophon-gateway:
    image: buildersoftdev/sophon:latest
    ports:
      - "${GATEWAY_PORT:-8081}:8080"
    volumes:
      - ${SOPHON_DATA:?Set SOPHON_DATA in .env}:/home/sophon/.sophon
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - ASPNETCORE_URLS=http://+:8080
      - SOPHON__Tier=Pro
      - SOPHON__Database=postgresql
      - SOPHON__DataDirectory=/home/sophon/.sophon
      - SOPHON__Sandbox__HostWorkspacesPath=${SOPHON_DATA}/sandbox/workspaces
      - ConnectionStrings__PostgreSQL=Host=postgres;Database=sophon;Username=${POSTGRES_USER:-sophon};Password=${POSTGRES_PASSWORD:-sophon}
      - Qdrant__Endpoint=http://qdrant:6334
    depends_on:
      postgres:
        condition: service_healthy
      qdrant:
        condition: service_started
    restart: unless-stopped

  sophon-dashboard:
    image: buildersoftdev/sophon-dashboard:latest
    ports:
      - "${DASHBOARD_PORT:-8080}:80"
    environment:
      - SOPHON_GATEWAY_URL=http://sophon-gateway:8080
    depends_on:
      - sophon-gateway
    restart: unless-stopped

  postgres:
    image: postgres:17
    environment:
      POSTGRES_DB: sophon
      POSTGRES_USER: ${POSTGRES_USER:-sophon}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-sophon}
    volumes:
      - pgdata:/var/lib/postgresql/data
    ports:
      - "${POSTGRES_PORT:-5432}:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U sophon"]
      interval: 5s
      timeout: 3s
      retries: 5
    restart: unless-stopped

  qdrant:
    image: qdrant/qdrant:latest
    ports:
      - "${QDRANT_HTTP_PORT:-6333}:6333"
      - "${QDRANT_GRPC_PORT:-6334}:6334"
    volumes:
      - qdrantdata:/qdrant/storage
    restart: unless-stopped

volumes:
  pgdata:
  qdrantdata:

Generate a strong database password before deploying:

# Generate a random password
POSTGRES_PASSWORD=$(openssl rand -base64 24)
echo "POSTGRES_PASSWORD=$POSTGRES_PASSWORD" >> .env

Enterprise Tier

Adds Redis (caching), RabbitMQ (message bus), and optional HashiCorp Vault. Includes a dedicated bridge network for service isolation.

docker-compose.enterprise.yml

services:
  sophon-gateway:
    image: buildersoftdev/sophon:latest
    ports:
      - "${GATEWAY_PORT:-8081}:8080"
    volumes:
      - ${SOPHON_DATA:?Set SOPHON_DATA in .env}:/home/sophon/.sophon
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - ASPNETCORE_URLS=http://+:8080
      - SOPHON__Tier=Enterprise
      - SOPHON__Database=postgresql
      - SOPHON__DataDirectory=/home/sophon/.sophon
      - SOPHON__Sandbox__HostWorkspacesPath=${SOPHON_DATA}/sandbox/workspaces
      - ConnectionStrings__PostgreSQL=Host=postgres;Database=sophon;Username=${POSTGRES_USER:-sophon};Password=${POSTGRES_PASSWORD:-sophon}
      - Qdrant__Endpoint=http://qdrant:6334
      - Sophon__Redis__ConnectionString=redis:${REDIS_PORT:-6379},password=${REDIS_PASSWORD:-sophon}
      - Sophon__Vault__Provider=${VAULT_PROVIDER:-local}
      - Sophon__Vault__Address=${VAULT_ADDRESS:-http://vault:8200}
      - Sophon__Vault__Token=${VAULT_TOKEN:-}
      - Sophon__MessageBus__Provider=rabbitmq
      - Sophon__MessageBus__RabbitMqHost=rabbitmq://rabbitmq
      - Sophon__MessageBus__RabbitMqUsername=${RABBITMQ_USER:-sophon}
      - Sophon__MessageBus__RabbitMqPassword=${RABBITMQ_PASSWORD:-sophon}
      - Sophon__Jwt__Secret=${JWT_SECRET:-}
      - Sophon__Sso__Enabled=${SSO_ENABLED:-false}
    depends_on:
      postgres:
        condition: service_healthy
      rabbitmq:
        condition: service_healthy
      qdrant:
        condition: service_started
      redis:
        condition: service_healthy
    restart: unless-stopped
    networks:
      - sophon

  sophon-dashboard:
    image: buildersoftdev/sophon-dashboard:latest
    ports:
      - "${DASHBOARD_PORT:-8080}:80"
    environment:
      - SOPHON_GATEWAY_URL=http://sophon-gateway:8080
    depends_on:
      - sophon-gateway
    restart: unless-stopped
    networks:
      - sophon

  postgres:
    image: postgres:17-alpine
    environment:
      POSTGRES_DB: sophon
      POSTGRES_USER: ${POSTGRES_USER:-sophon}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-sophon}
    volumes:
      - pgdata:/var/lib/postgresql/data
    ports:
      - "${POSTGRES_PORT:-5432}:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-sophon}"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped
    networks:
      - sophon

  qdrant:
    image: qdrant/qdrant:latest
    ports:
      - "${QDRANT_HTTP_PORT:-6333}:6333"
      - "${QDRANT_GRPC_PORT:-6334}:6334"
    volumes:
      - qdrantdata:/qdrant/storage
    restart: unless-stopped
    networks:
      - sophon

  redis:
    image: redis:7-alpine
    command: redis-server --requirepass ${REDIS_PASSWORD:-sophon} --appendonly yes
    ports:
      - "${REDIS_PORT:-6379}:6379"
    volumes:
      - redisdata:/data
    healthcheck:
      test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD:-sophon}", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped
    networks:
      - sophon

  rabbitmq:
    image: rabbitmq:4.0-management-alpine
    environment:
      RABBITMQ_DEFAULT_USER: ${RABBITMQ_USER:-sophon}
      RABBITMQ_DEFAULT_PASS: ${RABBITMQ_PASSWORD:-sophon}
    ports:
      - "${RABBITMQ_PORT:-5672}:5672"
      - "${RABBITMQ_MGMT_PORT:-15672}:15672"
    volumes:
      - rabbitmqdata:/var/lib/rabbitmq
    healthcheck:
      test: ["CMD", "rabbitmq-diagnostics", "check_running", "-q"]
      interval: 10s
      timeout: 10s
      retries: 5
    restart: unless-stopped
    networks:
      - sophon

volumes:
  pgdata:
  qdrantdata:
  redisdata:
  rabbitmqdata:

networks:
  sophon:
    driver: bridge

Generate all credentials before deploying:

# Generate .env with random passwords
cat > .env << 'EOF'
SOPHON_DATA=/opt/sophon/data
POSTGRES_PASSWORD=$(openssl rand -base64 24)
REDIS_PASSWORD=$(openssl rand -base64 24)
RABBITMQ_PASSWORD=$(openssl rand -base64 24)
JWT_SECRET=$(openssl rand -base64 48)
EOF

Environment Setup

The `.env` file

All compose files read from a .env file in the same directory. At minimum, set SOPHON_DATA:

.env

# Required — absolute path to your Sophon data directory
SOPHON_DATA=/home/user/.sophon

# Pro/Enterprise — database credentials
POSTGRES_PASSWORD=your-strong-password

# Enterprise — additional services
REDIS_PASSWORD=your-strong-password
RABBITMQ_PASSWORD=your-strong-password
JWT_SECRET=your-jwt-signing-secret

Important:

Use absolute paths for SOPHON_DATA — Docker Compose does not expand ~
On Windows, use forward slashes: SOPHON_DATA=C:/Users/you/.sophon
On Linux, set DOCKER_GID to your Docker group ID for socket access

The SOPHON_DATA directory is created automatically on first run. It stores everything: configuration, agents, skills, documents, memory, and the SQLite database (Personal tier). See Configuration Reference for the full directory layout.

Docker Socket

Sophon's code execution sandbox uses the Docker API to create isolated containers. This requires mounting the Docker socket.

Why it's needed: The full sandbox (gVisor isolation, resource limits, network control) requires Docker API access. Without it, Sophon falls back to a process-based sandbox.

Platform differences:

Windows/macOS: Docker Desktop maps /var/run/docker.sock automatically. No extra configuration needed.
Linux: The socket is owned by the docker group. Add group_add: ["${DOCKER_GID}"] to the gateway service and set DOCKER_GID in your .env.

Skipping the socket: If you don't need code execution sandboxing, remove the Docker socket volume mount from the gateway service. Sophon will fall back to ProcessSandboxOrchestrator.

Verifying the Deployment

After starting, verify everything is running:

# Check container status
docker compose ps

# Health check
curl http://localhost:8081/api/health

# View gateway logs
docker compose logs sophon-gateway

Open http://localhost:8080 in your browser. On first run, the Setup Wizard will guide you through:

Adding your first LLM provider (Anthropic, OpenAI, Ollama, etc.)
Configuring your agent personality
Optionally connecting channels (Telegram, WhatsApp, etc.)

Next Steps

Configuration Reference — all environment variables and data directory layout
Platform Guides — Docker installation for Windows, macOS, Ubuntu, Fedora, Arch
SSL & Reverse Proxy — production HTTPS with Caddy, Nginx, or Traefik
Backup & Upgrade — data persistence, backup procedures, and upgrades