Heartbeat Commands - switchAILocal

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>

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

switchAILocal heartbeat check claude

switchAILocal heartbeat check gemini-api

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

What does 'healthy' mean?

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

What does 'degraded' mean?

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.

What does 'unavailable' mean?

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

No providers registered

Providers are auto-registered from config:

Check your config.yaml has provider sections
Verify API keys are set (not placeholders)
Set environment variables as fallback:

export OPENAI_API_KEY="sk-..."
export GEMINI_API_KEY="AIzaSy..."

Ollama shows as unavailable

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

API provider auth failed

Verify API keys are valid:

# Re-authenticate
switchAILocal --claude-login
switchAILocal --login  # Gemini

# Or update config.yaml with valid keys

Quota information not showing

Quota info requires:

API-based provider (not CLI)
Valid authentication
Provider supports quota headers

# Check quota specifically
switchAILocal heartbeat quota

Memory Commands - View routing history
Steering Commands - Configure automatic fallbacks
Hooks Commands - Set up health alerts

​Overview

​Commands

​status

​check

​quota

​discover

​Provider Types

​CLI-Based Providers

​API-Based Providers

​Local Providers

​Configuration

​Environment Variable Fallbacks

​Health Check Details

​Status Interpretation

healthy

degraded

unavailable

unknown

​Steering and Hooks Integration

​Steering Rules

​Hooks

​Troubleshooting

​Related Commands

Overview

Commands

status

check

quota

discover

Provider Types

CLI-Based Providers

API-Based Providers

Local Providers

Configuration

Environment Variable Fallbacks

Health Check Details

Status Interpretation

Steering and Hooks Integration

Steering Rules

Hooks

Troubleshooting

Related Commands