Skip to main content

​
Overview

switchAILocal provides official Docker images and a Docker Compose setup for easy deployment and production use.

​
Quick Start with Docker Compose

1

Clone Repository

git clone https://github.com/traylinx/switchAILocal.git
cd switchAILocal
2

Create Configuration

cp config.example.yaml config.yaml
Edit config.yaml to add your provider credentials and settings.
3

Start with Docker Compose

docker-compose up -d
Or use the hub script:
./ail.sh start --docker
4

Verify Deployment

curl http://localhost:18080/health

​
Docker Compose Configuration

The included docker-compose.yml provides a complete production-ready setup:
docker-compose.yml
services:
  switchailocal:
    image: ${SWITCH_AI_IMAGE:-traylinx/switchailocal:latest}
    pull_policy: always
    container_name: switchailocal
    environment:
      TZ: ${TZ:-UTC}
      REMOTE_COMMAND_HOST: ${REMOTE_COMMAND_HOST:-http://host.docker.internal:18888}
    extra_hosts:
      - "host.docker.internal:host-gateway"
    ports:
      - "18080:18080"
    volumes:
      - ./config.yaml:/app/config.yaml
      - ${HOME}/.switchailocal:/home/appuser/.switchailocal
      - ./logs:/app/logs
      - ./plugins:/app/plugins
    restart: unless-stopped
Environment Variables:
  • TZ: Timezone for logs and timestamps (default: UTC)
  • REMOTE_COMMAND_HOST: Host for remote command execution
  • SWITCH_AI_IMAGE: Docker image to use (default: traylinx/switchailocal:latest)
Volumes:
  • ./config.yaml: Main configuration file
  • ~/.switchailocal: OAuth tokens and authentication data
  • ./logs: Application logs (when file logging is enabled)
  • ./plugins: Custom LUA plugins and Cortex Router skills

​
Building from Source

Build your own Docker image from source:
1

Build with Docker Compose

docker-compose build
Or with version metadata:
VERSION=1.0.0 COMMIT=$(git rev-parse HEAD) BUILD_DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ") \
  docker-compose build
2

Run Custom Build

docker-compose up -d

​
Build Arguments

The Dockerfile supports these build arguments:
Dockerfile
ARG VERSION=dev
ARG COMMIT=none
ARG BUILD_DATE=unknown

RUN CGO_ENABLED=0 GOOS=linux go build \
  -ldflags="-s -w \
    -X 'main.Version=${VERSION}' \
    -X 'main.Commit=${COMMIT}' \
    -X 'main.BuildDate=${BUILD_DATE}'" \
  -o ./switchAILocal ./cmd/server/

​
Dockerfile Architecture

The official Dockerfile uses a multi-stage build for optimal image size: 
# Build stage
FROM golang:1.25-alpine AS builder

WORKDIR /app

COPY go.mod go.sum ./
RUN go mod download

COPY . .

ARG VERSION=dev
ARG COMMIT=none
ARG BUILD_DATE=unknown

RUN CGO_ENABLED=0 GOOS=linux go build \
  -ldflags="-s -w \
    -X 'main.Version=${VERSION}' \
    -X 'main.Commit=${COMMIT}' \
    -X 'main.BuildDate=${BUILD_DATE}'" \
  -o ./switchAILocal ./cmd/server/
The image includes Node.js and npm to support the Gemini CLI tool for CLI-based authentication.

​
Using Pre-built Images

​
Docker Hub

Pull the latest official image: 
docker pull traylinx/switchailocal:latest
Run directly: 
docker run -d \
  -p 18080:18080 \
  -v $(pwd)/config.yaml:/app/config.yaml \
  -v ~/.switchailocal:/home/appuser/.switchailocal \
  --name switchailocal \
  traylinx/switchailocal:latest

​
Version Tags

Available image tags:
  • latest: Most recent stable release
  • vX.Y.Z: Specific version (e.g., v1.0.0)
  • dev: Development builds from main branch

​
Volume Management

​
Configuration Volume

Mount your config.yaml into the container: 
-v $(pwd)/config.yaml:/app/config.yaml

​
Authentication Data

Persist OAuth tokens and session data: 
-v ~/.switchailocal:/home/appuser/.switchailocal

​
Logs

When file logging is enabled, mount a logs directory:
config.yaml
logging-to-file: true
logs-max-total-size-mb: 500

-v $(pwd)/logs:/app/logs

​
Plugins

Mount custom plugins and skills: 
-v $(pwd)/plugins:/app/plugins

​
Environment Variables

​
Timezone

Set the container timezone:
docker-compose.yml
environment:
  TZ: America/New_York

​
Remote Command Host

For distributed deployments with remote command execution:
docker-compose.yml
environment:
  REMOTE_COMMAND_HOST: http://command-service:18888

​
Networking

​
Host Network Access

The Docker Compose configuration includes host.docker.internal mapping for accessing services on the host machine:
docker-compose.yml
extra_hosts:
  - "host.docker.internal:host-gateway"
This allows the container to connect to:
  • Ollama running on host: http://host.docker.internal:11434
  • LM Studio on host: http://host.docker.internal:1234
  • Other local services

​
Custom Networks

For advanced deployments, create a custom network:
docker-compose.yml
networks:
  switchai:
    driver: bridge

services:
  switchailocal:
    networks:
      - switchai

​
Health Checks

Add a Docker health check:
docker-compose.yml
services:
  switchailocal:
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:18080/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

​
Resource Limits

Set resource constraints for production:
docker-compose.yml
services:
  switchailocal:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          cpus: '0.5'
          memory: 512M

​
Updating

1

Pull Latest Image

docker-compose pull
2

Restart Services

docker-compose up -d
3

Verify Update

docker logs switchailocal

​
Troubleshooting

​
View Logs

docker-compose logs -f switchailocal

​
Check Container Status

docker-compose ps

​
Restart Container

docker-compose restart switchailocal

​
Execute Commands Inside Container

docker exec -it switchailocal sh

​
Permission Issues

If you encounter permission errors with mounted volumes: 
# Fix ownership
sudo chown -R 1000:1000 ~/.switchailocal
sudo chown -R 1000:1000 ./logs

​
Production Considerations

  • Always use TLS in production (tls.enable: true in config.yaml)
  • Store API keys securely (use Docker secrets or environment variables)
  • Restrict management API access (remote-management.allow-remote: false)
  • Use strong api-keys and secret-key values
  • Enable usage statistics for monitoring (usage-statistics-enabled: true)
  • Configure appropriate request-retry values
  • Use streaming.keepalive-seconds for long-running connections
  • Set logs-max-total-size-mb to prevent disk exhaustion
  • Monitor container health with docker-compose ps
  • Check logs regularly with docker-compose logs
  • Use the Management Dashboard at http://localhost:18080/management
  • Set up alerts for provider failures using hooks

​
Next Steps

Management Dashboard

Configure providers and monitor performance through the web UI

Troubleshooting

Resolve common deployment and runtime issues