Guide

Developer Setup

Set up a Ze development environment with all build, lint, and test dependencies.

Quick Start

./le is built from this repository with Go, so Go comes first. Install the release go.mod names on its go line from https://go.dev/dl/, or any Go 1.21 or newer, which downloads that release on first use. Then put two directories on PATH: the Go toolchain's, and the one go install writes to, where setup builds golangci-lint, staticcheck, goimports, gopls and govulncheck:

export PATH="$PATH:/usr/local/go/bin"          # the go.dev tarball's location
export PATH="$PATH:$(go env GOPATH)/bin"       # or $(go env GOBIN) when GOBIN is set

Add both lines to ~/.profile (~/.zshenv for zsh) so every new shell has them. A non-interactive shell such as ssh host command reads no ~/.bashrc. Then:

git clone <repo-url> && cd ze
./le setup install
./le setup check

When the install directory is not on PATH, setup still builds the tools there, reports each as [pending ] <tool> (in /root/go/bin, which is not on PATH), and prints once the exact export PATH=... line for that directory and the profile to keep it in. check reports the same rows the same way: a tool no shell can run is never counted present.

This detects your OS (macOS with Homebrew or Debian/Ubuntu with apt), installs missing tools, vendors Go dependencies, and reports what it did.

le is the native development-tool personality built from cmd/ze. The root ./le is a dispatcher, and bin/le is an identical copy of it that ./le installs whenever the two differ. Both run the newest build in bin/builds/<UTC commit time>-<short sha>/le. Setup behavior lives in internal/le/setup.Answer.

Builds follow HEAD, never your working tree, because a peer session's half-written source would otherwise break every call in every session. Each build records the git tree hash of le's inputs (internal cmd pkg api vendor go.mod go.sum feature-gates.txt feature-tags) at the commit it came from. When a commit changes them, the next ./le call starts one build of HEAD in the background and keeps running the newest build; the new one is smoke-tested and renamed into place only when it passes, so after a git pull the new commands arrive a couple of minutes later with no command of yours waiting. A commit that changes no input reuses the newest build. On a fresh checkout with no build at all, the first call builds HEAD in the foreground.

A HEAD that fails to build is reported once on stderr, with its log at bin/builds/.failed-<commit>.log, and the newest good build keeps running. A build that does not start is moved aside to bin/builds/.failed-<name> and the call runs the next newest, saying so in one line. When the newest build starts but misbehaves, take it out by hand:

./le rollback

It moves the newest build aside the same way, so the next call runs the one before it, and HEAD is not built again until a commit changes the inputs. Nothing is deleted: a peer executing that build keeps its file. ./le help lists rollback and Tab completes it; run it as ./le rollback, because only the launcher moves a build. ./le --update is gone and says so with exit 2.

Do not delete bin/le or anything in bin/builds/. Several sessions share one checkout and one of them can be executing that file right now. When you need le to carry your own uncommitted edits, ask for a build of your own instead:

./le --name session verify current

--name comes first, before the command, and the launcher consumes it. Every argument after it reaches the binary unchanged. --name session names the build after CLAUDE_CODE_SESSION_ID (s-<its first eight characters>) and refuses with exit 2 when that variable is unset; --name mywork picks the name yourself. The build lands in bin/le-<name>/le, which bin/ already keeps out of git, and it is rebuilt from the working tree on every call, so the toolchain decides what to recompile and the binary carries your edits. The shared builds are never written and never wait for a peer.

A name accepts letters, digits, dot, underscore and hyphen. A name carrying / or .. is refused with a message and exit 2, never repaired into something safe.

The launcher exports the name to the process it runs and to that process's children, so a script that calls ./le inside a named session reaches the same build without repeating the option. A binary that is not the one you named refuses to answer and reports both names:

le: --name asked for 'mywork' and this process is 'le' (/home/you/ze/bin/builds/20261025T114143Z-00b9273a2a/le).
    Reach the named build through ./le --name mywork, never through a hardcoded binary path.

Check Mode

Probe the current host without installing anything:

./le setup check

