Skip to main content

​
Overview

switchAILocal supports multiple AI providers through three authentication methods. Choose the method that works best for your use case.

​
Authentication Methods

Most users should start with CLI Wrappers (Option A) for the fastest setup with zero configuration.
If you already have gemini, claude, codex, or vibe CLI tools installed and authenticated, switchAILocal uses them automatically.
1

Verify CLI Installation

Check that your CLI tools are installed and working:
gemini --version
claude --version
codex --version
2

Use CLI Prefix

Reference the CLI provider using the cli suffix in your model name:
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!"}]
  }'
3

Supported Providers

Available CLI providers:
ProviderCLI ToolPrefixExample Model
Google Geminigeminigeminicli:geminicli:gemini-2.5-pro
Anthropic Claudeclaudeclaudecli:claudecli:claude-sonnet-4
OpenAI Codexcodexcodex:codex:gpt-4
Mistral Vibevibevibe:vibe:mistral-large
OpenCodeopencodeopencode:opencode:build

​
Option B: API Keys (Standard)

For cloud API providers, add API keys directly to your config.yaml.
1

Copy Example Config

cp config.example.yaml config.yaml
2

Add Provider Credentials

Edit config.yaml and add your API keys:
gemini-api-key:
  - api-key: "AIzaSy..."
    prefix: "google"
    base-url: "https://generativelanguage.googleapis.com"
3

Use Without CLI Suffix

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

​
Option C: OAuth Login (Advanced)

For users who want switchAILocal to manage OAuth tokens directly without CLI tools.
This method requires GEMINI_CLIENT_ID and GEMINI_CLIENT_SECRET environment variables. Most users should use Option A or Option B instead.
1

Set Environment Variables

export GEMINI_CLIENT_ID="your-client-id"
export GEMINI_CLIENT_SECRET="your-client-secret"
2

Run OAuth Login

./switchAILocal --login
3

Complete Browser Authentication

A browser window will open for you to authorize switchAILocal. After approval, tokens are stored in ~/.switchailocal/.

​
Local Model Providers

​
Ollama

Connect to locally running Ollama models.
1

Enable Ollama in Config

config.yaml
ollama:
  enabled: true
  base-url: "http://localhost:11434"
  auto-discover: true  # Automatically fetch available models
2

Start Ollama

ollama serve
3

Pull Models

ollama pull llama3.2
ollama pull qwen:0.5b
4

Use Ollama Models

curl http://localhost:18080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-test-123" \
  -d '{"model": "ollama:llama3.2", "messages": [...]}'

​
LM Studio

Connect to LM Studio for local model hosting.
config.yaml
lmstudio:
  enabled: true
  base-url: "http://localhost:1234/v1"
  auto-discover: true

​
OpenCode

Integrate with OpenCode for specialized development tasks.
config.yaml
opencode:
  enabled: true
  base-url: "http://localhost:4096"
  default-agent: "build"

​
OpenAI-Compatible Providers

Connect any OpenAI-compatible API endpoint.
config.yaml
openai-compatibility:
  - name: "groq"
    prefix: "groq"
    base-url: "https://api.groq.com/openai/v1"
    api-key-entries:
      - api-key: "gsk_..."
  
  - name: "openrouter"
    prefix: "or"
    base-url: "https://openrouter.ai/api/v1"
    api-key-entries:
      - api-key: "sk-or-v1-..."

​
Load Balancing

Configure multiple credentials per provider for automatic load balancing.
config.yaml
gemini-api-key:
  - api-key: "AIzaSy...account1"
  - api-key: "AIzaSy...account2"
  - api-key: "AIzaSy...account3"

routing:
  strategy: "round-robin"  # or "fill-first"
  • round-robin: Distributes requests evenly across all credentials
  • fill-first: Uses the first credential until quota is exhausted, then moves to the next

​
Model Aliasing

Create friendly aliases for frequently used models.
config.yaml
switchai-api-key:
  - api-key: "sk-lf-..."
    models:
      - name: "openai/gpt-oss-120b"
        alias: "fast"
      - name: "deepseek-reasoner"
        alias: "reasoner"
Use aliases in requests: 
curl http://localhost:18080/v1/chat/completions \
  -d '{"model": "fast", "messages": [...]}'

​
Verification

List all available models to verify provider setup: 
curl http://localhost:18080/v1/models \
  -H "Authorization: Bearer sk-test-123"
Check provider health status: 
curl http://localhost:18080/v0/management/heartbeat/status \
  -H "X-Management-Key: your-secret-key"

​
Next Steps

Docker Deployment

Deploy switchAILocal with Docker for production use

Management Dashboard

Use the web UI to configure providers visually