Both inbound SIP dispatch and outbound dialout must land on a CXB Core fleet host that has free worker capacity. CXB API does this with pick_fleet_server, backed by a parallel health check across every host in core_fleet. The fleet-routing logic lives in the API service’s fleet route and fleet service.

​
core_fleet

core_fleet is a list of CXB Core base URLs stored in the system document of system_settings. Adding a host to this list is all that is needed to include it in routing — no code change or restart. It is read by the dialout route, the LiveKit webhook, and the fleet status endpoint.

​
Health check

Each host is polled at GET {host}/health/fleet (_check_server). A host is healthy only if all of these hold; otherwise it is reported unreachable:
CheckRequirement
ReachableHTTP 2xx within FLEET_HEALTH_TIMEOUT_SECONDS (20s)
PayloadJSON object with status == "ok"
fleet_maxnon-negative int (total capacity)
fleet_availablenon-negative int, <= fleet_max
fleet_callsnon-negative int (active calls)
workerslist
The timeout is deliberately 20s, not 5s. /health/fleet aggregates all workers over Unix sockets; when workers are mid-call those polls queue and the endpoint can legitimately take 3–6s. A tight timeout was previously marking healthy-but-busy hosts unreachable and excluding them from routing.

​
Best-server selection

  • Only healthy hosts with total_available > 0 are candidates.
  • The host(s) with the highest total_available win; ties are broken with random.choice, spreading load across equally-free hosts.
  • None means no capacity — callers translate this to 503 (dialout: No healthy fleet server available; webhook: No healthy fleet).

​
Fleet status endpoint

GET /api/v1/fleet/status (admin) returns the aggregated view used by the dashboard:
FieldMeaning
total_capacitysum of fleet_max over healthy hosts
active_callssum of fleet_calls over healthy hosts
availabletotal_capacity - active_calls
workers[]per-host {url, status, total_capacity, total_available, worker_calls, workers}

​
config_url passthrough

When proxying a dialout, CXB API injects config_url = <its own base URL>/api/v1/config into the request to the chosen fleet host (see SIP dialout). This lets a single shared fleet serve multiple CXB API instances: each call’s config is fetched back from the CXB API that triggered it, rather than from a fleet-wide environment default.

SIP dialout

Where pick_fleet_server and config_url are used for outbound.

LiveKit webhook

Where pick_fleet_server is used for inbound.

Carriers & trunks

The SIP side of the telephony stack.

Settings

Where core_fleet lives in system settings.