Server Command - switchAILocal

Overview

The main switchAILocal command starts the proxy server that provides OpenAI/Gemini/Claude compatible API interfaces for CLI models.

Usage

switchAILocal [flags]

Server Flags

string

default:"config.yaml"

Path to the configuration file. The server looks for config.yaml in the current working directory by default.

switchAILocal --config /path/to/custom-config.yaml

string

Server password for authentication. For security, prefer using the SERVER_PASSWORD environment variable instead.

Using --password on the command line exposes the password in process listings. Use environment variables for production.

export SERVER_PASSWORD="your-secure-password"
switchAILocal

string

Google Cloud Project ID for Gemini API access. Only required when using Vertex AI or project-specific Gemini endpoints.

switchAILocal --project_id my-gcp-project-123

Environment Variables

The server supports extensive configuration through environment variables, especially for cloud deployments.

Storage Backends

PostgreSQL Token Store

Enable centralized token storage using PostgreSQL:

string

PostgreSQL connection string

export PGSTORE_DSN="postgresql://user:pass@localhost:5432/switchai"

string

Database schema name (optional)

string

Local spool directory for cached data

Git Token Store

Enable version-controlled token storage using Git:

string

Git repository URL for token storage

string

Git username for authentication

string

Git access token (personal access token or password)

string

Local path for git repository clone

Object Store (S3-Compatible)

Enable S3-compatible object storage for tokens:

string

S3-compatible endpoint URL (supports http:// or https://)

string

Access key ID

string

Secret access key

string

Bucket name for token storage

string

Local cache directory

Cloud Deployment

string

Set to cloud to enable cloud deployment mode. In this mode, the server waits for configuration before starting.

export DEPLOY="cloud"
switchAILocal

Examples

# Start with default config.yaml in current directory
switchAILocal

# Use a specific configuration file
switchAILocal --config /etc/switchai/production.yaml

# Use PostgreSQL for centralized token storage
export PGSTORE_DSN="postgresql://admin:secret@db.example.com:5432/switchai"
export PGSTORE_SCHEMA="public"
switchAILocal

# Cloud deployment with object storage
export DEPLOY="cloud"
export OBJECTSTORE_ENDPOINT="https://s3.amazonaws.com"
export OBJECTSTORE_ACCESS_KEY="AKIA..."
export OBJECTSTORE_SECRET_KEY="..."
export OBJECTSTORE_BUCKET="switchai-tokens"
switchAILocal

# Secure password authentication
export SERVER_PASSWORD="$(openssl rand -base64 32)"
switchAILocal --config config.yaml

Output

When the server starts successfully, you’ll see:

switchAILocal Version: v1.2.3, Commit: abc123, BuiltAt: 2026-03-09T10:00:00Z
switchAILocal Version: v1.2.3, Commit: abc123, BuiltAt: 2026-03-09T10:00:00Z
INFO[0000] Configuration loaded from: /path/to/config.yaml
INFO[0001] Server listening on http://localhost:8080
INFO[0001] OpenAI-compatible endpoint: http://localhost:8080/v1

Security Considerations

The server performs security validation on startup:

File Permissions: Configuration and auth files should have restrictive permissions (600 or more restrictive)
Path Traversal: File paths are validated to prevent directory traversal attacks
Sensitive Data: Passwords and tokens in error messages are automatically sanitized
Environment Variables: Sensitive environment variables are checked for common security issues

Configuration Precedence

The server loads configuration in the following order:

PostgreSQL Store (if PGSTORE_DSN is set)
Object Store (if OBJECTSTORE_ENDPOINT is set)
Git Store (if GITSTORE_GIT_URL is set)
Local File (specified via --config or default config.yaml)

When multiple storage backends are configured, PostgreSQL takes highest precedence.

Login Commands - Authenticate with AI providers
Memory Commands - Manage routing history and preferences
Heartbeat Commands - Monitor provider health

​Overview

​Usage

​Server Flags

​Environment Variables

​Storage Backends

​Cloud Deployment

​Examples

​Output

​Security Considerations

​Configuration Precedence

​Related Commands

Overview

Usage

Server Flags

Environment Variables

Storage Backends

Cloud Deployment

Examples

Output

Security Considerations

Configuration Precedence

Related Commands