Skip to main content

​
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

​
--config
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
​
--password
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
​
--project_id
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

Enable centralized token storage using PostgreSQL:
​
PGSTORE_DSN
string
PostgreSQL connection string
export PGSTORE_DSN="postgresql://user:pass@localhost:5432/switchai"
​
PGSTORE_SCHEMA
string
Database schema name (optional)
​
PGSTORE_LOCAL_PATH
string
Local spool directory for cached data
Enable version-controlled token storage using Git:
​
GITSTORE_GIT_URL
string
Git repository URL for token storage
​
GITSTORE_GIT_USERNAME
string
Git username for authentication
​
GITSTORE_GIT_TOKEN
string
Git access token (personal access token or password)
​
GITSTORE_LOCAL_PATH
string
Local path for git repository clone
Enable S3-compatible object storage for tokens:
​
OBJECTSTORE_ENDPOINT
string
S3-compatible endpoint URL (supports http:// or https://)
​
OBJECTSTORE_ACCESS_KEY
string
Access key ID
​
OBJECTSTORE_SECRET_KEY
string
Secret access key
​
OBJECTSTORE_BUCKET
string
Bucket name for token storage
​
OBJECTSTORE_LOCAL_PATH
string
Local cache directory

​
Cloud Deployment

​
DEPLOY
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

​
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:
  1. PostgreSQL Store (if PGSTORE_DSN is set)
  2. Object Store (if OBJECTSTORE_ENDPOINT is set)
  3. Git Store (if GITSTORE_GIT_URL is set)
  4. Local File (specified via --config or default config.yaml)
When multiple storage backends are configured, PostgreSQL takes highest precedence.