Skip to main content

Profile File Structure

Frontmatter fields: OSS does not authenticate clients or enforce per-client request quotas. Configure authentication and inbound rate limiting at your reverse proxy. Provider quota and circuit-breaker backoff are separate routing controls. Unknown YAML fields and invalid types are rejected. Use booleans (false), not quoted strings ("false"). A failed reload keeps the previous active configuration. Errors identify the field without printing credential values. Profile slugs must match their .yml filenames. Files beginning with _ or . are skipped. Keep a public.yml profile: routes without a profile use public, and it is required at startup. unlisted: true hides a profile from the selector; its endpoints remain accessible.

Chain Configuration

Each chain is a key under chains: with the following structure:

Chain Fields

Monitoring

Controls probe frequency and the dashboard lag status threshold. Shared upstreams use the shortest configured probe interval across profiles; HTTP polling slows while WebSocket block updates are active. Intervals accept 0 or at least 1,000 ms. Shared physical upstreams use the shortest positive interval requested by an enabled reference. Disabling one reference does not disable another profile’s observations.

Selection

Controls provider eligibility filtering during request routing.

Transaction providers

Added in v0.8.0. transactions: {providers: [provider_id], fallback: none} on a chain sends signed transactions only to the listed providers, one at a time; reads, subscriptions and block recovery keep using the chain’s other providers. Each listed ID must name a send-capable provider on that chain, and at least one other provider must remain to serve reads. Omit the block for ordinary routing, which also applies to profiles created before v0.8.0. Sending fails closed by default: if no transaction provider can take the send, the request fails rather than reaching a read provider. Set fallback to read_providers to add an explicit second phase over the chain’s other providers once the transaction providers are exhausted, within the same deadline and dispatch budget; the two sides are never ranked together. See the transaction providers configuration and routing behavior for the full contract, including the private-send example profile.

WebSocket

Controls upstream WebSocket subscription behavior. Failover limits are captured from the active profile at the beginning of each recovery, including after YAML reload. An in-progress recovery keeps its captured limits. The effective block allowance is the greater of max_backfill_blocks and the blocks expected during one backfill-timeout horizon, with time-derived expansion capped at 2,048 blocks. The backfill timeout is also bounded by the overall 30-second recovery deadline. Gaps beyond the effective allowance terminate continuity rather than silently skipping missing blocks.

UI Topology

Dashboard visualization settings. For live updates, see Profiles and reload.