Skip to main content

​
Basic Server Settings

​
Host and Port

Control which network interface and port the server binds to:
config.yaml
host: ""        # Bind all interfaces (default)
port: 18080      # Server port (default: 18080)
​
host
string
default:""
Network interface to bind. Empty string binds all interfaces (IPv4 + IPv6). Use "127.0.0.1" or "localhost" to restrict to local-only access.
​
port
integer
default:"18080"
TCP port for the HTTP/HTTPS server.
Examples: 
# Local development (localhost only)
host: "127.0.0.1"
port: 18080

# Production (all interfaces)
host: ""
port: 443  # Requires TLS

​
TLS Configuration

Enable HTTPS with TLS certificates:
config.yaml
tls:
  enable: false
  cert: ""
  key: ""
​
tls.enable
boolean
default:"false"
Enable HTTPS mode. When true, server listens with TLS.
​
tls.cert
string
Path to TLS certificate file (PEM format). Required when TLS is enabled.
​
tls.key
string
Path to TLS private key file (PEM format). Required when TLS is enabled.
Example with Let’s Encrypt: 
tls:
  enable: true
  cert: "/etc/letsencrypt/live/yourdomain.com/fullchain.pem"
  key: "/etc/letsencrypt/live/yourdomain.com/privkey.pem"
Changing TLS settings requires a server restart. Hot reload does not apply to certificate paths.

​
Authentication Directory

Specify where authentication tokens and session data are stored:
config.yaml
auth-dir: "~/.switchailocal"
​
auth-dir
string
default:"~/.switchailocal"
Directory for authentication token files and session data. Supports ~ for home directory expansion.
This directory stores:
  • OAuth tokens for providers (Google Gemini, etc.)
  • Session state
  • Authentication cache

​
Logging Configuration

​
Debug Mode

config.yaml
debug: false
​
debug
boolean
default:"false"
Enable debug-level logging and detailed error messages. Useful for troubleshooting but verbose in production.

​
File Logging

config.yaml
logging-to-file: false
logs-max-total-size-mb: 0
​
logging-to-file
boolean
default:"false"
When true, write logs to rotating files in ./logs/ instead of stdout.
​
logs-max-total-size-mb
integer
default:"0"
Maximum total size (MB) of log files. Oldest logs are deleted when limit is exceeded. Set to 0 to disable limit.
Example production logging: 
debug: false
logging-to-file: true
logs-max-total-size-mb: 1000  # 1GB total log retention

​
WebSocket Configuration

config.yaml
ws-auth: true
​
ws-auth
boolean
default:"true"
Enable authentication for WebSocket API (/v1/ws). Recommended to keep enabled for security.

​
Usage Statistics

config.yaml
usage-statistics-enabled: false
​
usage-statistics-enabled
boolean
default:"false"
Enable in-memory usage statistics aggregation. When false, usage data is discarded.
When enabled, usage stats are available via the Management API dashboard.

​
Proxy Settings

Configure a global proxy for outbound requests:
config.yaml
proxy-url: ""
​
proxy-url
string
Global proxy URL. Supports socks5://, http://, and https:// protocols.
Examples: 
# SOCKS5 proxy with authentication
proxy-url: "socks5://user:pass@192.168.1.1:1080/"

# HTTP proxy
proxy-url: "http://proxy.company.com:8080"
Individual providers can override the global proxy using their own proxy-url setting.

​
Request Retry Configuration

config.yaml
request-retry: 3
max-retry-interval: 0
​
request-retry
integer
default:"3"
Number of retry attempts for requests that fail with specific HTTP errors (403, 408, 500, 502, 503, 504).
​
max-retry-interval
integer
default:"0"
Maximum wait time in seconds before retrying a cooled-down credential. 0 means no limit.

​
Streaming Configuration

Control SSE heartbeats and bootstrap retry behavior:
config.yaml
streaming:
  keepalive-seconds: 15
  bootstrap-retries: 2
​
streaming.keepalive-seconds
integer
default:"15"
Heartbeat interval in seconds for SSE streams. Set to 0 to disable keepalive messages.
​
streaming.bootstrap-retries
integer
default:"2"
Number of retries before the first byte is sent to handle auth rotation. 0 disables bootstrap retries.
Bootstrap retries allow switchAILocal to transparently recover from transient auth failures before streaming begins.

​
Quota Exceeded Behavior

Configure automatic failover when API quotas are hit:
config.yaml
quota-exceeded:
  switch-project: true
  switch-preview-model: true
​
quota-exceeded.switch-project
boolean
default:"true"
Automatically switch to the next available project/credential when quota is exceeded.
​
quota-exceeded.switch-preview-model
boolean
default:"true"
Fallback to preview models (if available) when quota is exceeded on stable models.

​
Routing Strategy

Configure how credentials are selected when multiple match:
config.yaml
routing:
  strategy: "round-robin"
  # auto-model-priority:
  #   - "ollama:gpt-oss:120b-cloud"
  #   - "switchai-chat"
  #   - "gemini-2.5-flash"
​
routing.strategy
string
default:"round-robin"
Credential selection strategy. Options:
  • round-robin: Distribute requests evenly across credentials
  • fill-first: Use first credential until quota/error, then move to next
​
routing.auto-model-priority
array
Priority list for “auto” model resolution. System checks models in order and picks the first active one. Supports provider:model syntax.

​
Model Prefix Enforcement

config.yaml
force-model-prefix: false
​
force-model-prefix
boolean
default:"false"
When true, unprefixed model requests only use credentials without a prefix. When false, unprefixed requests can match any available credential.
Example: With force-model-prefix: true:
  • Request for gemini-pro → Only uses unprefixed Gemini credentials
  • Request for team-a/gemini-pro → Only uses credentials with prefix: "team-a"

​
Complete Example

config.yaml
# Production server configuration
host: ""
port: 443

tls:
  enable: true
  cert: "/etc/ssl/certs/switchai.pem"
  key: "/etc/ssl/private/switchai.key"

auth-dir: "~/.switchailocal"

# Logging
debug: false
logging-to-file: true
logs-max-total-size-mb: 2000

# Security
ws-auth: true

# Performance
usage-statistics-enabled: true
request-retry: 3

streaming:
  keepalive-seconds: 30
  bootstrap-retries: 3

routing:
  strategy: "round-robin"

quota-exceeded:
  switch-project: true
  switch-preview-model: true

​
Next Steps

Provider Configuration

Configure API keys for cloud and local AI providers

Security Settings

Set up API authentication and management access