Install
NAILS is installed by copying a verified static binary onto the mounted hidden volume, and in no other way. The binary contains identifiable strings, and a copy that ever touched the decoy disk can be recovered, even after it was deleted.
First installation
Section titled “First installation”The first installation copies a release binary that you download and verify away from the decoy. It is the only supported way to install NAILS for the first time, because it is the only one that can be checked without touching the decoy. First install from Tails walks through it with Tails.
-
Prepare the hidden volume away from the decoy, and mount it there. The recommended way is an external drive that you set up on another computer. The other is a live system started from a USB stick, which writes nothing to the computer’s internal disk. Tails is one. It can unlock a VeraCrypt volume but cannot create one, so make a VeraCrypt volume with VeraCrypt on another computer. The volume must be storage of its own, such as a whole device or a partition the decoy does not use. With VeraCrypt, make both the outer and the hidden volume with PBKDF2, not Argon2id. No cryptsetup release can open a volume made with Argon2id yet, so no decoy NAILS supports could unlock it.
-
Download and verify the release. The Download page shows the release these docs describe and how to check its checksum and build provenance. Check the provenance before you run
nailsfor the first time, becausenails initalready runs it as root on the decoy. If the live system cannot run that check, run it for the same release on another computer you trust. -
Copy the verified binary onto the hidden volume, and nowhere else.
Terminal window sudo install -m0755 /path/to/verified/nails /mnt/data/nailsThe examples use the mapping name
dataand the mount point/mnt/data. Keep yours neutral too. Names surface in/dev/mapper,/dev/disk/by-label, mount unit names and the journal, and NAILS warns when one contains a telling word. -
Prepare the configuration there, if you want to change it. Every key is optional and NAILS uses the defaults for any you leave out, so you can skip this step. To change a setting now, write
config/nails.tomlon the hidden volume from this machine and keep it owned by root, like the binary.nails initkeeps a file that is already there. Never edit the configuration on the decoy, where an editor leaves its own traces. To change it later, write it asnails.toml.newinside a hidden session and move it into place after the session, as Changing the configuration shows.
Lay out the hidden volume
Section titled “Lay out the hidden volume”Then start the decoy. In a shell with history off, unlock and mount the hidden volume, as Opening the volume shows, and lay it out once:
set +o history# unlock and mount the hidden volume at /mnt/data, then:sudo /mnt/data/nails init /mnt/datainit refuses a directory that is not a volume of its own, such as a folder,
or a subvolume, bind mount or unencrypted image file on the computer’s own
storage, before it writes or probes anything. An encrypted container file on a
decoy filesystem only gets a warning, because that filesystem can keep old
copies of the parts of the container that changed.
Unless a configuration file is already there, init writes a commented
template that uses the defaults and is readable by root only. On NixOS, it also
seeds the hidden NixOS layout from /etc/nixos/hardware-configuration.nix. It
ends by printing the next steps.
Then continue with your first session.
Run NAILS by its full path
Section titled “Run NAILS by its full path”The binary lives on the hidden volume, so every command uses its full path, for
example sudo /mnt/data/nails check. sudo does not search the hidden volume,
so a bare sudo nails would not resolve.
Leave hidden_volume_root unset in the configuration. NAILS then derives it
from the binary’s location, and the configuration keeps working wherever the
volume is mounted. This relies on the binary being installed on the hidden
volume. If you run NAILS from a build directory or the Nix store, set
hidden_volume_root or pass --config.
Updating NAILS
Section titled “Updating NAILS”New releases appear in the
releases feed, which any
feed reader can follow without a GitHub account. Follow it inside a hidden
session or on another device, never on the decoy, where the reader’s
subscription would name the tool. The feed lists a version as soon as its tag
is pushed, before its release is published, and keeps tags that never got a
release. A version is out once
GitHub Releases lists it with
its files. Versions ending in -rc.N are release candidates.
Replace the binary, the configuration or a hidden NixOS flake only while no session is active.
-
Inside a hidden session, download and verify the new release, or build it from source, and leave it next to the old one as
nails.new. Downloads and build caches then land in the upper layer on the hidden volume, never on the decoy.Terminal window # a verified releasesudo install -m0755 /path/to/verified/nails /mnt/data/nails.new# or a build from sourcegit clone https://github.com/WitteShadovv/nails /mnt/data/src/nailscd /mnt/data/src/nailscargo build --release # or: nix build .#nails, then use ./result/bin/nailssudo install -m0755 ./target/release/nails /mnt/data/nails.new -
End the session, as Ending a session describes.
-
Before your next activation, with the hidden volume mounted on the decoy and in a shell with history off, move the new binary into place.
Terminal window sudo mv /mnt/data/nails.new /mnt/data/nails
Never build or download on the decoy. Before a session there is no upper layer to catch the caches. After a version change, read its release notes and the operator guide again, because operational requirements can change between releases.
Upgrading from 0.2
Section titled “Upgrading from 0.2”NAILS 0.2 is the earlier design for NixOS only, with per-directory overlays and a YAML configuration. The whole-root session replaced it and changed operator-facing interfaces, with no compatibility shim. Convert your setup before you run the new binary.
- End the 0.2 session first, with its own
nails deactivate. A reboot ends it too. - Session layout. The per-directory overlays are gone. The session takes the
whole root, entered and left with a soft-reboot that needs systemd 254 or
newer. Its layers live under
<hidden-root>/root/, and the old uppers,<hidden-root>/<name>and<hidden-root>/.work, are not read. Move what you need from them into a hidden session, then delete them. On NixOS, runnails initagain to place the hidden hardware configuration. - Platforms. Debian 13, Ubuntu 24.04 and Ubuntu 26.04 are now supported as decoys alongside NixOS, and a later Debian or Ubuntu release runs with a warning.
- A volume of its own. NAILS now refuses hidden roots that 0.2 accepted: a folder, a btrfs subvolume or bind of a folder of a filesystem the decoy uses, a logical volume in the decoy’s volume group, an unencrypted image file on a decoy filesystem, and an overlay, FUSE, network or ZFS filesystem. Move the hidden volume to a device of its own.
- Decoy root. The decoy root must now be on a block device, with ext4, xfs,
btrfs or f2fs. An overlay root, a ZFS root and a tmpfs root, such as
nixos-impermanenceon/, are refused. A/varor/homeon its own tmpfs, wiped at boot, is fine. - NixOS flake decoys. Activation refuses to build the decoy’s own
/etc/nixosflake, however it is named, and--no-preflightdoes not change that. Write a self-contained flake in<hidden-root>/nixosthat imports the hidden module and reads none of the decoy’s files. Write and lock it inside a hidden session, whichactivate --overlay-onlyenters, never on the decoy. - Configuration. It is strict TOML in
config/nails.tomlnext to the binary. The new binary never reads the 0.2 YAML file and does not warn about it, so an unconverted setup runs with the defaults. Convert each key by hand.hidden_volume_pathis nowhidden_volume_root, which you can leave unset. Unknown keys, including the removed ones, are rejected. - Flags. The output flags are global and accepted in any position.
activate --flakeis now--nixos-flake,status -vis nowstatus --details, and the flags of the old live-overlay mode are removed. - Confirmation.
activateanddeactivatenow ask for confirmation, and without a terminal they refuse with exit code 2. Add-yto every script, key binding or unit that runs them.emergencynever asks. - Exit codes and JSON. Every command returns a documented exit code, and
--jsonwrites a versioned envelope. Update any script that parses the old output. - State file. The new binary cannot verify a
state.jsonthat 0.2 wrote.statusreports the state as unknown andactivaterefuses until you delete the file from a clean, inactive system. Do not edit it by hand.
The changelog’s upgrade notes and its list of removed items name every removed key, flag and command.
The NAILS 0.3 release announcement explains what changed and why.
Channels that are not offered
Section titled “Channels that are not offered”There is no crates.io crate, no nixpkgs package, no .deb or .rpm package and
no NixOS module for the decoy. Each of them would write a lasting record onto
the decoy or into a public index.