Skip to content

panix deploy

panix deploy runs the full workflow: inspect, bootstrap, build, transfer, secrets, and activate.

All flags can also be set via environment variables (shown in parentheses) or in the flags section of panix.yml, except per-invocation flags like --config (and the standalone commands’ -o), which cannot be set in panix.yml (the universal --help and --version flags are excluded).

> panix deploy --help
Usage: panix deploy [flags]

Do full workflow (inspect -> bootstrap -> build -> transfer -> secrets ->
activate)

Flags:
  -h, --help                       Show context-sensitive help.
      --version                    Show version ($PANIX_VERSION)

  -c, --config="panix.yml"         Config file ($PANIX_CONFIG)
      --validate.flakes            Validate flake URLs and configuration keys
                                   ($PANIX_VALIDATE_FLAKES)
      --validate.bootstrap-secrets
                                   Validate that bootstrap disk encryption
                                   key local paths exist on disk
                                   ($PANIX_VALIDATE_BOOTSTRAP_SECRETS)
  -t, --tags=TAGS,...              Filter machines by tags (flakes, installables
                                   (output type and attribute name) and machine
                                   names are already registered as tags)
                                   ($PANIX_TAGS)
  -s, --skip-phases=SKIP-PHASES,...
                                   Declare phases to skip (not all phases can be
                                   skipped) ($PANIX_SKIP_PHASES)
      --timeout=2h                 Timeout per command (eg. '1h', '1m15s')
                                   ($PANIX_TIMEOUT)
      --activation-mode=ACTIVATION-MODE
                                   Activation mode override. Bare value (e.g.
                                   'test') applies to all types. Per-type:
                                   'nixosConfigurations=test;homeConfigurations=switch'
                                   ($PANIX_ACTIVATION_MODE)
      --output-mode=OUTPUT-MODE    Output mode: tui, console, json
                                   ($PANIX_OUTPUT_MODE)
      --require-all-success        Abort if any task fails, primarily for CI/CD
                                   ('retry' and 'restart' keybinds are disabled
                                   in this mode) ($PANIX_REQUIRE_ALL_SUCCESS)
      --exit-on-complete           Exit TUI on completion
                                   ($PANIX_EXIT_ON_COMPLETE)
      --local-machine-hostname=STRING
                                   Hostname of the machine that is local
                                   (won't use ssh to connect to it) (default:
                                   your deployment machine hostname)
                                   ($PANIX_LOCAL_MACHINE_HOSTNAME)
      --dry-run                    Show what would be done without executing
                                   ($PANIX_DRY_RUN)
      --dry-run-with-inspect       Show what would be done without
                                   executing, but with real inspect query
                                   ($PANIX_DRY_RUN_WITH_INSPECT)
      --out-links                  Create GC root outlinks for built
                                   installables (like 'nix build --out-link')
                                   in out_links_dir, structured as
                                   <flake>/<output_type>/<name>. Nix skips
                                   outlinks for remote (non-local) build stores
                                   ($PANIX_OUT_LINKS)
      --out-links-dir=".panix"     Directory for build outlinks
                                   ($PANIX_OUT_LINKS_DIR)
  -l, --log                        Enable logging to file ($PANIX_LOG)
      --log-file="panix.log"       Log file path (epoch timestamp appended
                                   before .log) ($PANIX_LOG_FILE)
  -d, --debug                      Debug mode (enables logging) ($PANIX_DEBUG)
      --snapshot.dir="."           Directory to save snapshots
                                   ($PANIX_SNAPSHOT_DIR)
      --snapshot.on-retry          Take snapshot before retry
                                   ($PANIX_SNAPSHOT_ON_RETRY)
      --snapshot.on-exit           Take snapshot on exit
                                   ($PANIX_SNAPSHOT_ON_EXIT)
      --tui.show-all-build-logs    Show all build logs in TUI (keybind h)
                                   ($PANIX_TUI_SHOW_ALL_BUILD_LOGS)
      --tui.show-active-only       Show only running or errored logs
                                   in TUI build logs (keybind a)
                                   ($PANIX_TUI_SHOW_ACTIVE_ONLY)
      --tui.show-commands-in-labels
                                   Show raw commands instead of descriptions
                                   as labels in build logs (keybind c)
                                   ($PANIX_TUI_SHOW_COMMANDS_IN_LABELS)
      --tui.command-output-max-height=8
                                   Maximum height for command labels
                                   and outputs viewports in TUI
                                   ($PANIX_TUI_COMMAND_OUTPUT_MAX_HEIGHT)
      --tui.command-output-max-lines=10000
                                   Maximum output lines to keep per
                                   command in TUI (older lines are
                                   trimmed from the front in batches)
                                   ($PANIX_TUI_COMMAND_OUTPUT_MAX_LINES)
      --tui.theme="panix"          TUI color theme name ($PANIX_TUI_THEME)
      --tui.themes-file=STRING     Path to the themes file (default:
                                   ./panix-themes.yml) ($PANIX_TUI_THEMES_FILE)
      --profile.cpu=STRING         Path for CPU profile output (enables CPU
                                   profiling) ($PANIX_PROFILE_CPU)
      --profile.mem=STRING         Path for memory profile output (enables
                                   memory profiling) ($PANIX_PROFILE_MEM)
      --profile.block=STRING       Path for block profile output (enables block
                                   profiling) ($PANIX_PROFILE_BLOCK)
      --profile.mutex=STRING       Path for mutex profile output (enables mutex
                                   profiling) ($PANIX_PROFILE_MUTEX)
      --profile.goroutine=STRING
                                   Path for goroutine profile output
                                   (enables goroutine profiling)
                                   ($PANIX_PROFILE_GOROUTINE)
      --runtime.max-concurrency=0
                                   Maximum concurrent workers in
                                   the worker pool (0 = unlimited)
                                   ($PANIX_RUNTIME_MAX_CONCURRENCY)
      --runtime.disconnect-timeout=5m
                                   Timeout for waiting for a host to
                                   disconnect during reboot (e.g. '5s', '10m')
                                   ($PANIX_RUNTIME_DISCONNECT_TIMEOUT)
      --runtime.reconnect-timeout=10m
                                   Timeout for waiting for a host to
                                   reconnect after reboot (e.g. '10s', '20m')
                                   ($PANIX_RUNTIME_RECONNECT_TIMEOUT)
      --runtime.ssh-reachability-timeout=2s
                                   TCP dial timeout for SSH reachability probe
                                   ($PANIX_RUNTIME_SSH_REACHABILITY_TIMEOUT)
      --runtime.flake-validation-timeout=60s
                                   Timeout for nix flake
                                   metadata/eval during validation
                                   ($PANIX_RUNTIME_FLAKE_VALIDATION_TIMEOUT)

