Repository layout

The tree

• Directoryvirtainer-lite/

  • Directorysrc/ — the agent: one Rust crate, the daemon that owns the host

    • Directoryapi/ — HTTP routes and handlers; src/api/mod.rs is the route table

      • …
    • Directoryauth/ — accounts, sessions, CSRF, API keys

      • …
    • Directoryvm/ — VM and AppVM lifecycle, one Cloud Hypervisor process each

      • …
    • Directorystorage/ — pools, volumes, the AppVM image store

      • …
    • Directorynet/ — host networking: the desired state, realization, taps, nftables

      • …
    • Directorycloud_init/ — the cidata seed handed to each VM

      • …
    • metrics/, diagnostics/ — the in-house RRD and the diagnosis surface
    • system_bootc.rs, host_update.rs — the host’s own image and upgrade state
    • webui.rs — rust-embed: the compiled console lives in here
  • Directoryweb/ — the React console. Builds to web/dist/, embedded into the binary

    • …
  • Directoryvmkit-init/ — guest PID 1 for AppVMs, a second workspace member

    • …
  • Directoryvmkit-wire/ — the protocol between the agent and the guest init, the third workspace member

    • …
  • Directorymigrations/ — SQLite roll-forward migrations, compiled into the binary

    • …
  • Directorytools/ — build, release, acceptance and source-gate scripts

    • …
  • Directorydocs/ — design, decisions, operating manual, acceptance procedure, reports

    • …
  • Directorytests/ — Rust integration tests, including the host-requiring ones

    • …
  • Directorypackaging/bootc/ — the Containerfile for the whole-machine image

    • …
  • Directorytests/fixtures/ — recorded shapes the contract tests run against

    • …

The Cargo workspace has three members: the virtainer agent plus vmkit-wire and vmkit-init. The guest init is built for x86_64-unknown-linux-musl and is statically linked on purpose: it is the first process in a machine whose root filesystem may be a single compressed archive.

What is compiled in, not copied in

Three things that look like runtime files are actually inside the binary:

Content	Mechanism	Consequence
The web console	#[folder = "web/dist/"] in src/webui.rs	A missing web/dist fails the Rust build rather than shipping a UI-less binary
Database migrations	sqlx::migrate!	A release cannot run against a schema it does not carry
The SELinux policy module	include_str! of tools/selinux/virtainer.cil	The agent loads it at first start; there is no policy file to lose

This is why the host image recipe contains exactly one copy instruction for product content. If you are looking for a file in the image and cannot find it in the recipe, check whether it is embedded.

Which document answers which question

The repository keeps one home per kind of answer, so a change has exactly one place to land. docs/handbook/README.md is the index; it deliberately points at sources instead of restating them, because a summary of the code drifts the moment it is written.

Question	Authoritative source
Why is it this way, and what was rejected	docs/adr/, one decision per numbered file
What is it: boundaries and invariants	docs/DESIGN.md and the DESIGN-*.md set
How it is operated, and the API surface	docs/USAGE.md
What changed in behaviour	CHANGELOG.md
How a release gets accepted	docs/RELEASE-ACCEPTANCE.md
Method for asking a question the repo cannot answer	docs/runbooks/
How it is actually written	src/

Caution

When a document and the code disagree, the code is right and the document is a defect to fix in the same change. docs/handbook/README.md states that rule and sends the repair through the design-change flow in docs/CONTRIBUTING.md, and tools/check-current-contract.sh exists to catch retired names and dead ADR links before they settle in.

Decisions are permanent

docs/adr/ holds over a hundred Architecture Decision Records. Each has a number that never gets reused. A decision is never edited into a new position: when one is reversed, the old file is marked Superseded by and a new ADR states the new position. Reading a decision therefore always tells you both what is currently true and what was tried and given up, which is the part that stops a team from re-deciding the same thing twice.