Chapter 12
Development
Everything is a Nix flake. One command checks the whole project:
nix flake check # format, statix, deadnix, ruff, mypy, unit tests, the runtime's scenario
# matrix, every board evaluated (with and without the runtime),
# VM tests (base, update/rollback, installer on vm and pc, runtime)
nix fmt # nixfmt on every .nix file
nix develop # a shell with nixfmt, statix, deadnix, ruff, python3 with numpy and mypy
The runtime has its own check, which runs without a VM in under a minute: nix build .#checks.x86_64-linux.omarchy-runtime. Inside nix develop, from pkgs/omarchy-runtime, python3 -m unittest discover -s tests -t . runs the same tests. AGENTS.md lists the runtime’s binding principles and how to add an extension.
The VM tests need the nixos-test system feature in nix.conf; with kvm and /dev/kvm they run under KVM, without them under QEMU’s emulation (TCG), several times slower. Every check, build, experiment and release check runs locally (AGENTS.md, “Checks and releases”): the relevant checks after each change, the full nix flake check on the commit to tag before every release. The GitHub workflows are manual-only and run nothing by themselves. nix build .#checks.x86_64-linux.manual builds this manual (open result/index.html) and fails if a page keeps Markdown as text.
What you can build
Every artifact comes from robot.nix. <board> is any Jetson board.
| Command | Artifact |
|---|---|
nix build .#nixosConfigurations.robot.config.system.build.toplevel |
the robot’s system, as robot.nix declares it |
nix build .#nixosConfigurations.<board>.config.system.build.toplevel |
the same system on <board> |
nix build .#flash or .#flash-<board> |
the firmware flash script (x86_64 host, USB recovery mode) |
nix build .#packages.aarch64-linux.installer or .installer-<board> |
the installation image for a Jetson, carrying its system |
nix build .#installer-vm or .#installer-pc |
the installation image for the vm or pc board |
nix build .#vm |
the vm board as a QEMU VM (nix run .#vm) |
nix build .#omarchy-robot |
the command alone |
nix build .#omarchy-runtime |
the runtime alone; nix run .#omarchy-runtime -- demo runs it |
.#flash and .#installer follow the board set in robot.nix. With board = "vm" or "pc", only .#installer exists.
Building a Jetson system on an x86_64 host needs extra-platforms = aarch64-linux and a QEMU binfmt handler (on NixOS, boot.binfmt.emulatedSystems = [ "aarch64-linux" ]). There is no public binary cache for jetpack-nixos, so the Tegra kernel compiles under emulation the first time.
Layout
flake.nix inputs pinned in flake.lock; every output
robot.nix the one file a user edits
modules/ options, base, identity, jetson, vm, pc, runtime, installer, boards, branding
pkgs/omarchy-robot/ the command, its unit tests and fixtures
pkgs/omarchy-runtime/ the runtime: contracts, control plane, simulator, scenarios, tests
tests/ checks and VM tests
branding/ logo and wordmark
manual/ this manual
Versions
Before 1.0, releases count up: v0.0.1, v0.0.2, v0.0.3, v0.1.0. A new release comes only with a major feature. v0.1.0 is the first board booted and validated on hardware, a Jetson AGX Orin developer kit. The validate report schema and the runtime’s trace schema are versioned separately. Each release’s changes are in the CHANGELOG, and each change in detail in the commit history.
This manual
The pages are Markdown in manual/, one file per chapter, listed in order in manual/_data/chapters.yml. A push to main that touches manual/ publishes it to GitHub Pages. When a change in the code makes a page wrong, fix the page in the same commit.
License
MIT. jetpack-nixos is MIT too. The NVIDIA components it packages are under NVIDIA’s licenses: they are built locally and never redistributed here.