Steering Commands - switchAILocal

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]

string

Path to specific rule file to test

string

Intent to test against (e.g., coding, reasoning, fast)

string

User API key hash to test against

integer

Hour of day to test (0-23, default: current hour)

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

string

required

Unique identifier for the rule

string

required

Target intent (coding, reasoning, fast, secure, or * for all)

string

required

Model to route to (supports provider prefixes)

integer

required

Priority (0-1000, higher = preferred)

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

Automatic Failover to Local Models

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

Sensitive Data Routing

Force local models for requests containing PII:

- id: pii-local
  intent: "*"
  model: ollama:llama3.2
  priority: 200
  conditions:
    - pii_detected: true

Off-Hours Cost Optimization

Use faster, cheaper models during off-peak hours:

- id: night-fast
  intent: fast
  model: switchai-fast
  priority: 150
  conditions:
    - hour_range: "22-06"

Enterprise User Isolation

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:

Cortex Router classifies the request intent
Steering rules are evaluated against the classified intent
If a steering rule matches, its model overrides the Cortex selection
If no steering rule matches, Cortex selection is used

Use steering for deterministic, policy-based routing and Cortex for intelligent, adaptive routing.

Troubleshooting

Rules not applying

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

Multiple rules matching

Higher priority rules take precedence
If priorities are equal, first defined rule wins
Use steering test to debug rule evaluation

Condition not recognized

Check condition syntax against supported conditions
Ensure provider names match configured providers
Verify hour ranges are in 24h format (0-23)

​Overview

​Commands

​list

​test

​validate

​reload

​Steering Rule Format

​Rule Fields

​Supported Conditions

​Use Cases

​Integration with Cortex Router

​Troubleshooting

​See Also

Overview

Commands

list

test

validate

reload

Steering Rule Format

Rule Fields

Supported Conditions

Use Cases

Integration with Cortex Router

Troubleshooting

See Also