Skip to main content

​
Overview

Heartbeat commands provide real-time monitoring of AI provider availability, latency, quota usage, and model discovery.

​
Commands

​
status

Check health status of all configured providers. 
switchAILocal heartbeat status
Output: 
Checking provider status...

PROVIDER              STATUS     LATENCY    MODELS    MESSAGE
--------              ------     -------    ------    -------
gemini-cli            healthy    142ms      15        
claude-cli            healthy    98ms       8         
ollama                healthy    12ms       3         
switchai-api          healthy    234ms      42        
gemini-api            healthy    156ms      15        
claude-api            healthy    187ms      12        
groq                  healthy    89ms       7         
openai-compat-xyz     degraded   2341ms     5         High latency detected
The status command automatically discovers providers from your config.yaml and environment variables.

​
check

Check health of a specific provider. 
switchAILocal heartbeat check <provider>
​
provider
string
required
Provider name to check. Available providers:
  • gemini - Google Gemini (CLI)
  • claude - Anthropic Claude (CLI)
  • ollama - Local Ollama instance
  • gemini-api - Gemini via API
  • claude-api - Claude via API
  • openai - OpenAI API
  • groq - Groq API
  • Custom provider names from config
switchAILocal heartbeat check ollama
Output: 
Checking ollama...
Status: healthy
Latency: 12ms
Metadata:
  endpoint: http://localhost:11434
  version: 0.1.29
  models_available: 3
  models:
    - llama2:latest
    - codellama:7b
    - mistral:latest
Error Example: 
Checking ollama...
❌ Error: Failed to check provider 'ollama': connection refused

💡 Tip: Verify the provider name and ensure it's configured.
   Available providers: gemini, claude, openai, ollama

​
quota

Display quota usage for all API-based providers. 
switchAILocal heartbeat quota
Output: 
Checking quotas...

PROVIDER              QUOTA USED    LIMIT       RESET
--------              ----------    -----       -----
gemini-api            15,432        1,000,000   -
claude-api            8,291         500,000     -
switchai-api          142,087       10,000,000  -
groq                  1,234         60,000      -
openai                N/A           N/A         -
gemini-cli            N/A           N/A         -
claude-cli            N/A           N/A         -
ollama                N/A           N/A         -

💡 Note: Quota information is only available for API-based providers.
   CLI-based providers (gemini-cli, claude-cli) don't report quotas.
Quota information is extracted from API response headers during health checks. Values represent token usage or request counts depending on the provider.

​
discover

Force model discovery for local providers. 
switchAILocal heartbeat discover
Output: 
Discovering models...
✓ Discovered 3 models for ollama

Found 3 models:
  - llama2:latest (3.8 GB)
  - codellama:7b (3.8 GB)
  - mistral:latest (4.1 GB)
No Models: 
Discovering models...
No models found.

💡 Tip: Pull some models first:
   ollama pull llama2
   ollama pull codellama
Error: 
Discovering models...
❌ Error: Failed to discover Ollama models: connection refused

💡 Tip: Ensure Ollama is running on http://localhost:11434
   Start Ollama with: ollama serve
Model discovery requires the memory system to be initialized:
switchAILocal memory init

​
Provider Types

Heartbeat monitors three types of providers:

​
CLI-Based Providers

  • gemini-cli - Google Gemini via gcloud CLI
  • claude-cli - Anthropic Claude via CLI
These providers don’t report quotas but are checked for availability.

​
API-Based Providers

  • gemini-api - Google Gemini via REST API
  • claude-api - Anthropic Claude via REST API
  • switchai-api - SwitchAI proprietary API
  • groq - Groq inference API
These providers report quota usage and rate limits.

​
Local Providers

  • ollama - Local Ollama instance
  • vibe - Local Vibe AI
Local providers support model discovery and typically have low latency.

​
Configuration

Providers are auto-registered from your config.yaml: 
# Ollama local instance
ollama:
  enabled: true
  base_url: http://localhost:11434

# Gemini API keys
gemini_key:
  - api_key: AIzaSy...
    base_url: https://generativelanguage.googleapis.com/v1beta

# Claude API keys
claude_key:
  - api_key: sk-ant-...
    base_url: https://api.anthropic.com

# OpenAI-compatible providers
openai_compatibility:
  - name: groq
    base_url: https://api.groq.com/openai/v1
    api_key_entries:
      - api_key: gsk_...

​
Environment Variable Fallbacks

If providers aren’t in your config, heartbeat checks these environment variables: 
export OPENAI_API_KEY="sk-..."
export GEMINI_API_KEY="AIzaSy..."
export ANTHROPIC_API_KEY="sk-ant-..."

​
Health Check Details

A provider is marked healthy when:
  • Connection succeeds within 5 seconds
  • Authentication is valid
  • At least one model is available
  • Latency is under 3 seconds
A provider is marked degraded when:
  • Connection succeeds but latency > 3 seconds
  • Some models unavailable
  • Quota approaching limits
Degraded providers remain usable but may have performance issues.
A provider is marked unavailable when:
  • Connection fails
  • Authentication fails
  • No models available
  • Quota exceeded

​
Status Interpretation

healthy

All systems operational. Provider ready for requests.

degraded

Provider functional but experiencing issues. Fallback recommended.

unavailable

Provider offline or inaccessible. Requests will fail.

unknown

Provider not yet checked or check timed out.

​
Steering and Hooks Integration

Heartbeat status can trigger automated responses:

​
Steering Rules

Automatically route around unhealthy providers: 
# ~/.switchailocal/steering/fallback-unhealthy.yaml
name: "Fallback on Provider Failure"
activation:
  condition: "provider_status == 'unavailable'"
  priority: 100
preferences:
  primary_model: "claude-sonnet-4"
  fallback_providers:
    - anthropic
    - google
    - openai

​
Hooks

Receive alerts when providers become unhealthy: 
# ~/.switchailocal/hooks/health-alert.yaml
id: health-recovery
name: "Health Check Recovery"
enabled: true
event: health_check_failed
condition: "data.provider == 'ollama'"
action: restart_provider
params:
  max_retries: 3
  retry_delay: 5s

​
Troubleshooting

Providers are auto-registered from config:
  1. Check your config.yaml has provider sections
  2. Verify API keys are set (not placeholders)
  3. Set environment variables as fallback:
export OPENAI_API_KEY="sk-..."
export GEMINI_API_KEY="AIzaSy..."
Ensure Ollama is running:
# Start Ollama
ollama serve

# Verify it's running
curl http://localhost:11434/api/tags

# Check with heartbeat
switchAILocal heartbeat check ollama
Verify API keys are valid:
# Re-authenticate
switchAILocal --claude-login
switchAILocal --login  # Gemini

# Or update config.yaml with valid keys
Quota info requires:
  1. API-based provider (not CLI)
  2. Valid authentication
  3. Provider supports quota headers
# Check quota specifically
switchAILocal heartbeat quota