sand-boxer/docs/routing.md

Extension routing

Version 0.1 — SAND-WP-0006. Select backend when a profile lists multiple extensions.

Profile route block

extension: ext.compose-ssh   # default / explicit fallback
route:
  strategy: prefer-self-hosted
  extensions:
    - ext.compose-ssh
    - ext.saas-stub
  max_cost_per_hour_usd: 1.0

Strategies

Strategy	Behavior
explicit	Use profile.extension (default when no route)
prefer-self-hosted	First self-hosted candidate with resolvable host; else SaaS
lowest-cost	Self-hosted if available; else cheapest estimate_cost
lowest-latency	Self-hosted if available; else last candidate (v0)

Testing SaaS fallback

# Skip self-hosted when host unavailable:
unset SANDBOXER_HOST
SANDBOXER_FORCE_SAAS=1 sandboxer create --profile profile.burst-sandbox

# Or use metered-only profile:
sandboxer create --profile profile.saas-stub

Reference profiles

Profile	Route
profile.burst-sandbox	compose-ssh → saas-stub fallback
profile.saas-stub	explicit ext.saas-stub

Resolver: sandboxer.routing.resolver.resolve_extension.