Set up development

Use this guide to choose the smallest environment for your change. Atlas app work needs a Frappe site. Metal and WG Mesh work needs Linux host features.

Local setup is a work in progress

The local setup guides are not fully verified. Steps can be incomplete or change. Ask the team if a step does not work.

If this is your first change, read how a VM request works. Then use the code map to find the owner and its tests. Choose a setup below for that owner.

Follow a change through the system

1. Read the topic's handbook page to learn the request path, saved state, and failure path. The architecture shows which component owns each part.
2. Use the code map to find the owner, its nearby SPEC.md, and the first test to read.
3. Follow the input from its API or job to the saved record and the worker that applies it. For example, the firewall guide follows a network request to the host rule update.
4. Change the owning component and run its focused tests. Use host tests when Linux, ZFS, KVM, or packet behavior matters. Update the authoritative handbook page when behavior changes.

Choose an environment

Work	Start here	Needs
Atlas app, DocTypes, and placement	Atlas development	Frappe, MariaDB, Redis, and a site
Metal code and VM runtime	Metal development	Go and Linux host tools
Metal integration tests	Metal testing	Linux, root, KVM, ZFS, systemd, and iptables
HTTP proxy	Proxy development	Python 3.14 and OpenResty test tools
WG Mesh	WG Mesh development	Linux, Go, Clang, libbpf, and a test host for packet checks
IPv6 router	Router design and specification	Clang and a gateway VM for live checks

Run documentation locally

Install the Node dependencies, then start the VitePress server:

npm install
npm run docs:dev

Build the site before you open a pull request:

npm run docs:build

VitePress reads Markdown from the repository. Do not edit .vitepress/dist by hand.

Write documentation

Explain behavior, reasons, and recovery once in the matching handbook section under docs/. Keep code contracts in a nearby SPEC.md and link to the handbook. A short README.md can link to both.

Put a new page in reading order in .vitepress/sidebar.mts. Keep source-code links in a details block at the end of the page. The docs-build/internal/ files are background research and are excluded from the site.

Before you submit a change

• Read the nearest component SPEC.md before a structural change.
• Run the formatter and focused tests for the component.
• Run npm run docs:build when you change documentation or the VitePress configuration.
• Keep each page focused on one reader task.