Skip to content
NAILS on GitHub
These docs describe NAILS 0.3, published so far as the release candidate v0.3.0-rc.3. They do not apply to v0.2.0, the latest stable release. Download and verify NAILS 0.3

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.

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.

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

  2. 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 nails for the first time, because nails init already 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.

  3. Copy the verified binary onto the hidden volume, and nowhere else.

    Terminal window
    sudo install -m0755 /path/to/verified/nails /mnt/data/nails

    The examples use the mapping name data and 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.

  4. 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.toml on the hidden volume from this machine and keep it owned by root, like the binary. nails init keeps 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 as nails.toml.new inside a hidden session and move it into place after the session, as Changing the configuration shows.

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:

Terminal window
set +o history
# unlock and mount the hidden volume at /mnt/data, then:
sudo /mnt/data/nails init /mnt/data

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

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.

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.

  1. 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 release
    sudo install -m0755 /path/to/verified/nails /mnt/data/nails.new
    # or a build from source
    git clone https://github.com/WitteShadovv/nails /mnt/data/src/nails
    cd /mnt/data/src/nails
    cargo build --release # or: nix build .#nails, then use ./result/bin/nails
    sudo install -m0755 ./target/release/nails /mnt/data/nails.new
  2. End the session, as Ending a session describes.

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

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, run nails init again 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-impermanence on /, are refused. A /var or /home on its own tmpfs, wiped at boot, is fine.
  • NixOS flake decoys. Activation refuses to build the decoy’s own /etc/nixos flake, however it is named, and --no-preflight does not change that. Write a self-contained flake in <hidden-root>/nixos that imports the hidden module and reads none of the decoy’s files. Write and lock it inside a hidden session, which activate --overlay-only enters, never on the decoy.
  • Configuration. It is strict TOML in config/nails.toml next 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_path is now hidden_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 --flake is now --nixos-flake, status -v is now status --details, and the flags of the old live-overlay mode are removed.
  • Confirmation. activate and deactivate now ask for confirmation, and without a terminal they refuse with exit code 2. Add -y to every script, key binding or unit that runs them. emergency never asks.
  • Exit codes and JSON. Every command returns a documented exit code, and --json writes a versioned envelope. Update any script that parses the old output.
  • State file. The new binary cannot verify a state.json that 0.2 wrote. status reports the state as unknown and activate refuses 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.

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.