Installation

birdd can run as a standalone binary or as a NixOS service. The project flake supports Linux and macOS on x86-64 and ARM64.

Note

The quickest way to get started with birdd is to use the reference stack.

NixOS

The flake exports nixosModules.birdd. A minimal service configuration looks like this:

{inputs, pkgs, ...}: {
  imports = [inputs.birdd.nixosModules.birdd];

  services.birdd = {
    enable = true;
    package = inputs.birdd.packages.${pkgs.system}.birdd;
    nodeName = "pallet";
    flockDisplayName = "Pallet Town Birders";
    flockKeyFile = "/var/lib/private/birdd/flock.key";
    relays = ["wss://relay.example.com"];
  };
}

The key file must already exist at an absolute path outside the Nix store. The service will not start when it is missing. Node state defaults to /var/lib/birdd, and the module installs a birdd-admin wrapper for running CLI commands with the service identity and permissions.

Build with Nix

Build the node from the repository:

nix build .#birdd
./result/bin/birdd --help

Install it into your user profile:

nix profile install .#birdd

Use birdd-with-docs instead when the admin portal should serve an embedded copy of this book:

nix build .#birdd-with-docs

Build from source

Source builds require a Rust toolchain supporting edition 2024, OpenSSL, and pkg-config. SQLite is bundled by the Rust dependency.

cargo build --release --locked
./target/release/birdd --help

The build produces birdd, the main node and CLI; and birdd-admin-web, the local operator portal.

Continue with Node configuration after installation.