nami keeps almost everything in the store, /nix/store, and its own state in /nix/var/nami. The rest are links and small files where other programs look for them. How the pieces fit together is in How it works.
Your nami files
| Path | What it is |
|---|---|
/etc/nami/computer.nami | The computer’s file. Root writes it and admins read it (mode 640), because it can hold passwords. |
/etc/nami/nami.lock | The computer file’s lock. |
/etc/nami | A link to /etc/nami-config/<computer>, laid out like a config repo, so package folders sit next to it. |
~/user.nami | Your file. With a config repo, a link into your checkout. |
~/.config/nami/nami.lock | Your file’s lock, when ~/user.nami is a plain file. |
~/.config/nami/ | Your config repo’s checkout, when you set up from one. |
project.nami, nami.lock | A project’s file and its lock, in the project’s folder. |
.nami-recipients | Who can open a repo’s secrets. Looked for up to the top of the git repo. |
Every nami file’s lock is nami.lock in the same folder. In a config repo’s checkout, nami keeps this computer’s own files (age.key, secrets.env, env.sh, shell.*) out of git with .git/info/exclude.
The store
| Path | What it is |
|---|---|
/nix/store/<hash>-<name> | Packages, read-only, shared by everyone on the computer. |
/nix/store/.nami-tmp-*, .nami-build-*, .nami-stage-* | Downloads and builds in progress, renamed into place when done. |
On distributions with a read-only root (Silverblue, Kinoite, SteamOS), the store lives in /var/lib/nami/nix, mounted on /nix by /etc/systemd/system/nix.mount.
/nix/var/nami
nami’s own state. Owned by root; everyone else changes it through the daemon.
| Path | What it is |
|---|---|
index.json | The catalog in use. |
index-source, index-resolved | Where the catalog comes from, and the exact index a channel pointed at. |
catalog-keys.json | Keys the catalog and nami’s releases must be signed by. |
catalog-caches.json | Binary caches the signed catalog names. |
menus/<sha256>.json | The last few catalogs, for projects pinned to an older one. |
icons/, drvs/ | App icons and build definitions, fetched as needed. icons-source, drvs-source and versions-source say where from. |
db/<hash>-<name>.json | One record per store path nami put there. Paths without one are never touched. |
caches.json | The binary caches root’s caches: lists. |
builds/, logs/<path>.log | Builds while they run, and each build’s log. |
sources/, plates/, remote/ | Root’s caches: unpacked .deb sources, nami shell setup scripts, github: packages. |
layers/ | Layers root’s files include from git repos. |
profiles/default, default-N/ | The computer’s current change, and change N. |
profiles/default-N.json | Change N’s manifest. default-N.config.json is the file it came from, readable only by its owner. |
profiles/runtime, runtime-N/ | Graphics drivers, locales and fonts for graphical apps. |
profiles/projects/ | Projects whose packages nami gc keeps while their folder exists. |
profiles/per-user/<login>/ | Each person’s own profile, laid out the same way. |
units.json, etc-files.json | System units and /etc files nami wrote, with their hashes, so hand edits can be told apart. |
bin/nami | The program. /usr/local/bin/nami links to it. |
daemon.sock | The daemon’s socket. Anyone may ask; the daemon decides. |
uninstall.sh | Removes nami (below). |
staging/ | With Nix installed only: builds waiting for nix-store --import. |
With Nix installed, /nix/var/nix/gcroots/nami/ also holds a root for every store path nami uses.
In your home
| Path | What it is |
|---|---|
~/.local/state/nami/profile | Link to your profile. Shells and the desktop find your apps through it. |
~/.local/state/nami/home-files.json, units.json, settings.json | The home files, user units and desktop settings nami set, so it can undo exactly those. |
~/.config/nami/env.sh | Your env: and aliases:, for sh, bash and zsh. |
~/.config/nami/shell.bash, shell.zsh, login.bash | Your shell: lines, and what starts your login shell from bash. |
~/.config/nami/secrets.env, secrets.fish | Your secret env: values, opened, mode 0600. |
~/.config/nami/age.key | Your key for secrets, if nami made you one. |
~/.config/fish/conf.d/nami-home.fish, nami-shell.fish | The same settings for fish. |
~/.config/environment.d/60-nami-home.conf, 61-nami-secrets.conf | Your env: for the graphical session. |
A marked line at the end of ~/.bashrc and ~/.zshrc | Sources env.sh last, so your settings win over the distribution’s. |
~/.config/systemd/user/ | Your services’ units. |
~/.local/share/applications/<app>.desktop | Menu entries for your apps, marked X-Nami-Managed=true. |
~/<file> | Each home file nami manages: a link into your profile, or a private real file when it holds a secret. A file in the way is kept as <file>.nami-backup. |
~/.cache/nami/ | Caches, layers and nami usb builds. Safe to delete. |
~/.cache/nami-bundle/ | The store all bundles share. |
The XDG_* variables move these as usual: $XDG_CONFIG_HOME/nami, $XDG_CACHE_HOME/nami, $XDG_DATA_HOME/applications.
What the installer adds
| Path | What it is |
|---|---|
/etc/profile.d/nami.sh | PATH, XDG_DATA_DIRS and the rest for login shells: your profile first, then the computer’s. |
/etc/bash.bashrc or /etc/bashrc | One line that sources ~/.config/nami/env.sh. |
/etc/environment.d/50-nami.conf | The same variables for graphical sessions, which puts apps in the menu. |
/etc/tmpfiles.d/nami.conf | Recreates /run/opengl-driver at every boot. |
/etc/systemd/system/nami-daemon.service | The daemon. OpenRC: /etc/init.d/nami-daemon; runit: /etc/sv/nami-daemon. |
/usr/local/share/bash-completion/completions/nami, /usr/local/share/zsh/site-functions/_nami, /etc/fish/completions/nami.fish | Tab completion for each shell you have. On namiOS: /etc/bashrc.d/nami-completions.sh, /etc/zshrc.d/nami-completions.zsh and /etc/fish/completions/nami.fish. |
On Fedora and RHEL the installer also labels /nix/store for SELinux. On NixOS it only uses the files NixOS leaves for local additions (/etc/profile.local and the like) and puts the daemon in /etc/systemd/system.control/.
What applying writes
| Path | Written for |
|---|---|
/usr/local/share/applications/<app>.desktop | Menu entries for the computer’s apps. |
/etc/systemd/system/<name>.service (and .socket, .timer, .path) | The computer’s services, as copies. A unit in the way is kept as .nami-backup. |
/etc/systemd/system/<name>.service.d/ | Your changes to a package’s unit. |
Paths under /etc | The computer’s files:. |
/run/opengl-driver | Link to the graphics runtime. |
<project>/.nami/ | nami up’s services: state, pid files and logs. |
/run/nami/secrets/ | On namiOS, /etc files with secrets, opened into memory at start. |
namiOS
namiOS has the paths above, plus its system.
| Path | What it is |
|---|---|
/nix/var/nami/os/system-N/ | System N: its packages, kernel, initrd, firmware, /etc, units and start scripts. The newest four are kept. |
/run/current-system, /run/booted-system | Links to the system in use and the one the computer started with. |
/run/wrappers/bin | Programs that run as root, such as sudo. |
/etc/static | Link to the system’s etc/. Each file in /etc links through it, unless someone changed it. |
/lib64/ld-linux-x86-64.so.2 | So programs built for other distributions start. |
/var/lib/nami/etc/ | Hashes of /etc files that must be real copies. A changed one is kept, with the system’s version next to it as .nami-dist. |
/var/lib/nami/locked-people | People taken out of the file: locked out, their files kept. |
/var/lib/nami/seed/ | What the namiOS Installer left for the first start, until it’s applied. |
/etc/nami/repo | The config repo the computer was made from. |
/etc/nami/<login>/ | That person’s folder, readable by them and the admins. |
/etc/nami/computer.flat.nami | The whole computer in one file, generated. |
/nix/var/nami/secrets/age.key | The computer’s own key for secrets, root’s alone. |
/nix/var/nami/secure-boot/ | The computer’s Secure Boot key. |
On the boot partition (/boot):
| Path | What it is |
|---|---|
EFI/BOOT/BOOTX64.EFI | systemd-boot, or shim with Secure Boot. |
nami/N/kernel, nami/N/initrd | System N’s kernel and initrd. |
loader/entries/nami-N.conf | System N’s boot entry. A new one has three tries. |
nami usb works in ~/.cache/nami/os/, and keeps each computer’s secrets and Secure Boot keys there for its next drive.
Environment variables
| Variable | What it does |
|---|---|
NAMI_NIX=off | Don’t use an installed Nix’s store; manage /nix/store directly. |
NAMI_THEME | The nami app: dark or light, instead of following the desktop. |
NAMI | The nami app: the nami program to run. |
NAMI_DISK_PASSWORD | nami install-to --encrypt in a script: the disk’s password. |
NAMI_USB_BINARY | nami usb: the static nami to put on the drive. |
NAMI_OS_DIR | nami usb: an absolute folder to build in instead of ~/.cache/nami/os. |
NAMI_BUILD_DEBUG=1 | Builds trace every command into the log. |
NAMI_IMPORT_NIX | nami import: 0 never uses Nix; an absolute path is the nix to run. |
NAMI_GITHUB_MIRROR | Read github: packages from a local mirror folder. |
NAMI_LAYERS_DIR | Keep fetched layers in this folder. |
NAMI_ROOT | Use this folder as /, for tests. Your home isn’t moved. |
NAMI_CHANNEL, NAMI_KEY | The installer: the catalog channel, and the key it’s signed with. |
NO_COLOR | The web installer prints without colours. |
Inside a project’s environment, nami sets NAMI_PROJECT to the project’s folder. It also reads the usual HOME, XDG_*, SHELL (for nami shell) and VISUAL or EDITOR (for nami secret edit).
Removing nami
sudo sh /nix/var/nami/uninstall.sh
This stops the daemon, deletes the store paths nami registered (and nothing else in the store), deletes /nix/var/nami, and removes what the installer added. Your nami files and ~/.local/state/nami stay (Install nami).