Installation

This guide covers all installation methods for switchAILocal, from quick local setup to production Docker deployments.

Prerequisites

Required

Go 1.24+ - Download
Git - For cloning the repository
Terminal/Shell - Command line access

Optional

Docker - For containerized deployment
Node.js 18+ - For building the Management UI
CLI Tools - gemini, claude, vibe for zero-config providers

Installation Methods

Local (Hub Script)
Manual Build
Docker

Using ail.sh (Recommended)

The unified operations hub script handles building, dependencies, and lifecycle management automatically.

Clone Repository

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

Check Dependencies

Verify Go and Docker are installed:

./ail.sh check

Expected output:

[INFO] Running pre-flight checks...
[OK]   Go detected: 1.24.0
[OK]   Docker detected.
[OK]   All systems go.

macOS users: Run ./ail.sh install to auto-install missing dependencies via Homebrew.

Start Server

Build and start in one command:

./ail.sh start

The script will:

Create .ail state directory
Build the switchAILocal binary
Start the server in background
Save PID to .ail/local.pid
Write logs to server.log

./ail.sh start -f
# Builds, starts, and follows logs

Verify Installation

Check server status:

./ail.sh status

Test the API:

curl http://localhost:18080/v1/models \
  -H "Authorization: Bearer sk-test-123"

Hub Script Commands

start

command

Build and start the serverOptions:

-d, --docker - Use Docker runtime
-b, --build - Force rebuild (Docker only)
-f, --follow - Follow logs after starting

./ail.sh start -f
./ail.sh start --docker --build

stop

command

Stop the running server

./ail.sh stop
./ail.sh stop --docker

restart

command

Restart the server (stop + start)

./ail.sh restart

status

command

Show status of all instances (local, Docker, bridge)

./ail.sh status

logs

command

View server logsOptions:

-f, --follow - Follow log output

./ail.sh logs        # Last 50 lines
./ail.sh logs -f     # Follow logs

check

command

Verify dependencies (Go, Docker)

./ail.sh check

install

command

Auto-install dependencies (macOS only, requires Homebrew)

./ail.sh install

bridge

command

Manage the bridge agent (for advanced integrations)

./ail.sh bridge start
./ail.sh bridge stop
./ail.sh bridge status

Build from Source

For users who prefer manual control or are on non-standard systems.

Clone and Navigate

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

Download Dependencies

go mod download

Build Binary

go build -o switchAILocal ./cmd/server

For production builds with version information:

VERSION=$(git describe --tags --always)
COMMIT=$(git rev-parse --short HEAD)
BUILD_DATE=$(date -u +%Y-%m-%dT%H:%M:%SZ)

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

Verify Build

./switchAILocal --version

Create Configuration

cp config.example.yaml config.yaml

Edit config.yaml with your provider credentials (see Configuration Guide).

Run Server

./switchAILocal

The server starts on http://localhost:18080 by default.

Custom Build Options

# Smaller binary, no debug symbols
go build -ldflags="-s -w" -o switchAILocal ./cmd/server

Docker Installation

Run switchAILocal in an isolated container with all dependencies included.

Clone Repository

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

Choose Installation Method

docker-build.sh
Docker Compose
Manual Commands

Use the interactive setup script:

./docker-build.sh

You’ll see:

=================================================
  switchAILocal - Docker Build & Run
=================================================

1) Pre-built image (traylinx/switchailocal:latest)
2) Build from source (local Dockerfile)
3) Exit

Select option: 

Option 1: Pull pre-built image from Docker Hub (fastest)
Option 2: Build from source (recommended for development)

Use Docker Compose for production deployments:

# Start in detached mode
docker compose up -d

# Start with rebuild
docker compose up -d --build

# View logs
docker compose logs -f

# Stop services
docker compose down

Build and run manually:

# Build image
docker build -t switchailocal:latest .

# Run container
docker run -d \
  --name switchailocal \
  -p 18080:18080 \
  -v $(pwd)/config.yaml:/app/config.yaml \
  -v ~/.switchailocal:/home/appuser/.switchailocal \
  -v $(pwd)/logs:/app/logs \
  switchailocal:latest

Configure Volumes

The Docker setup mounts these directories:

Host Path	Container Path	Purpose
`./config.yaml`	`/app/config.yaml`	Server configuration
`~/.switchailocal`	`/home/appuser/.switchailocal`	Auth credentials & tokens
`./logs`	`/app/logs`	Server logs
`./plugins`	`/app/plugins`	LUA plugins & Cortex Router skills

Ensure config.yaml exists before starting Docker. Copy from config.example.yaml if needed.

Verify Container

# Check container status
docker ps | grep switchailocal

# View logs
docker logs -f switchailocal

# Test API
curl http://localhost:18080/v1/models \
  -H "Authorization: Bearer sk-test-123"

Docker Environment Variables

string

default:"UTC"

Container timezone

environment:
  TZ: "America/New_York"

REMOTE_COMMAND_HOST

string

default:"http://host.docker.internal:18888"

Bridge agent connection URL (advanced)

environment:
  REMOTE_COMMAND_HOST: "http://192.168.1.100:18888"

SWITCH_AI_IMAGE

string

default:"traylinx/switchailocal:latest"

Docker image to use

SWITCH_AI_IMAGE=switchailocal:dev docker compose up -d

Dockerfile Overview