The check action probes only and changes nothing: it installs no package, edits no sysctl, and adds no loopback address. It exits 0 if all required tools are present, nonzero if any are missing. Use it as a CI preflight check. Run ./le setup install to install what the probe found missing.

One row is behaviour rather than a binary: gopls-answers runs the language server and checks that it replies. A server on PATH that does not answer fails this check, because every LSP call against it fails the same way.

Editor plugin

A language server on PATH is not the whole capability. Claude Code reaches it through a plugin, and without that plugin the LSP tool refuses every Go file.

When Claude Code is installed (claude on PATH, or a ~/.claude directory) and the plugin is not, ./le setup check reports the plugin as a pending step and names the command that installs it. On a host without Claude Code the row is skipped with the reason "Claude Code is not installed", because there is no LSP tool to refuse anything and no session to run the slash command in.

Plugin Serves Install
gopls-lsp .go /plugin install gopls-lsp@claude-plugins-official

Run the slash command inside a Claude Code session. The plugin and the binary it names fail the same way and have different fixes, so the report says which of the two is absent.

Tool caches: le exec

./le exec <path> [args...] runs a program with its caches in the one per-user cache, $XDG_CACHE_HOME/ze, else ~/.cache/ze, instead of each tool's default folder (~/Library/Caches on macOS). It sets four variables, creates their directories, and then replaces itself with the program, so the program's exit status is the caller's and every argument after the path reaches it untouched.

A heavy tool that needs a job slot is the exception: go test, golangci-lint run, staticcheck and the formatters, judged as the Bash hook judges a raw command. In a checkout, le exec waits for a slot, then runs the tool as its child on the same terminal, forwards every SIGINT, SIGTERM, SIGHUP and SIGQUIT to it until it exits, releases the slot and exits with the tool's code. Inside a live parent's slot (./le go lint run starting the linter) or outside a checkout it holds nothing and replaces itself, as for any other program. The main thread's post-edit lint goes past the shim on purpose and takes no slot (docs/contributing/running-commands.md, "Waiting for another session's job").

Variable Directory under the per-user cache
GOCACHE go-cache
GOPLSCACHE gopls
GOLANGCI_LINT_CACHE golangci-lint-cache
STATICCHECK_CACHE staticcheck-matrix

When the working directory is inside a Ze checkout, the program also gets Ze's patched GOROOT, with GOTOOLCHAIN=local and the tree's bin first on PATH, so gopls analyzes the standard library Ze compiles. Anywhere else it gets the GOROOT, GOTOOLCHAIN and PATH its caller had, and never a patched tree, so a tool on another repository sees that repository's Go.

A bare name is looked up on PATH, skipping any file that carries the shim marker. le exec refuses, with exit 1, a path that does not exist, is not an executable file, or is a shim ./le setup wrote, because a shim handed back to le exec would start it again in a loop; each refusal names the path and ./le setup. Warm, ./le exec /usr/bin/true takes about 50 ms on an Apple silicon Mac.

Tool shims, PATH and the Go cache setting

./le setup install writes a shim for gopls, golangci-lint and staticcheck, the tool rows marked Shim in the setup table, into the shim directory it chooses from PATH. Each shim is a short sh script, mode 0755, that carries the le exec marker on its second line and ends with:

exec '/path/to/ze/le' exec '/path/to/real/gopls' "$@"

The shim directory is the earliest PATH entry that is:

  • an absolute path under HOME
  • an existing directory this user can write
  • outside any ze checkout (a directory holding go.mod beside feature-gates.txt, or under one)
  • ahead of every PATH directory holding a real gopls, golangci-lint or staticcheck

The PATH judged here is the caller's: the one the shell that ran ./le had, which is the one an editor or a new shell searches. le's own PATH is not it, because le puts the patched GOROOT's bin first before it runs any action (see above), and that tree lives under the per-user cache, so under HOME and writable. Setup restores the caller's PATH the way le exec does, dropping every patched tree's bin a parent le left on it, and judges the shim directory, the real tools and the gopls-answers row against that.