Runtime Tunables

The --runtime.* flags configure operational timeouts and concurrency. They can be set via CLI flag, environment variable, or the runtime: block under flags in panix.yml.

Flag	Env var	Default	Description
`--runtime.max-concurrency`	`PANIX_RUNTIME_MAX_CONCURRENCY`	`0`	Max parallel workers in the worker pool (0 = unlimited)
`--runtime.disconnect-timeout`	`PANIX_RUNTIME_DISCONNECT_TIMEOUT`	`5m`	Wait for host to disconnect during reboot
`--runtime.reconnect-timeout`	`PANIX_RUNTIME_RECONNECT_TIMEOUT`	`10m`	Wait for host to reconnect after reboot
`--runtime.ssh-reachability-timeout`	`PANIX_RUNTIME_SSH_REACHABILITY_TIMEOUT`	`2s`	TCP dial timeout for SSH reachability probe
`--runtime.flake-validation-timeout`	`PANIX_RUNTIME_FLAKE_VALIDATION_TIMEOUT`	`60s`	Timeout for nix flake metadata/eval during validation

Dry Run

Preview what a deploy would do without executing it:

panix deploy --dry-run                # Config-only preview
panix deploy --dry-run-with-inspect   # Preview with real Inspect queries

Flag	Description
`--dry-run`	Shows what Panix would do based on the configuration alone, without connecting to any machines. Useful for verifying configuration structure, tag filtering, and inheritance.
`--dry-run-with-inspect`	Same as dry run, but executes the Inspect phase to query real machine states (reachability, OS, architecture, generations). The preview is more accurate because it knows which machines are NixOS and which need bootstrapping.

Build Modes: local vs remote builds, remote builder selection
Output Types: --activation-mode values and per-type activation overrides
Tag Filtering: -t, --tags filtering and tag inheritance
Output Modes: --output-mode, file logging, and CI flags