Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

birdd

birdd is a signed observation and federation node. This book documents how to operate and configure a node.

Start with Node configuration for the typed TOML settings accepted by birdd.

Node configuration

birdd configuration is typed in Rust, loaded from TOML, and rejects unknown keys. NixOS deployments generate birdd.toml from services.birdd options. Credential files are loaded separately and secret values are protected in memory.

Node identity

node_name

Stable name used to identify this node in operations and telemetry.

  • Type: string
  • Required
  • NixOS: services.birdd.nodeName

flock_display_name

Human-readable flock identity published in signed metadata.

  • Type: string
  • Required
  • NixOS: services.birdd.flockDisplayName

time_zone

IANA time zone used to interpret local dates and display observation times.

  • Type: string, such as UTC or America/New_York
  • Default: UTC
  • NixOS: time.timeZone

relays

Nostr-compatible relays used to publish and receive federated events.

  • Type: array of ws:// or wss:// URL strings
  • Default: []
  • NixOS: services.birdd.relays

Federation

federation.default_audiences

Audience policies applied to new local observations. Every entry must name a policy under federation.audiences, and duplicates are rejected.

  • Type: non-empty array of audience names
  • Default: ["public"]
  • NixOS: services.birdd.settings.federation.default_audiences

Audience names contain 1-32 lowercase letters, digits, or hyphens. Replace name in the options below with that audience name.

federation.audiences.<name>.transport

Determines whether an audience is published openly or encrypted for named recipients.

  • Type: enum
  • Values: public, restricted
  • Required

federation.audiences.<name>.allowed_senders

Flock public keys allowed to send restricted observations into this audience. Public audiences must leave this empty.

  • Type: array of unique 64-character hexadecimal public keys
  • Default: []

federation.audiences.<name>.recipients

Flock public keys that receive encrypted observations for a restricted audience. Restricted audiences require at least one recipient; public audiences must leave this empty. A recipient can belong to only one audience.

  • Type: array of unique 64-character hexadecimal public keys
  • Default: []

Audience projection

federation.audiences.<name>.projection.observed_at_precision

Reduces timestamp precision before an observation is published to this audience.

  • Type: enum
  • Values: exact, hour, day
  • Default: exact

federation.audiences.<name>.projection.publication_delay_seconds

Minimum delay before projected observations become eligible for federation.

  • Type: unsigned integer from 0 through 31536000
  • Default: 0

federation.audiences.<name>.projection.notes

Controls whether observation notes are included for this audience.

  • Type: boolean
  • Default: true

federation.audiences.<name>.projection.tags

Controls whether observation tags are included for this audience.

  • Type: boolean
  • Default: true

federation.audiences.<name>.projection.location

Controls whether location data is included for this audience.

  • Type: boolean
  • Default: false

federation.audiences.<name>.projection.media

Controls whether signed media references are included for this audience.

  • Type: boolean
  • Default: true

federation.audiences.<name>.projection.extensions

Selects which namespaced extension envelopes are included for this audience.

  • Type: non-empty array of strings
  • Values: ["*"] or an allowlist of namespaced extension IDs
  • Default: ["*"]

Public audiences must use the default projection. Projection controls are intended for restricted audiences.