Nix

Koyal includes a flake for reproducible development shells and package builds.

nix develop
nix build
./result/bin/koyal doctor

The developer shell includes Rust, rust-analyzer, cargo-deny, cargo-audit, just, mdbook, lychee, actionlint, Node.js, Go, and supporting CLIs used by the local quality gates.

Use the same check script as CI:

scripts/ci/nix_flake_check.sh

Set KOYAL_FULL_NIX_CHECK=1 to build the default package through the script. Without nix installed, the script exits successfully with a clear skip message so non-Nix contributors can keep using the Cargo and Docker paths.

scripts/ci/check_nix_contract.sh statically keeps the flake package, dev shell tooling, runtime checker, docs, and just nix-check target aligned.

NixOS Module

Koyal also exports nixosModules.default and nixosModules.koyal:

{
  imports = [ inputs.koyal.nixosModules.default ];

  services.koyal.instances.gateway = {
    package = inputs.koyal.packages.${pkgs.system}.koyal;
    gatewayHost = "127.0.0.1";
    gatewayPort = 8790;
    environmentFile = "/run/agenix/koyal.env";
  };
}

Each services.koyal.instances.<name> entry creates an isolated systemd unit, system user/group, and state directory. Set package = inputs.koyal.packages.${pkgs.system}.koyal explicitly because Koyal is consumed as an out-of-tree flake module. nix/test.nix covers gateway and agent-tick unit generation plus hardening defaults for module maintainers.