WG Mesh development

Local setup is a work in progress

The host setup steps below are not fully verified. Ask the team if a step fails.

WG Mesh has an eBPF data path and a Go command named atlas-wg-mesh. Metal calls the command to install hooks and replace host state. Read how VMs reach each other before you change packet rules.

Find the owner

Change	Start here
Packet checks and forwarding	VM hook and WireGuard hook
Shared map layout	Map definitions and Go BPF loader
Host and VM commands	Go command package
Metal integration	Metal mesh attachment

The design page lists every hook, map, and packet rule. The component specification defines the code boundaries.

Build and check

Run these commands from services/wg-mesh/ on Linux. Install Go from the version in cli/go.mod, Clang, and the Linux BPF headers first.

sudo apt-get update
sudo apt-get install --yes clang libbpf-dev linux-libc-dev
make bpf
go vet -C cli ./...
go test -C cli -race ./...
make build

make bpf creates the object that the Go command embeds. make build creates Linux binaries for amd64 and arm64 in dist/. Unit tests do not need root. Host commands need root because they change interfaces and BPF hooks.

Check a host

Use a test host for packet checks. The operations guide shows how to inspect hooks, maps, peers, and VM locations. Check both local delivery and traffic between hosts when you change a packet rule.

The WG Mesh CI job runs the BPF build, Go vet, race tests, and release build. Read the nearest Go test when you change a command. Packet behavior also depends on Metal's host links and WireGuard peer policy.