headscale-rs

A Rust implementation of Tailscale-style mesh coordination: node registration, WireGuard control plane, mesh topology, DERP relay, and per-session bandwidth metering.

This crate is the transport layer. It deliberately does not own escrow, payments, or settlement — those belong in an integration layer that consumes the MeteringSnapshot events surfaced by headscale-core::metering::MeteringService.

The current compatibility target is headscale-go v0.29.5. Verified results and the remaining replacement-parity gaps are recorded in the parity ledger and remaining-work audit; the qualification records are the standalone main line's checkpoints, bound to that line's tree.

Workspace layout

Five crates are first-class workspace members and participate in cargo build --workspace / cargo test --workspace / cargo clippy --workspace:

headscale-api-acl             native policy syntax and shared ACL types
headscale-api                 gRPC + HTTP control plane, Tailscale wire, admin GUI
headscale-db                  sqlite/postgres persistence (preauth keys, nodes, ...)
headscale-cli                 headscale-rs daemon + operator CLI
headscale-vendor-conformance  behaviour tests for the patched crates under vendor/

Four crates are on disk but not workspace members as of 2026-05-20 (see CHANGES.md). They are still compiled when the active crates above pull them in via path dependencies. Their own per-crate tests and lint checks require the separate manifest commands; workspace tests do not execute those excluded test targets.

headscale-core      mesh, WireGuard, DERP, metering, routing, authorization
headscale-identity  Ed25519 + DID + session primitives
headscale-resources resource registry + metering
headscale-payments  reference ledger / x402 / escrow / channels (deletion candidate)

To work on one of the demoted crates directly:

cd headscale-<name> && cargo build --release
cd headscale-<name> && cargo test

Build

cargo build --workspace

Quality gates

See docs/HARDENING.md for the local audit, coverage, fuzzing, and supply-chain commands. Pull requests run a 10k-input fuzz smoke pass; a separate scheduled workflow runs longer fuzz campaigns and uploads crash artifacts.