Configuration Model

Flakes contain installables, installables contain machines:

Fleet → Flake → Installable → Machine

Attributes cascade down, without overriding child attributes. Slices (tags, secrets, disk encryption keys) append: define once at the fleet, extend at any level.

Why Installables Are Separate From Machines

An installable is a flake output (e.g. a nixosConfigurations or homeConfigurations entry) that defines what to build and deploy.

Traditional deployment tools assume one machine, one configuration: 50 identical machines mean 50 entries and 50 builds. Panix breaks this mapping: many machines share one installable, each can get its hostname and network identity from DHCP. Two effects compound:

• Build deduplication: one installable means one build, regardless of how many machines consume it.
• Parallel bootstrap: all machines sharing an installable can be bootstrapped simultaneously, since none needs machine-specific configuration.

The machine’s role is purely operational: it holds the SSH connection, target address, and transfer and activation state. The installable is the blueprint; the machine is where it lands.

Multiple Output Types Per Machine

A machine often needs more than a system configuration, for example a NixOS system plus a home-manager profile on the same box. Define multiple installable types under a single flake:

fleet:
  flakes:
    my-flake:
      installables:
        nixosConfigurations:
          server1:
            machines:
              server1:            # system-level activation (root)

        homeConfigurations:
          alice:
            user: alice           # activation runs as alice via su -l alice
            machines:
              server1:
                ssh:
                  username: root  # SSH as root, but activate as alice

For user-level types, activation runs as the SSH user by default. To deploy to a different user while SSHing as root, set the user field on the installable: Panix wraps activation in su -l <user> -c, running with that user’s $HOME and profile; generation listing (nix-env --list-generations) also runs as that user.

The user field is meaningful for every installable type. For user-level types (homeConfigurations, nixOnDroidConfigurations, packages, maidConfigurations) it selects the profile owner. For system-level types (nixosConfigurations, darwinConfigurations, systemConfigs) a non-root target user runs every privileged command (profile set, activation, rollback, generation listing) as that user via su -l, with each command elevated by the configured sudo_program, useful when a non-root user with passwordless sudo should activate the system. A system-level user: root is treated exactly like an unset user (the plain sudo path), never re-wrapped in su -l. su -l requires SSHing as root (su prompts for a password even when the SSH user already is the target user), and a non-root target user needs passwordless sudo; Inspect fails fast when the SSH user is not root, with guidance to unset user when it matches the SSH user. Activate re-probes rootness and re-validates after SSH connection switches (kexec, bootstrap reboot), and on local machines the executing user is the user actually running Panix, not the SSH username.

Caution

Each (installable, machine) pair is independent: no activation ordering, no gating when bootstrapping. If the target machine is in the NixOS installer, non-nixosConfigurations types also try to run; pass --tags=nixosConfigurations on bootstrap to exclude them.

Each installable type auto-infers its build path, activation mechanism, profile path, whether profile setting is needed, and its bootstrap mode (NixOS bootstrap for nixosConfigurations, Nix installer bootstrap for the other built-in types; custom types declare bootstrap_mode under output_types to opt in, see the Bootstrap guide). The built-in types, their activation mechanics, and custom type declarations under output_types are covered in Output Types.

How Inheritance Works

• Tags: every name (flake, installable type, installable, machine) is automatically a tag and accumulates. See Tag Filtering.
• Secrets: secrets defined above machine level append down, never replaced. See Secrets.
• SSH and bootstrap: settings cascade down; a machine can override any SSH parameter, and hooks at each level are collected. The rest of bootstrap inherits the same way, including bootstrap.nix (installer url, args, and curl_default_flags) and disable_nix_install.
• sudo_program: the elevation program used whenever a command must run as root and the executing user is not (SSH user, target user; default sudo; doas and run0 also work), inherits down.
• hardware_config_path: when set on a machine being bootstrapped, nixos-generate-config runs on the target and the hardware config it prints is written to this path on the machine running Panix, so the generated file lands straight in your configuration. Inspect generates it when it finds the machine in the NixOS installer; on machines that still need kexec, Bootstrap generates it right after kexec and before the bootstrap build that may import it, so a single bootstrap produces the file (see the Bootstrap guide).
• Nix flags: extra_flags, build_flags, copy_flags accumulate. See Nix Flags.

Disabling Parts of the Configuration

Set disabled: true on a flake, installable, or machine to skip it and its descendants: disabled sections are filtered out at evaluation and never run.