nami alpha Docs

Files on disk

Look up every path nami reads or writes, the environment variables it reads, and what removing it takes away.

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

PathWhat it is
/etc/nami/computer.namiThe computer’s file. Root writes it and admins read it (mode 640), because it can hold passwords.
/etc/nami/nami.lockThe computer file’s lock.
/etc/namiA link to /etc/nami-config/<computer>, laid out like a config repo, so package folders sit next to it.
~/user.namiYour file. With a config repo, a link into your checkout.
~/.config/nami/nami.lockYour 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.lockA project’s file and its lock, in the project’s folder.
.nami-recipientsWho 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

PathWhat 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.

PathWhat it is
index.jsonThe catalog in use.
index-source, index-resolvedWhere the catalog comes from, and the exact index a channel pointed at.
catalog-keys.jsonKeys the catalog and nami’s releases must be signed by.
catalog-caches.jsonBinary caches the signed catalog names.
menus/<sha256>.jsonThe 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>.jsonOne record per store path nami put there. Paths without one are never touched.
caches.jsonThe binary caches root’s caches: lists.
builds/, logs/<path>.logBuilds 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.jsonChange 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.jsonSystem units and /etc files nami wrote, with their hashes, so hand edits can be told apart.
bin/namiThe program. /usr/local/bin/nami links to it.
daemon.sockThe daemon’s socket. Anyone may ask; the daemon decides.
uninstall.shRemoves 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

PathWhat it is
~/.local/state/nami/profileLink to your profile. Shells and the desktop find your apps through it.
~/.local/state/nami/home-files.json, units.json, settings.jsonThe home files, user units and desktop settings nami set, so it can undo exactly those.
~/.config/nami/env.shYour env: and aliases:, for sh, bash and zsh.
~/.config/nami/shell.bash, shell.zsh, login.bashYour shell: lines, and what starts your login shell from bash.
~/.config/nami/secrets.env, secrets.fishYour secret env: values, opened, mode 0600.
~/.config/nami/age.keyYour key for secrets, if nami made you one.
~/.config/fish/conf.d/nami-home.fish, nami-shell.fishThe same settings for fish.
~/.config/environment.d/60-nami-home.conf, 61-nami-secrets.confYour env: for the graphical session.
A marked line at the end of ~/.bashrc and ~/.zshrcSources env.sh last, so your settings win over the distribution’s.
~/.config/systemd/user/Your services’ units.
~/.local/share/applications/<app>.desktopMenu 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

PathWhat it is
/etc/profile.d/nami.shPATH, XDG_DATA_DIRS and the rest for login shells: your profile first, then the computer’s.
/etc/bash.bashrc or /etc/bashrcOne line that sources ~/.config/nami/env.sh.
/etc/environment.d/50-nami.confThe same variables for graphical sessions, which puts apps in the menu.
/etc/tmpfiles.d/nami.confRecreates /run/opengl-driver at every boot.
/etc/systemd/system/nami-daemon.serviceThe 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.fishTab 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

PathWritten for
/usr/local/share/applications/<app>.desktopMenu 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 /etcThe computer’s files:.
/run/opengl-driverLink 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.

PathWhat 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-systemLinks to the system in use and the one the computer started with.
/run/wrappers/binPrograms that run as root, such as sudo.
/etc/staticLink to the system’s etc/. Each file in /etc links through it, unless someone changed it.
/lib64/ld-linux-x86-64.so.2So 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-peoplePeople 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/repoThe config repo the computer was made from.
/etc/nami/<login>/That person’s folder, readable by them and the admins.
/etc/nami/computer.flat.namiThe whole computer in one file, generated.
/nix/var/nami/secrets/age.keyThe 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):

PathWhat it is
EFI/BOOT/BOOTX64.EFIsystemd-boot, or shim with Secure Boot.
nami/N/kernel, nami/N/initrdSystem N’s kernel and initrd.
loader/entries/nami-N.confSystem 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

VariableWhat it does
NAMI_NIX=offDon’t use an installed Nix’s store; manage /nix/store directly.
NAMI_THEMEThe nami app: dark or light, instead of following the desktop.
NAMIThe nami app: the nami program to run.
NAMI_DISK_PASSWORDnami install-to --encrypt in a script: the disk’s password.
NAMI_USB_BINARYnami usb: the static nami to put on the drive.
NAMI_OS_DIRnami usb: an absolute folder to build in instead of ~/.cache/nami/os.
NAMI_BUILD_DEBUG=1Builds trace every command into the log.
NAMI_IMPORT_NIXnami import: 0 never uses Nix; an absolute path is the nix to run.
NAMI_GITHUB_MIRRORRead github: packages from a local mirror folder.
NAMI_LAYERS_DIRKeep fetched layers in this folder.
NAMI_ROOTUse this folder as /, for tests. Your home isn’t moved.
NAMI_CHANNEL, NAMI_KEYThe installer: the catalog channel, and the key it’s signed with.
NO_COLORThe 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).

Something wrong or missing here? nami report tells us, or Report a problem in the nami window.