Skip to main content
Run AeonSage in Docker for easy deployment and isolation.

Quick Start

Using Docker Run

# Pull the image
docker pull aeonsage/gateway:latest

# Run the container
docker run -d \
  --name aeonsage-gateway \
  -p 18789:18789 \
  -v aeonsage-data:/root/.aeonsage \
  -e OPENAI_API_KEY=your-key-here \
  aeonsage/gateway:latest

Using Docker Compose

Create docker-compose.yml:
version: '3.8'

services:
  aeonsage:
    image: aeonsage/gateway:latest
    container_name: aeonsage-gateway
    restart: unless-stopped
    ports:
      - "18789:18789"
    volumes:
      - ./config:/root/.aeonsage
      - ./skills:/root/.aeonsage/skills
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - GATEWAY_TOKEN=${GATEWAY_TOKEN}
      - LOG_LEVEL=info
Start:
docker-compose up -d

Configuration

Environment Variables

VariableDescriptionDefault
GATEWAY_TOKENAdmin token(required)
OPENAI_API_KEYOpenAI API key-
ANTHROPIC_API_KEYAnthropic API key-
LOG_LEVELLog verbosityinfo
GATEWAY_HOSTBind address0.0.0.0
GATEWAY_PORTListen port18789

Volume Mounts

Mount PointDescription
/root/.aeonsageConfiguration and data
/root/.aeonsage/skillsCustom skills

Example with All Options

version: '3.8'

services:
  aeonsage:
    image: aeonsage/gateway:latest
    container_name: aeonsage-gateway
    restart: unless-stopped
    ports:
      - "18789:18789"
    volumes:
      - ./config:/root/.aeonsage
      - ./skills:/root/.aeonsage/skills
      - ./logs:/var/log/aeonsage
    environment:
      - GATEWAY_TOKEN=your-secure-token
      - OPENAI_API_KEY=sk-your-key
      - ANTHROPIC_API_KEY=sk-ant-your-key
      - LOG_LEVEL=debug
      - GATEWAY_HOST=0.0.0.0
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:18789/health"]
      interval: 30s
      timeout: 10s
      retries: 3

With Ollama

Run AeonSage with local Ollama:
version: '3.8'

services:
  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    restart: unless-stopped
    ports:
      - "11434:11434"
    volumes:
      - ollama-data:/root/.ollama
    
  aeonsage:
    image: aeonsage/gateway:latest
    container_name: aeonsage-gateway
    restart: unless-stopped
    ports:
      - "18789:18789"
    volumes:
      - ./config:/root/.aeonsage
    environment:
      - GATEWAY_TOKEN=your-token
      - OLLAMA_HOST=http://ollama:11434
    depends_on:
      - ollama

volumes:
  ollama-data:
For GPU acceleration with Ollama, add GPU configuration to the ollama service. See Ollama Docker docs.

With PostgreSQL

For production multi-user deployments:
version: '3.8'

services:
  postgres:
    image: postgres:15-alpine
    container_name: aeonsage-postgres
    restart: unless-stopped
    environment:
      - POSTGRES_USER=aeonsage
      - POSTGRES_PASSWORD=secure-password
      - POSTGRES_DB=aeonsage
    volumes:
      - postgres-data:/var/lib/postgresql/data
    
  aeonsage:
    image: aeonsage/gateway:latest
    container_name: aeonsage-gateway
    restart: unless-stopped
    ports:
      - "18789:18789"
    environment:
      - GATEWAY_TOKEN=your-token
      - DATABASE_URL=postgresql://aeonsage:secure-password@postgres:5432/aeonsage
    depends_on:
      - postgres

volumes:
  postgres-data:

With Reverse Proxy

Nginx

version: '3.8'

services:
  nginx:
    image: nginx:alpine
    container_name: aeonsage-nginx
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./certs:/etc/nginx/certs:ro
    depends_on:
      - aeonsage
  
  aeonsage:
    image: aeonsage/gateway:latest
    container_name: aeonsage-gateway
    restart: unless-stopped
    expose:
      - "18789"
    environment:
      - GATEWAY_TOKEN=your-token

Caddy (Automatic HTTPS)

version: '3.8'

services:
  caddy:
    image: caddy:2
    container_name: aeonsage-caddy
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy-data:/data
    depends_on:
      - aeonsage
  
  aeonsage:
    image: aeonsage/gateway:latest
    container_name: aeonsage-gateway
    restart: unless-stopped
    expose:
      - "18789"
    environment:
      - GATEWAY_TOKEN=your-token

Health Checks

# Check container health
docker ps

# View health check logs
docker inspect --format='{{json .State.Health}}' aeonsage-gateway | jq

# Manual health check
docker exec aeonsage-gateway curl -f http://localhost:18789/health

Logs

# View logs
docker logs aeonsage-gateway

# Follow logs
docker logs -f aeonsage-gateway

# View last 100 lines
docker logs --tail 100 aeonsage-gateway

Updates

# Pull latest image
docker pull aeonsage/gateway:latest

# Restart with new image
docker-compose down
docker-compose up -d

Troubleshooting


Next Steps

Your Docker deployment is now running. For production environments, consider implementing monitoring and alerting to track system health, resource usage, and performance metrics. For large-scale deployments requiring high availability and auto-scaling, Kubernetes provides advanced orchestration capabilities.