Skip to main content

​
Overview

Steering commands manage runtime routing rules that automatically adjust model selection based on intent, user, time of day, and other conditions. Steering rules complement the Cortex Router by providing static, deterministic routing policies.

​
Commands

​
list

Display all active steering rules. 
switchAILocal steering list
Output: 
Active Steering Rules:

ID              INTENT          MODEL              PRIORITY  CONDITIONS
--              ------          -----              --------  ----------
fallback-1      coding          ollama:codellama   100       provider:geminicli unhealthy
secure-route    *               ollama:llama3.2    200       user:enterprise-*
off-hours       fast            switchai-fast      150       hour:22-06
Steering rules are loaded from ~/.switchailocal/steering/*.yaml files.

​
test

Test a steering rule against specific conditions. 
switchAILocal steering test [options]
​
--file
string
Path to specific rule file to test
​
--intent
string
Intent to test against (e.g., coding, reasoning, fast)
​
--user
string
User API key hash to test against
​
--hour
integer
Hour of day to test (0-23, default: current hour)
​
--format
string
Output format: table or json (default: table)
Example: 
switchAILocal steering test --intent coding --hour 23
Output: 
Testing steering rules:

Intent: coding
Hour: 23

Matching Rules:
  - off-hours: switchai-fast (priority: 150)
  - fallback-1: ollama:codellama (priority: 100)

Selected Model: switchai-fast
Reason: Highest priority match

​
validate

Validate steering rule syntax and conditions. 
switchAILocal steering validate [--file <path>]
Example: 
switchAILocal steering validate --file ~/.switchailocal/steering/custom.yaml
Output: 
Validating: /Users/user/.switchailocal/steering/custom.yaml

✓ Syntax valid
✓ All conditions recognized
✓ Model references valid
✓ Priority values acceptable

Validation passed.

​
reload

Reload all steering rules from disk without restarting the server. 
switchAILocal steering reload
Output: 
Reloading steering rules...

✓ Loaded 5 rules from 3 files
✓ All rules validated successfully

Steering engine reloaded.
Hot reload is only available when the server is running with --enable-steering.

​
Steering Rule Format

Steering rules are defined in YAML files:
~/.switchailocal/steering/custom-routing.yaml
rules:
  - id: coding-local
    intent: coding
    model: ollama:codellama
    priority: 100
    conditions:
      - provider: geminicli
        status: unhealthy
      - provider: claudecli
        status: unhealthy
  
  - id: secure-data
    intent: "*"
    model: ollama:llama3.2
    priority: 200
    conditions:
      - user_pattern: "enterprise-*"
      - pii_detected: true
  
  - id: off-hours-fast
    intent: fast
    model: switchai-fast
    priority: 150
    conditions:
      - hour_range: "22-06"

​
Rule Fields

​
id
string
required
Unique identifier for the rule
​
intent
string
required
Target intent (coding, reasoning, fast, secure, or * for all)
​
model
string
required
Model to route to (supports provider prefixes)
​
priority
integer
required
Priority (0-1000, higher = preferred)
​
conditions
array
List of conditions that must all be true for the rule to apply

​
Supported Conditions

  • provider: <name> + status: <healthy|unhealthy|degraded>
  • user_pattern: <glob> - Match user API key hash
  • hour_range: <start-end> - Match hour of day (24h format)
  • pii_detected: <true|false> - Match PII detection result
  • quota_remaining: <percentage> - Match quota threshold

​
Use Cases

Route to local models when cloud providers are unhealthy:
- id: cloud-failover
  intent: "*"
  model: ollama:llama3.2
  priority: 90
  conditions:
    - provider: geminicli
      status: unhealthy
    - provider: claudecli
      status: unhealthy
Force local models for requests containing PII:
- id: pii-local
  intent: "*"
  model: ollama:llama3.2
  priority: 200
  conditions:
    - pii_detected: true
Use faster, cheaper models during off-peak hours:
- id: night-fast
  intent: fast
  model: switchai-fast
  priority: 150
  conditions:
    - hour_range: "22-06"
Route enterprise users to dedicated models:
- id: enterprise-dedicated
  intent: "*"
  model: ollama:llama3.2
  priority: 180
  conditions:
    - user_pattern: "enterprise-*"

​
Integration with Cortex Router

Steering rules and Cortex Router work together:
  1. Cortex Router classifies the request intent
  2. Steering rules are evaluated against the classified intent
  3. If a steering rule matches, its model overrides the Cortex selection
  4. If no steering rule matches, Cortex selection is used
Use steering for deterministic, policy-based routing and Cortex for intelligent, adaptive routing.

​
Troubleshooting

  • Verify rule files are in ~/.switchailocal/steering/
  • Check file permissions (must be readable)
  • Run steering validate to check syntax
  • Ensure server was started with --enable-steering
  • Higher priority rules take precedence
  • If priorities are equal, first defined rule wins
  • Use steering test to debug rule evaluation
  • Check condition syntax against supported conditions
  • Ensure provider names match configured providers
  • Verify hour ranges are in 24h format (0-23)

​
See Also