Profile File Structure
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 underchains: 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.