Introduction

Navi is the most complete NixOS deployment tool in existence. Where every other tool solves one slice of the problem, Navi solves all of it. Cloud provisioning, bare-metal installation, disk decryption, secret delivery, DNS, and configuration switching are a single declarative workflow evaluated from one flake. It is the only tool that takes a fleet from nothing to fully running with a single command, and it does exactly that for real, multi-tenant production infrastructure spanning cloud and on-premise hardware today.

Navi began as a fork of Colmena and goes vastly further, unbound by compatibility with its ancestor. Colmena, NixOps, deploy-rs, and morph all begin only once a machine already exists and is reachable. They push a configuration and stop. Navi begins before the machine exists. It creates the machine, installs NixOS onto it, unlocks its encrypted disks, manages its DNS, and delivers its secrets, all from the same Nix evaluation. One source of truth, one command, one tool, instead of a brittle pile of Terraform, nixos-anywhere, a secrets mechanism, a DNS tool, and a deployer lashed together by hand.

Navi is built by longtime Nix maintainers with industrial experience from some of the largest Nix deployments in the world, including a former maintainer of morph. It distills the needs they have run into across their careers into one tool, formalizing what years of operating real fleets taught them about what a deployment tool actually has to do. It is engineered for fleets that are too large, too heterogeneous, and too important to manage by hand. A first-class terminal interface and a persistent daemon let it drive a large fleet concurrently without races, while the same commands scale all the way down to a single workstation. If you run NixOS seriously, Navi is the tool you graduate to.

What it looks like

Everything starts from a Hive: a Nix description of your fleet, living under the navi output of a flake. You write it once, declaring each node's NixOS configuration and how Navi reaches it; The Hive walks through creating one. From then on, because the whole lifecycle is evaluated from that same Hive, the command that acts on one node acts on a whole class of them with the same shape, on cloud or bare metal. Bringing a group of declared machines from nothing to their target configuration is one command:

navi provision --on <selector>

Selecting more nodes widens the operation without changing it, which is what makes a thirty-node fleet no harder to run than a single host. For a concrete picture of what that looks like in practice, see A production deployment.

Descended from Colmena

Navi inherits the Hive model from Colmena, so the configuration format will feel familiar if you have used it. But Navi is not Colmena-compatible and does not aim to be: it has diverged from the start, and it evolves in whatever direction the full lifecycle demands rather than staying within its ancestor's boundaries. What it adds is the rest of the lifecycle: provisioning, installation, disk unlock, DNS, and secret delivery, all from the same evaluation. Two capabilities make this practical at scale — the navi tui terminal interface for managing large fleets interactively, and a background daemon that owns connections and locks so operations across many nodes run concurrently without colliding.

How this manual is organised

Getting started takes you from an empty directory to a deployed node. The topic sections that follow each cover one capability end to end — deploying, providers, provisioning, disk encryption, secrets, and day-to-day operations — bundling the use case, the Hive configuration, and the commands together. The reference documents a complete production fleet, every command, and every configuration option; its command-line section is generated from the binary, so it cannot drift.

Status

Navi is in early development. Commands, configuration formats, and this manual can change between releases without notice. Do not use it with production credentials or on multi-user systems yet, because credential handling is not hardened.

How to read the command examples

Commands are shown without a shell prompt:

navi apply --on web-01

Where a command needs a Hive that an earlier chapter built, the chapter says so at the top.