Skip to main content

Documentation Index

Fetch the complete documentation index at: https://ail.traylinx.com/llms.txt

Use this file to discover all available pages before exploring further.

Get switchAILocal up and running with your first AI request in minutes. This guide will help you install, configure, and test your unified AI gateway.

​
What You’ll Build

By the end of this guide, you’ll have:
  • switchAILocal server running on http://localhost:18080
  • At least one AI provider configured (CLI, API, or local)
  • Made your first successful API request
1
Clone the Repository
2
Get the latest version of switchAILocal:
3
git clone https://github.com/traylinx/switchAILocal.git
cd switchAILocal
4
Start the Server
5
Use the unified hub script to start switchAILocal. It automatically builds and runs the server:
6
Local (Recommended)
./ail.sh start
Docker
./ail.sh start --docker --build
Local with Logs
./ail.sh start -f
7
The server will start on http://localhost:18080 by default.
8
First time running? The hub script will automatically check for Go dependencies and build the binary for you.
9
Choose Your Provider
10
Select one of three authentication methods to connect AI providers:
11
CLI Wrappers (Zero Setup)
# If you have gemini, claude, or vibe CLI tools installed,
# switchAILocal uses them automatically - no configuration needed!

# Just use the CLI prefix in your requests:
curl http://localhost:18080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-test-123" \
  -d '{
    "model": "geminicli:gemini-2.5-pro",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
API Keys
# Add API keys to config.yaml
cp config.example.yaml config.yaml

# Edit config.yaml:
gemini-api-key:
  - api-key: "AIzaSy..."

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

codex-api-key:
  - api-key: "sk-..."
Local Models
# Enable Ollama or LM Studio in config.yaml
ollama:
  enabled: true
  base-url: "http://localhost:11434"
  auto-discover: true

lmstudio:
  enabled: true
  base-url: "http://localhost:1234/v1"
  auto-discover: true
12
The default API key sk-test-123 is for testing only. Update api-keys in config.yaml for production use.
13
Make Your First Request
14
Test your setup with a simple API call:
15
cURL
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": "What is the meaning of life?"}
    ]
  }'
Python
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:18080/v1",
    api_key="sk-test-123"
)

response = client.chat.completions.create(
    model="gemini-2.5-pro",
    messages=[
        {"role": "user", "content": "What is the meaning of life?"}
    ]
)

print(response.choices[0].message.content)
JavaScript
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'http://localhost:18080/v1',
  apiKey: 'sk-test-123'
});

const response = await client.chat.completions.create({
  model: 'gemini-2.5-pro',
  messages: [
    { role: 'user', content: 'What is the meaning of life?' }
  ]
});

console.log(response.choices[0].message.content);
16
Verify Server Status
17
Check that everything is running smoothly:
18
./ail.sh status
19
Expected output:
20
--- Local Status ---
[OK]   Running (PID 12345)

--- Docker Status ---
Not running locally.

Bridge: Not running.

​
Next Steps

Configure Providers

Set up multiple AI providers and accounts for load balancing

API Reference

Explore the full OpenAI-compatible API

Intelligent Routing

Enable Cortex Router for automatic model selection

Management Dashboard

Use the web UI to configure and monitor your gateway

​
Quick Tips

Use the provider:model format to route to a specific provider:
# Force Gemini CLI
model="geminicli:gemini-2.5-pro"

# Force Ollama
model="ollama:llama3.2"

# Force Claude API
model="claude:claude-sonnet-4"
Without a prefix, switchAILocal auto-routes to any available provider.
Add "stream": true to your request:
stream = client.chat.completions.create(
    model="gemini-2.5-pro",
    messages=[{"role": "user", "content": "Tell me a story"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
Query the /v1/models endpoint:
curl http://localhost:18080/v1/models \
  -H "Authorization: Bearer sk-test-123"
This returns all models from all configured providers.
Run diagnostics:
# Check dependencies
./ail.sh check

# View logs
./ail.sh logs -f

# Verify Go installation
go version  # Should be 1.24+

​
Troubleshooting

Connection Refused

Problem: curl: (7) Failed to connectSolution:
  • Check if server is running: ./ail.sh status
  • Verify port 18080 is not in use: lsof -i :18080
  • Review logs: ./ail.sh logs

401 Unauthorized

Problem: API key rejectedSolution:
  • Ensure your API key matches one in config.yaml: 
    api-keys:
  - "sk-test-123"
  • Restart server after config changes: ./ail.sh restart

No Models Available

Problem: Empty models list or “model not found”Solution:
  • Verify provider is enabled in config.yaml
  • Check CLI tools are installed: which gemini claude
  • Enable auto-discovery for local providers: 
    ollama:
  enabled: true
  auto-discover: true

Build Failed

Problem: Go build errorsSolution:
  • Update Go to 1.24+: go version
  • Clean modules: go clean -modcache
  • Re-download dependencies: go mod download
Need more help? Check the Installation Guide for detailed setup instructions or visit our GitHub Issues.