nami is one program. It reads your YAML, downloads ready-built packages from nixpkgs’ binary cache, checks them, and links them into place. It never runs Nix’s evaluator to install something, and it has no packages of its own: everything comes from nixpkgs or from a recipe. Where each piece lives is in Files on disk.
The catalog
Turning a name like ripgrep into a store path normally means evaluating the Nix language. nami does this once per nixpkgs release, ahead of time, for everyone, and writes one index: every package’s store paths, version, description, licence and apps. On your computer, nami install ripgrep is a lookup in that file.
Next to the index are app icons, build definitions, and every version each package has had (for firefox@150). Nix only runs on your computer for nami import of a flake.
The signature
Whoever controls the catalog decides what nami install firefox means, so nami only takes a catalog signed by a key the computer trusts; the installer adds the publisher’s key. The index carries the sha256 of every build definition and icon, so that one ed25519 signature vouches for all of them. An unsigned catalog is accepted only with nami update --unsigned.
Channels and pins
A channel is a small file naming the current release. nami records both the channel, to follow later, and the exact index it got, so a lock can pin a catalog that never changes. The last few catalogs are kept, so a project pinned to an older one still finds it.
A signed catalog can also name binary caches of its own, for apps that aren’t in nixpkgs, and nami downloads from them too. This adds no trust: the catalog’s signer already decides what every name means.
The store
Everything nami installs is in /nix/store, one read-only folder per package build, named by a hash of how it was built: /nix/store/<hash>-ripgrep-15.2.0. Two versions of a library are two folders, so nothing overwrites anything.
The store can’t move: nixpkgs programs have /nix/store/... written into their library paths, ELF interpreter and shebangs. That’s also why the same bytes run on any distribution: they bring their own C library and never look in /usr/lib. On distributions with a read-only root (Silverblue, SteamOS), the installer mounts /var/lib/nami/nix at /nix.
Downloading
nami speaks the binary cache protocol directly. Each path’s .narinfo lists its dependencies and must be signed by a trusted key (cache.nixos.org’s is built in); each archive must match the narinfo’s hash, and is unpacked into a temporary folder and renamed into place. Caches are asked in order: cache.nixos.org, then root’s caches:, then the catalog’s.
Only when the whole closure is unpacked does nami record the paths in its own database, so an interrupted run leaves nothing half-installed. nami never touches a store path it didn’t register.
Profiles and changes
A profile is what’s on your PATH. Every install, remove, apply or undo makes a new change, which Nix calls a generation: a tree of links merging every package, links to the dotfiles, units and /etc files that change renders, and a manifest saying what it holds.
default is a link to the current change. Switching is one atomic rename of that link, so there’s never a moment with half the old apps and half the new. nami undo switches back.
The computer’s profile is root’s and the admins’. Everyone else has a profile of their own, first on PATH and in the app menu, and manages its changes without root; only writing to the store goes through the daemon.
Graphics drivers
On another distribution, a nixpkgs app finds no GPU drivers, because they’re in /usr/lib, which it never reads. So when a package needs graphics, the computer’s profile gets a runtime with nixpkgs’ mesa, fontconfig and locales (plus the host’s NVIDIA libraries, which must match its kernel module), linked at /run/opengl-driver, where NixOS keeps them.
The daemon
Only root writes to the store. Everyone else talks to nami daemon, a root service the installer sets up. Following Nix’s model, it only offers operations that can’t plant something under a path another person trusts:
| Operation | Why it’s safe |
|---|---|
| Download paths | Only from caches root trusts, signatures checked. |
| Add a file, run a build, replace a library | The daemon works out each store path from the content or the whole job. |
| Build a catalog package | The request names a package: only what the signed catalog describes is built. |
| Run a command, for admins | The kernel says who’s on the socket, and they must be in wheel, sudo or admin. Changing the computer’s file also asks for the admin’s password (polkit). |
People’s files are read by nami running as them, so nothing only root can read ends up in the store, which everyone can read.
What nami apply does
- Check the file. Every problem is listed and nothing changes.
- Resolve each package. A locked name keeps its paths; a new one is looked up in the catalog; a recipe is built or downloaded. A package the catalog no longer has is left out, with a message.
- Replace libraries and render your home files, units and
/etcfiles into the store. - Commit. Download everything and write the new change.
- Switch. The graphics runtime, then
default, then the app menu and your home’s links. Units that go away stop,/etcfiles are written, new units start and changed ones restart. - Write
nami.lockif it changed, and prune old changes whenhistory:says so.
--dry-run stops before the commit and says what would change. On namiOS, applying the computer’s file makes a new system instead; see A whole computer.
Building
A nixpkgs build is bash, stdenv/setup and a set of environment variables, and stdenv and the compilers are ordinary store paths in the binary cache. So nami writes the variables from a recipe and runs nixpkgs’ own builder, and every nixpkgs hook works unchanged.
Builds run in bubblewrap, with only the inputs visible and no network, except for downloads with a known hash. The output path is a hash of the whole job, so the same recipe gives the same path on every computer. Before building, nami asks your caches for that path, and downloads it if someone already built and pushed it (Share builds).
A recipe that extends: a nixpkgs package starts from that package’s build definition in the catalog, checked against the signed index. Every input stays the nixpkgs path, so only the changed package is built.
Unfree packages aren’t on cache.nixos.org, because Hydra doesn’t build them. For those, the catalog carries everything needed to build them, and nami builds them at exactly the paths nixpkgs gives them.
replace: swaps a library in the packages that use it without building them again: nami copies each one with the old library’s store path written over by the new one’s, as NixOS’ replaceDependency does. It checks first that the bytes still fit: the same path length, and every shared library and symbol of the old one in the new one.
Cleaning up
nami gc deletes old changes by the rules you give, then every registered store path that no change, no existing project folder, no namiOS system and no running program still uses (what a process runs, has open, has mapped or has in its environment, read from /proc, as Nix’s runtime roots). It unregisters a path before deleting it. Only root deletes store paths (an admin through the daemon); anyone else’s nami gc deletes their own old changes.
The daily update cleans up first (nami gc --auto, as root, at low priority): old changes as cleanup: says (older than 30 days, the current one and the newest 3 kept), the computer’s from computer.nami and each person’s from their own user.nami (run as them), then the store paths nothing uses, sparing those registered in the last hour (an install that hasn’t made its change yet). On namiOS the computer’s changes are its systems: one goes with its kernel and boot entries, never the one running, the one it started as, the one before it or what starts next. When the disk with /nix has less than 10% or 5 GB free, the daily update and nami apply clean up early, whatever the age.
Next to Nix
When Nix is installed, its store is its own and nami goes through it. Downloads use nix-store --realise, so Nix checks the signatures, and what nami builds is handed to nix-store --import. Every path nami uses gets a garbage-collector root, so nix-collect-garbage leaves nami’s apps alone. The paths are the same byte for byte, so nothing is downloaded twice. NAMI_NIX=off turns this off. Coming from Nix is in Install nami.
Bundles
nami bundle writes a small static runtime followed by the program’s whole closure, down to glibc. Started, the runtime unpacks what isn’t there yet into one store all bundles share, ~/.cache/nami-bundle/store. Instead of patching programs, it replaces the bytes /nix/store with a /tmp/ path of exactly the same length as it unpacks, and makes that path a link to its store, so nothing inside any program moves. Then it finds the host’s graphics drivers and starts the program with the bundle’s own glibc. More in Ship your app.
A whole computer
nami usb builds a drive that starts a whole computer from a computer file. It isn’t NixOS and needs no Nix: the kernel, systemd, the desktop and the apps come ready-built from the binary cache, and nami writes the boot setup, /etc, the users and the disk image (as a tar stream, turned into ext4 without root).
One version of the computer is one folder, /nix/var/nami/os/system-N: every package merged into one tree, the kernel and its modules, firmware, graphics drivers, an initrd, /etc files, systemd units, and the scripts that start it. The layout is the one nixpkgs’ programs expect (/run/current-system/sw, /run/wrappers, /run/opengl-driver), so none of them needs changing.
At start, a small initrd reaches the disk, asks for the password if it’s encrypted, and hands over to activate, which points /run/current-system at the system, links each file into /etc (a file someone changed stays as it is), and brings the people in line with the file. With Secure Boot, it starts the way Ubuntu does: shim, signed by Microsoft, starts systemd-boot and kernels signed with the computer’s own key, which you enroll with MokManager on the first start.
Applying the computer’s file on namiOS builds system N+1 next to the running one, adds it to the boot menu and starts what’s new; a new kernel is used from the next start. A new entry gets three tries, and if it doesn’t start, the one before starts instead. The newest four systems are kept: hold Space as the computer starts to pick an older one. Updates come by themselves once a day and only change what the next start brings.
Each computer has its own age key. An /etc file with a secret stays sealed in the system, and is opened with that key into /run/nami/secrets/ as the computer starts. nami install-to copies the running system from the USB drive onto a disk, with its people, their files and Wi-Fi networks (Make your own computer).
nami itself
The web installer downloads the newest release, checks it against the release’s SHA256SUMS, and runs its setup.sh, which installs the binary and the daemon, then trusts and fetches the catalog. nami self-update trusts a release the way it trusts a catalog: SHA256SUMS must be signed by a catalog key the computer already trusts.
Limits
- x86_64 Linux only, for now.
services:needs systemd. Without it, services are left out with a message and everything else still comes up.- On a distribution nami didn’t install, changes don’t cover the rest of
/etc, the distribution’s own packages, its users or its kernel.