Docker Deployment

Run Sinaptic® DROID+ in production with Docker. The official image is minimal (<15MB), runs as non-root, and includes a built-in healthcheck.

Images

Registry	Image	Pull command
Docker Hub (primary)	sinapticai/droid	docker pull sinapticai/droid:latest
GHCR (mirror)	ghcr.io/sinapticai/droid	docker pull ghcr.io/sinapticai/droid:latest

Tags: latest, 0.5.0, 0.5, 0 (semver), plus sha-<commit> for pinning.

Quick Start

docker run -d \
  --name droid \
  -p 8080:8080 \
  -p 8081:8081 \
  -v ./droid.yaml:/etc/droid/droid.yaml \
  -v ./configs/agents:/etc/droid/agents \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  sinapticai/droid

This starts Sinaptic® DROID+ with:

• Port 8080: OpenAI-compatible API
• Port 8081: Management API + Agent Builder UI
• Your local config and agent files mounted into the container
• API key passed via environment variable

Configuration

The container expects two paths:

Path	Purpose	Default
/etc/droid/droid.yaml	Runtime config	Required (mount your own)
/var/lib/droid	Data directory (RAG, logs, audit)	Created automatically

Override the config path with DROID_CONFIG and the data directory with DROID_DATA_DIR environment variables.

Environment Variables

Pass API keys and overrides via environment variables. The config file supports ${VAR} syntax:

docker run -d \
  -e OPENAI_API_KEY=sk-... \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -e GEMINI_API_KEY=AIza... \
  -e GROK_API_KEY=xai-... \
  sinapticai/droid

Docker Compose

For production deployments, use Docker Compose:

# docker-compose.yml
version: "3.8"

services:
  droid:
    image: sinapticai/droid:latest
    ports:
      - "8080:8080"   # OpenAI-compatible API
      - "8081:8081"   # Management API + Builder UI
    volumes:
      - ./droid.yaml:/etc/droid/droid.yaml:ro
      - ./configs/agents:/etc/droid/agents:ro
      - droid-data:/var/lib/droid
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:-}
    restart: unless-stopped
    healthcheck:
      test: ["/usr/local/bin/droid", "health", "--openai-port", "8080"]
      interval: 30s
      timeout: 3s
      start_period: 5s
      retries: 3

volumes:
  droid-data:

Start:

docker compose up -d

Health Checks

The container includes a built-in healthcheck that runs droid health every 30 seconds. You can also check health manually:

# From outside the container
curl http://localhost:8081/health

# Docker inspect
docker inspect --format='{{.State.Health.Status}}' droid

Production Recommendations

Volumes

Mount your config as read-only (:ro) and use a named volume for data:

-v ./droid.yaml:/etc/droid/droid.yaml:ro
-v ./configs/agents:/etc/droid/agents:ro
-v droid-data:/var/lib/droid

Security

The container runs as non-root by default (distroless image). For additional security:

• Don't expose port 8081 publicly — the Management API and Builder UI are for internal use
• Use Docker secrets or a vault for API keys instead of environment variables
• Enable SinapticAI in block mode for all production agents

# Only expose the API port externally
ports:
  - "8080:8080"
# Keep 8081 on internal network only

Resource Limits

Sinaptic® DROID+ itself is lightweight, but LLM responses can consume memory during streaming. Recommended minimums:

deploy:
  resources:
    limits:
      memory: 512M
      cpus: "1.0"
    reservations:
      memory: 128M
      cpus: "0.25"

Logging

Sinaptic® DROID+ outputs structured JSON logs to stdout by default. Capture with your preferred log aggregator:

logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "3"

Networking

If running multiple Sinaptic® DROID+ instances or connecting to local LLMs (Ollama, LM Studio):

services:
  droid:
    # ... droid config ...
    networks:
      - droid-net

  ollama:
    image: ollama/ollama:latest
    networks:
      - droid-net

networks:
  droid-net:
    driver: bridge

Then reference Ollama by service name in droid.yaml:

ollama:
  base_url: "http://ollama:11434/v1"

Updating

docker pull sinapticai/droid:latest
docker compose up -d

The container is stateless — all configuration is in mounted files and all data is in the volume. You can safely replace the container at any time.

Building from Source

If you prefer to build the Docker image yourself:

git clone https://github.com/SinapticAI/droid-community.git
cd droid-community
docker build -t droid:local .

Troubleshooting

Container exits immediately: Check logs with docker logs droid. Most common cause: missing or invalid droid.yaml.

Health check failing: Ensure port 8080 is accessible inside the container and the config file is valid YAML.

Can't connect to local LLM: If Ollama or LM Studio runs on the host, use host.docker.internal instead of localhost:

ollama:
  base_url: "http://host.docker.internal:11434/v1"

Permission denied on volumes: The container runs as non-root. Ensure mounted directories are readable by UID 65534 (nobody).