The official Dockerfile includes:

Alpine Linux base image (minimal footprint)
Go 1.25 build environment
Node.js & npm for CLI tool support
@google/gemini-cli pre-installed
Non-root user for security
TLS certificates for HTTPS providers

Building the Management UI

The optional web dashboard provides a modern interface for configuration and monitoring.

Install Node.js

Requires Node.js 18+ and npm:

node --version  # Should be v18.0.0 or higher
npm --version

Build UI

Run the build script:

./ail_ui.sh

This script:

Navigates to frontend/
Installs dependencies (npm install)
Builds React app (npm run build)
Inlines all assets (CSS, JS, SVGs)
Outputs single-file static/management.html (~226 KB)

Verify Build

ls -lh static/management.html
# Should show ~226 KB file

Access Dashboard

Start the server and visit:

http://localhost:18080/management

The Management UI requires a secret key. See Management Dashboard for setup.

Post-Installation Configuration

Copy Configuration Template

cp config.example.yaml config.yaml

Add Your Provider Credentials

Edit config.yaml and add API keys or enable local providers:

Cloud APIs

gemini-api-key:
  - api-key: "AIzaSy...YOUR_KEY_HERE"

claude-api-key:
  - api-key: "sk-ant-...YOUR_KEY_HERE"

codex-api-key:
  - api-key: "sk-...YOUR_KEY_HERE"

Local Models

ollama:
  enabled: true
  base-url: "http://localhost:11434"
  auto-discover: true

lmstudio:
  enabled: true
  base-url: "http://localhost:1234/v1"
  auto-discover: true

CLI Wrappers

# No configuration needed!
# Install CLI tools and switchAILocal detects them automatically:
# - npm install -g @google/gemini-cli
# - brew install anthropic/tap/claude
# - npm install -g @mistralai/vibe

Set Authentication Keys

Update the API keys that clients use to authenticate to your switchAILocal server:

api-keys:
  - "your-secure-key-here"
  - "another-key-for-team"

Replace the default sk-test-123 key before deploying to production.

Restart Server

Apply configuration changes:

./ail.sh restart

Verification Tests

Health Check
List Models
Chat Completion

curl http://localhost:18080/health

Expected response:

{"status": "ok"}

curl http://localhost:18080/v1/models \
  -H "Authorization: Bearer sk-test-123"

Expected response:

{
  "object": "list",
  "data": [
    {
      "id": "geminicli:gemini-2.5-pro",
      "object": "model",
      "owned_by": "google"
    },
    {
      "id": "ollama:llama3.2",
      "object": "model",
      "owned_by": "ollama"
    }
  ]
}

curl http://localhost:18080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-test-123" \
  -d '{
    "model": "gemini-2.5-pro",
    "messages": [{"role": "user", "content": "Say hello"}]
  }'

Expected response:

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "gemini-2.5-pro",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Hello! How can I help you today?"
    },
    "finish_reason": "stop"
  }]
}

Troubleshooting

Go version too old

Error: go: directive requires go version >= 1.24Solution:

# Check current version
go version

# Update Go
# macOS
brew upgrade go

# Linux
wget https://go.dev/dl/go1.24.0.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.24.0.linux-amd64.tar.gz

Port 18080 already in use

Error: bind: address already in useSolution:

# Find process using port
lsof -i :18080

# Kill existing process
kill -9 <PID>

# OR change port in config.yaml
port: 18081

Docker build fails

Error: error building imageSolution:

# Clean Docker cache
docker system prune -a

# Rebuild without cache
docker build --no-cache -t switchailocal .

# Check disk space
df -h

Config file not found

Error: config.yaml not foundSolution:

# Create from template
cp config.example.yaml config.yaml

# Verify file exists
ls -la config.yaml

# Check working directory
pwd  # Should be in switchAILocal root

Module download fails

Error: go: error loading module requirementsSolution:

# Clean module cache
go clean -modcache

# Tidy dependencies
go mod tidy

# Re-download
go mod download

# Verify go.sum
go mod verify

Get Started

Core Concepts

Configuration

Intelligent Systems

Advanced Features

Guides

Prerequisites

Required

Optional

Installation Methods

Using ail.sh (Recommended)

Hub Script Commands

Build from Source

Custom Build Options

Docker Installation

Docker Environment Variables

Dockerfile Overview

Building the Management UI

Post-Installation Configuration

Verification Tests

Troubleshooting

System Requirements

Minimum

Recommended

Next Steps

Configure Providers

Quickstart Guide

Configuration

Get Started

Core Concepts

Configuration

Intelligent Systems

Advanced Features

Guides

​Prerequisites

Required

Optional

​Installation Methods

​Using ail.sh (Recommended)

​Hub Script Commands

​Build from Source

​Custom Build Options

​Docker Installation

​Docker Environment Variables

​Dockerfile Overview

​Building the Management UI

​Post-Installation Configuration

​Verification Tests

​Troubleshooting

​System Requirements

Minimum

Recommended

​Next Steps

Configure Providers

Quickstart Guide

Configuration

Prerequisites

Installation Methods

Using ail.sh (Recommended)

Hub Script Commands

Build from Source

Custom Build Options

Docker Installation

Docker Environment Variables

Dockerfile Overview

Building the Management UI

Post-Installation Configuration

Verification Tests

Troubleshooting

System Requirements

Next Steps