A directory listed twice counts at its first position, the one a lookup reaches. The Go bin directory never qualifies, because it holds the real tools, and a shim there would be overwritten by the next go install. Only when no entry qualifies do the shims go in ~/bin, and the shim-dir row is pending until PATH reaches ~/bin first.

The real tool is the first copy on PATH outside the shim directory that is not itself a shim. An editor, the Claude LSP or a shell that finds the tool by PATH then starts it through le exec, so its cache lands under ~/.cache/ze with no shell variable. Each run rewrites a shim whose checkout or tool path changed, so after moving the checkout or reinstalling a tool, run ./le setup install again. When the checkout a shim names is gone, the shim exits 1 and says which le is missing and that ./le setup install from the current checkout rewrites it. Setup never overwrites a file in the shim directory that it did not write: the row is pending and prints the mv command that moves the file aside. A shimmed tool with no real copy on PATH is missing, and its own tool row installs it; a shim found first on PATH does not count as the tool.

Once a tool's shim is current in the shim directory, the same run removes every older shim for that tool in ~/bin, in every other directory of the caller's PATH, and in every directory of le's own PATH (the patched tree's bin, where an earlier setup wrote them), and the tool's row names each one it removed. Directories are compared by identity, so a second spelling of the shim directory (~/Bin for ~/bin on a case-insensitive disk, or a link) is the same directory and keeps its shims. Only a file carrying the le exec marker under a shimmed tool's name is removed, so a file setup did not write is never touched. check removes nothing and reports the old shims as work left.

Row Present when Otherwise
<tool>-shim <shim directory>/<tool> runs le exec on the current real tool, and no older shim for it is left elsewhere install writes it and removes the old shims; check reports it missing
shim-dir a PATH entry qualifies; the row names it pending, with the shims in ~/bin and the lines below
go-env-gocache go env GOCACHE names <per-user cache>/go-cache, links followed install runs go env -w GOCACHE=<that path> and prints the old and new value; check reports it

le never edits a shell file. When no PATH entry qualifies, setup prints the line that puts ~/bin first for ~/.zshenv (~/.profile for another shell) and, when nu is on PATH, the line for the env file nu -c '$nu.env-path' names:

