broker.yaml

Broker topology, disk persistence, and fallback behavior.

Source: crates/config/src/types/broker.rs.

Shape

broker:
  type: nats          # nats | local
  url: nats://localhost:4222
  auth:
    enabled: false
    nkey_file: ./secrets/nats.nkey
  persistence:
    enabled: true
    path: ./data/queue
  limits:
    max_payload: 4MB
    max_pending: 10000
  fallback:
    mode: local_queue
    drain_on_reconnect: true

Fields

FieldTypeDefaultPurpose
typenats | locallocallocal keeps the whole bus in-process; nats uses a real NATS server.
urlurl—NATS connection URL (ignored when type: local).
auth.enabledboolfalseTurn on NKey mTLS.
auth.nkey_filepath—Path to the NKey file when auth.enabled.
persistence.enabledbooltrueTurn on the SQLite disk queue.
persistence.pathpath./data/queueDirectory for the disk queue SQLite DB.
limits.max_payloadsize4MBReject events larger than this.
limits.max_pendingu6410000Hard cap on the disk queue; past this, oldest events are shed.
fallback.modelocal_queue | droplocal_queueWhat to do when NATS is unreachable.
fallback.drain_on_reconnectbooltrueReplay the disk queue when NATS returns.

Operational notes

  • type: local for single-machine dev. You don't need NATS running just to try the agent. The local broker matches NATS subject semantics, so everything works the same.
  • Disk queue always on in production. Even on a single machine. It's the guarantee against losing events on a NATS blip.
  • drain_on_reconnect: true is FIFO. See Event bus — Disk queue.

See also: