Skip to content
NAILS
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

First install from Tails

The first installation of NAILS has to happen away from the decoy system, and Tails is a good place for it. Tails is a live system that starts from a USB stick. Tails says that it runs only from the computer’s memory and that everything you do disappears when you shut it down, apart from what you keep in its optional Persistent Storage. It can unlock VeraCrypt and LUKS volumes.

This page follows Tails 7. Later updates happen inside a hidden session instead, as Updating NAILS describes. Here Tails is only the place you install from. The comparison page explains how NAILS and Tails differ.

Before you start

Section titled “Before you start”
  • A Tails USB stick. The Tails website explains how to install Tails.
  • The hidden volume, made beforehand, with ext4, xfs, btrfs or f2fs inside. Tails can unlock VeraCrypt volumes, but its VeraCrypt guide says to create new ones outside of Tails. Make a VeraCrypt volume with VeraCrypt on another computer.
  • PBKDF2, not Argon2id. Make both the outer and the hidden VeraCrypt volume with PBKDF2. No cryptsetup release can open a VeraCrypt volume made with Argon2id yet, so no decoy NAILS supports could unlock it. Tails 7 is based on Debian 13, whose cryptsetup cannot open it either, and the attempt fails as if the password were wrong. Use PBKDF2, not Argon2id shows how to choose it and how to change a volume you already made.
  • Storage of its own. Keep the hidden volume on a drive or a partition of its own, which the decoy does not use. Do not use Tails to reach a container file on the decoy’s own disk. Tails would have to mount the decoy’s filesystem, and mounting writes to it. An ext4 filesystem, for one, records when and where it was last mounted.

In Tails

Section titled “In Tails”

  1. Start Tails with an administration password. Start it from the USB stick, not in a virtual machine. Tails says that traces of a session in a virtual machine are likely to be left on the host computer’s hard disk. If the hidden volume is on an external drive, start Tails on another computer. The first installation then does not touch the decoy computer at all. On the Welcome Screen, add an administration password under Additional Settings. Copying NAILS onto the hidden volume needs sudo, and Tails does not let you set the password after it has started. Then connect to the Tor network.

  2. Unlock the hidden volume, not the outer one. NAILS goes on the hidden volume. Tails opens VeraCrypt volumes without VeraCrypt’s hidden-volume protection, so a write to the outer volume can overwrite the hidden one, as Hazards explains. The Tails guide to VeraCrypt volumes has the steps for a file container and for a partition. Give the hidden volume’s password and choose to unlock the hidden volume. A LUKS2 volume on an external drive unlocks from the dialog that appears when you plug the drive in.

    Tails mounts the volume in a folder under /media/amnesia/, and ls /media/amnesia/ shows its name. The commands below use /media/amnesia/data. Put in the name of your folder.

  3. Download the release. In Tor Browser, download nails, checksums.txt and provenance.sigstore.json of the release these docs describe, which the Download page shows. Save them in a folder in your Home folder. In Tails that folder is in memory, so they are gone when Tails shuts down. Do not save them in the Persistent Storage, if you have one, which would keep them on the Tails stick.

  4. Check the checksum. Open a terminal with Apps ▸ System Tools ▸ Console, change to that folder and run:

    Terminal window
    sha256sum --check --ignore-missing checksums.txt

    It prints nails: OK. A matching checksum shows that the download is complete and matches checksums.txt. It says nothing about who built the file, because checksums.txt comes from the same release page.

  5. Check the provenance. This check shows that the release workflow of the NAILS repository built the file. Run it with cosign, as the Download page shows for this release. It needs cosign 3.1.3 or later, or 2.6.5 or later. Tails 7 is based on Debian 13, whose cosign package is too old, so get it another way, as the Download page explains. cosign also needs Sigstore’s public keys. It fetches them over the network each time it runs, or reads them from a file that you fetched elsewhere, as Verify a release explains.

    If you cannot run the check in Tails, run it for the same release on another computer you trust, before you run nails for the first time. nails init already runs the binary as root on the decoy. Until then only the checksum has been checked. Tails does not include the GitHub CLI, which the repository’s own Tails guide still uses for this check, so that guide always has you run it on another computer. Both tools check the same signed provenance.

  6. Copy NAILS onto the hidden volume.

    Terminal window
    sudo install -m0755 nails /media/amnesia/data/nails

    With sudo, install leaves the binary owned by root and writable by root alone.

  7. Eject the volume and shut down. In the sidebar of the Files browser, click the eject button next to the volume. Then shut down Tails.

Then, on the decoy

Section titled “Then, on the decoy”

If you could not check the provenance in Tails, check it on another computer first. Then start the decoy system. In a shell with history off, unlock and mount the hidden volume as Opening the volume shows, and lay it out with nails init, as Lay out the hidden volume describes. The mount point can differ from the one Tails used, because NAILS finds the hidden volume from the binary’s location.

Full details

Section titled “Full details”