export PATH='/Users/you/bin':"$PATH"
$env.PATH = ($env.PATH | split row (char esep) | prepend r#'/Users/you/bin'# | uniq)

Plain go outside le reads GOCACHE from go env, so the go-env-gocache row is what keeps go build in any shell out of ~/Library/Caches/go-build. It reads the setting with GOCACHE removed from the environment, so le's own value does not hide it. When go env -w fails, for example under GOENV=off, the row fails with the reason and prints the exact go env -w command.

With the shims in place, the GOPLSCACHE, GOLANGCI_LINT_CACHE and STATICCHECK_CACHE lines in ~/.zshenv or env.nu are no longer needed: le exec sets them. The gopls-answers row names the gopls the caller's PATH reaches and whether it is the shim; a gopls started by absolute path, or one ahead of the shim directory, keeps its default cache.

What It Installs

Build and Lint

Tool Purpose
go Go toolchain
git Version control
protobuf (protoc) Protocol buffer compiler
jq JSON processing
golangci-lint Go linter (via go install)
staticcheck Feature-tag structural type checker, pinned to 2026.2.2 (honnef.co/go/tools v0.8.2 in, built from the vendor tree with go install -mod=vendor so it links the x/tools requires). go.modgo.mod
goimports Go import formatter (via go install)
gopls Go language server behind the agent LSP tool (via go install)
govulncheck Dependency vulnerability scanner for the verification gate, built from the vendored copy (via go install)

The linter's module dependency and setup install target move together. Use the pinned release: its exhaustive analyzer checks enum switches through type aliases as well as directly named types. An existing golangci-lint on PATH is only presence-probed by setup, so changing the pin alone does not replace that binary.

Regenerate the checked-in protobuf Go files after you change api/proto/ze.proto or the module path:

./le setup proto

The action builds both protoc plugins from the vendored module versions, runs protoc, and applies explicit json_name options to Go struct tags.

Run the installed checker through the repository gate:

./le go staticcheck check

The target and its checked feature population are documented in docs/contributing/testing.md.

Appliance

Tool Purpose
qemu QEMU functional and install gate tests
e2fsprogs mkfs.ext4 and debugfs for appliance builds
xorriso ISO image creation
grub GRUB EFI tooling for ISO builds (Linux only)
iproute2 (ip) The Linux loopback step's ip -6 addr add (Linux only; slim Debian and Ubuntu images lack it, macOS uses ifconfig)

Optional

Tool Purpose
sshpass Optional SSH probe fallback
docker / colima Container appliance and kernel builds
xl2tpd L2TP LAC peer for the root-only L2TP PPP evidence tests (Linux only)
ppp (pppd) pppd for the same tests, which run on Linux, where setup installs it with apt. macOS ships /usr/sbin/pppd, so setup reports it present there. Debian installs it as root:dip mode 4754, so a user outside dip cannot run it; setup counts the file as present, because the tests run it as root

Platform Notes

macOS

  • The Homebrew prefix is resolved, never assumed. It is /opt/homebrew on Apple Silicon and /usr/local on Intel, so a hardcoded path is absent on half the Macs. Every consumer asks in the same order: HOMEBREW_PREFIX when brew shellenv has exported it, then the brew binary's own location (<prefix>/bin/brew), then the two documented defaults. The brew link is not followed: on Intel it points into <prefix>/Homebrew, which would answer with the wrong prefix. The docker-buildx step (Docker labs, below) is the one consumer that asks brew --prefix: it needs brew to install the formula anyway, and Homebrew's caveat for that formula names the same path.
  • e2fsprogs is keg-only on Homebrew, so none of it is linked onto PATH and which finds nothing however well it is installed. It is looked for under <prefix>/opt/e2fsprogs/sbin, the link kept at the current version, and under <prefix>/Cellar/e2fsprogs/<version>/sbin, where an interrupted upgrade leaves it with no link. No PATH modification is needed after brew install e2fsprogs.
  • grub has no first-party Homebrew formula. ISO builds require Linux or a container (colima/docker). The setup action skips grub on macOS.

Docker labs

A Docker lab runs Ze in containers, so the kernel it tests is the Docker host's, and that kernel has to carry every feature Ze enrolls. A lab is never judged on a kernel that lacks one.

  • macOS, the ze Colima profile: the labs run on the Colima profile ze, which boots Ze's docker-host image (Ze's runtime kernel, dockerd, containerd). ./le setup docker host start builds the image when needed and runs the profile, never touching Colima's default profile, then makes colima-ze the current Docker context so a plain docker reaches it. With DOCKER_HOST unset, every lab names the profile's socket, ze/docker.sock under Colima's home ($COLIMA_HOME when that directory exists, else ~/.colima), itself, whatever the current Docker context says; when that socket is absent the lab stops before it builds anything and names ./le setup docker host start. It never falls back to default or to Docker Desktop. A DOCKER_HOST you set is used as it is, and the lab's Docker kernel check judges that daemon. ./le setup docker host check names anything missing (colima, lima, docker, brew install e2fsprogs for mkfs.ext4), and ./le setup docker host stop stops it. The image build and the profile's lifecycle are in docs/architecture/appliance/docker-host.md.
  • macOS, the QEMU guest: the second route boots the same docker-host image under QEMU with HVF, on Ze's own arm64 runtime kernel, and runs the labs from the host le against the guest's dockerd through a forwarded socket. Build the kernel cache entry once with ./le build host-driver and then ./ze-host appliance kernel --target runtime --arch arm64 (the ./ze wrapper builds without appliance), then run a lab as ./le test qemu docker-lab lab "test integration interop-ipsec". With no lab the action stops after the guest's Docker kernel check.
  • Linux: the labs run on the host's own Docker, on a kernel that carries every registered feature. ./le setup docker kernel check asks the Docker daemon in hand and names each missing feature. It cross-builds the linux ze it probes with for the daemon's architecture (tmp/qemu/linux-<arch>/ze); ze <path> names another, which must be a linux executable for that architecture. ./le setup docker kernel install puts Ze's cached runtime kernel under /boot and makes it GRUB's default, one stated sudo step at a time. It needs GRUB_DEFAULT=saved in /etc/default/grub, never reboots, and refuses on macOS. A kernel built with --builder qemu on a host with Docker is installed with builder qemu, because the cache entry is keyed by backend. When the daemon applies AppArmor (Ubuntu's default), the check runs its probe under Ze's ze-kernel-probe profile, because Docker's docker-default denies what the probe does; ./le setup docker kernel apparmor confirm ze-kernel-probe installs and loads it, one stated sudo step at a time. The lab peers that write their network sysctls while they run (the VRRP scenarios' ze, strongSwan in some IPsec scenarios) run under the one generic profile ze-lab-net-sysctl the same way, loaded with ./le setup docker kernel apparmor confirm ze-lab-net-sysctl; the action with no confirm lists every profile and the steps each one runs.
  • BuildKit: the interop labs build some images with a named build context, which only BuildKit accepts, and the docker CLI reaches BuildKit through its buildx plugin. When docker is on PATH, setup runs a docker-buildx step that is judged by docker buildx version answering, never by a package being present. ./le setup check reports it MISSING and changes nothing. On macOS, ./le setup install runs brew install docker-buildx when brew does not hold the formula. It then adds $(brew --prefix)/lib/docker/cli-plugins to cliPluginsExtraDirs in the docker config, because the docker CLI does not search the Homebrew directory until the config names it. The config is $DOCKER_CONFIG/config.json when DOCKER_CONFIG is set, else ~/.docker/config.json. The edit keeps every other key and its value, adds no entry that is already there, refuses a file that is not a JSON object rather than replacing it, and replaces the file by rename after a sync. A symbolic link is followed, and a link to a file that does not exist is refused rather than replaced. With no home directory and no DOCKER_CONFIG the step refuses instead of writing a relative path. Each failure (brew cannot install, brew names no prefix, the plugin still does not answer) leaves the step pending with the reason and the next command to run. On a Mac with no Homebrew the step changes nothing and names https://brew.sh. On Linux the plugin is a root package and setup runs no sudo for it. The step names the package that matches the installed docker, docker-buildx-plugin beside Docker's docker-ce when dpkg reports it install ok installed, and docker-buildx beside the distribution's docker.io, with the sudo apt-get install line, and reports it pending. The lab's BuildKit refusal names ./le setup install as its fix. With no docker CLI the step is skipped.

docs/architecture/testing/qemu-integration.md, "Docker labs in the Ze-kernel guest", is the guest path; the scheduled nightly runs the same path on amd64 under KVM (docs/architecture/testing/ci-workflows.md).

Linux

./le setup install installs the apt packages itself, the same way it installs the Homebrew ones on macOS. Each command is echoed before it runs. It takes apt-get update once per run, because a container image ships no package lists, and it sets DEBIAN_FRONTEND=noninteractive so a package with a debconf prompt cannot stop the run.

How it reaches root. The answer is decided before any command runs, and sudo is always given -n, so no path can stop at a password prompt:

State What setup does
You are root (a container build) Runs the command directly. sudo need not be installed
sudo acts with no password Runs sudo -n <command>
sudo wants a password, a terminal is attached Asks once with sudo -v, then runs sudo -n <command>
sudo wants a password, no terminal (CI, an agent session) Prints the command, installs nothing, exits nonzero

GRUB follows your host architecture. Debian packages one module set per architecture: an amd64 host takes grub-efi-amd64-bin, an arm64 host takes grub-efi-arm64-bin. Asking an arm64 host for the amd64 package installs nothing at all, grub-mkstandalone included. ze appliance iso picks its GRUB target from the architecture of the image it packs, so building an ISO for the OTHER architecture needs that architecture's set too, through dpkg --add-architecture.

Unprivileged user namespaces. Ubuntu 23.10+ ships kernel.apparmor_restrict_unprivileged_userns=1, which blocks the sandbox Chrome relies on and makes the agent-browser web functional tests fail to launch Chrome (No usable sandbox!). It also breaks the kernel tests that run in a user namespace of their own (userns.Enter, see the testing guide): the namespace holds no capability, so each such test fails and its message names this check. Setup checks this tunable as userns-unrestricted. When it is restricted, ./le setup install echoes and then runs these commands via sudo to lift it globally:

echo "kernel.apparmor_restrict_unprivileged_userns = 0" | sudo tee /etc/sysctl.d/60-ze-userns.conf
sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0

The /etc/sysctl.d drop-in makes the change survive reboots. It goes through the same root route as the package installs, so on a root run the echoed lines carry no sudo, and when root is out of reach it prints the commands to run by hand instead. ./le setup check only reports the state, never changes it.

KVM device access. /dev/kvm is root:kvm mode 0660, so QEMU-backed evidence (the appliance boot proofs and every ze-qemu-* target) needs your user in the kvm group. Without it QEMU does not quietly fall back to emulation: it refuses to start with Could not access KVM kernel module: Permission denied, and the calling native QEMU action reports a timeout instead. Setup checks this as kvm-access and, in install mode, runs:

sudo usermod -aG kvm $USER

Group membership is fixed at login, so an existing shell keeps the old groups even after the command succeeds. Log out and back in, or run one command with the new group:

sg kvm -c './le test qemu vpp-hugepages'

Setup distinguishes the two states: kvm-access reports pending when the group database lists you but the running session predates it, and missing when the group is not granted at all. A host with no /dev/kvm (no hardware virtualisation, or a VM without nested virt) reports n/a: QEMU runs under tcg there, only slower. macOS has no /dev/kvm and needs no group; the native QEMU actions select the Apple hypervisor (hvf) by platform.

PPP device access. The L2TP and PPPoE tests open /dev/ppp to drive the kernel PPP channel. They run as you, in a user namespace of their own (userns.Enter), where root holds the CAP_NET_ADMIN the PPP ioctls need, and your supplementary groups still apply to the open. A stock Debian host makes the device root:root mode 0600, so a test run as you cannot open it, and the test fails naming ./le setup install and ppp-access. Setup checks this as ppp-access and grants the device to the dip group. Debian ships dip (gid 30) for PPP dial-up, pppd's documentation names it, and you are usually in it already, so a second group of Ze's own would grant the same device to the same person under another name. A host with no dip group gets one as a system group. In install mode setup runs only the steps whose piece is absent, in this order:

sudo groupadd --system dip
printf '%s\n' '# ./le setup install: the dip group may open /dev/ppp, for the L2TP and PPPoE tests.' 'KERNEL=="ppp", GROUP="dip", MODE="0660", OPTIONS+="static_node=ppp"' | sudo tee /etc/udev/rules.d/60-ze-ppp.rules
sudo udevadm control --reload
sudo modprobe ppp_generic
sudo chgrp dip /dev/ppp
sudo chmod 0660 /dev/ppp
sudo usermod -aG dip $USER

The rule keeps the grant across module loads and reboots: KERNEL=="ppp" applies when ppp_generic registers the device, and static_node=ppp applies at boot to the node systemd creates before the module loads (systemd grants /dev/kvm with the same line). The first open of that node loads the module. modprobe runs only when /dev/ppp does not exist. The node is changed with chgrp and chmod rather than udevadm trigger, because a static node with no module loaded has no device udev can act on.

ppp-access is present when your session can open /dev/ppp read-write. It is pending when the rule, the node and the group database are all in place but your session predates the membership: log out and back in, or run sg dip -c '<command>'. Otherwise ./le setup check reports it MISSING with the absent pieces, and ./le setup install grants them. The check judges the device with access(2) and does not open it, because opening /dev/ppp loads ppp_generic and a check changes nothing. When root is out of reach, the install prints the commands above with sudo instead of running them. macOS reports the step skipped: it has no /dev/ppp, and the PPP tests run in the Linux VM.

Kernel features. A test that needs a kernel feature runs on Ze's kernel, which carries it. The nftables flowtable test needs NF_FLOW_TABLE, NF_FLOW_TABLE_INET and NFT_FLOW_OFFLOAD, and the tc ingress policer tests need NET_ACT_POLICE and NET_ACT_GACT. Ze's kernel builds all five in (gokrazy/kernel/kernel.config and runtime.config). A distribution kernel may build them as modules or not at all, and the kernel then answers the test with a bare no such file or directory. The test still fails, never skips, and its failure adds a line for each option the running kernel lacks or has not loaded: the kernel release, the option, and the fix. The fix is to boot Ze's kernel (on a Linux host, ./le setup docker kernel install, then reboot) or, for a module that is built but not loaded, sudo modprobe <module>. The options are read from /proc/config.gz, else /boot/config-<release>, and the loaded modules from /proc/modules. Setup does not load these modules.

Loopback addresses. The functional fixtures give each end of a BGP session its own address: RFC 4271 Section 5.1.3 forbids a peer its own address as NEXT_HOP, so a session whose two ends share one address has every originated route withheld. IPv4 spends 127.0.0.0/8, which Linux already routes to lo and macOS does not, so setup adds 127.0.0.2 through 127.0.0.6 there. IPv6 gives a host exactly ::1 on every platform. Setup adds fd00::2/128 for the speaker and next-hop owner, fd00::3/127 for the recipient, and fe80::1 as the next-hop owner's link-local. macOS already carries fe80::1/64 on lo0 from boot, so setup adds fe80::1/128 only where it is absent, normally on Linux. The one connected prefix fd00::2/127 contains exactly the two unique-local addresses. This makes the RFC2545 compatibility fixture's common-subnet condition real without routing all of fd00::/64 locally. Setup checks this as loopback-addresses and, in install mode, runs:

sudo ifconfig lo0 inet6 fd00::2/128 alias      # macOS
sudo ifconfig lo0 inet6 fd00::3/127 alias
sudo ifconfig lo0 inet6 fe80::1/128 alias      # only if lo0 lacks fe80::1
sudo ip -6 addr add fd00::2/128 dev lo         # Linux
sudo ip -6 addr add fd00::3/127 dev lo
sudo ip -6 addr add fe80::1/128 dev lo

Presence requires a successful socket bind. IPv6 additionally requires the address on lo (lo0 on macOS), and the unique-local pair at its exact prefix; an address elsewhere, or fd00::3/128, does not establish this fixture's common subnet. fe80::1 is ready at any prefix length, because the fixtures use it only as a next hop and bind address, and its bind probe includes the interface zone. An unreadable interface fails the ownership check closed. Setup never silently removes an existing address with a different prefix: resolve a conflicting assignment explicitly if the add command fails.

These changes require an explicit setup install or the commands above. setup check and test runners do not change host networking. Every command that starts a functional suite (./le test functional, ./le verify worktree, ./le verify current) runs this same check before it builds or runs anything, and refuses to start when an address is missing. The refusal names each missing address and the commands above that add it (FunctionalHostPreflight). The runners' own per-test probes stay, and check bindability only.

These additions do not survive a reboot. Re-run ./le setup install after one; ./le setup check says when it is needed. The merge gate adds the same IPv6 addresses and prefix in .github/workflows/verify.yml.

These three, and the apt installs above, are every place setup reaches for root. All of them go through one helper, so the table of states earlier in this section governs each of them.

After Setup

Check that the checkout builds and its tests run with one scoped package test:

./le test unit pkg path ./internal/core/textbuf/

It runs the package's tests under the feature tags with the race detector, admitted as a job, and a green run answers one line counting the packages that passed and naming the log it wrote (../contributing/running-commands.md, "Testing one package while you develop it").

./le verify changed is the day-to-day evidence once you have a change: it judges only the change set against the upstream, so on a fresh clone it judges nothing and proves nothing about the setup.

The full verification, ./le verify current, is Thomas's release check. It refuses unless stdin and stdout are a terminal, so it is started by hand at one when a release needs it, never from an agent or a script.

Check that appliance tools are detected:

./le setup check

Drift Guard

The dev setup action and ze doctor appliance checks share the same tool list. A Go test (TestDevSetupMatchesDoctor in internal/appliance/dev_setup_drift_test.go) fails if they disagree, preventing the lists from drifting apart.