Skip to content
Panix

Full YAML Reference

This reference walks the fleet tree level by level, then embeds the complete auto-generated YAML schema.

The same schema is available in the repository at gen/panix-schema.yaml.

# yaml-language-server: $schema=https://raw.githubusercontent.com/mihakrumpestar/panix/main/gen/panix-schema.yaml


# Only some options, read the YAML schema for all
fleet:
  tags: [production]                   # Inherited by all descendants
  rsync_default_flags: ["-rcEx", "--mkpath", "--perms"]  # Override base rsync flags (default shown)
  auto_rollback: false                 # Roll back to pre-deploy generation on activation failure
  nix:
    extra_flags: ["--option", "sandbox", "false"]  # APPEND after default flags
  ssh:
    username: root
    disable_strict_key_checking: true   # Lab/test networks only


  flakes:
    infrastructure:
      url: path:../infra-flake
      tags: [critical]                 # Accumulated with fleet: [production, critical]
      rsync_default_flags: ["-rcEx", "--mkpath", "--perms"]  # Inherited by installables/machines (override)
      nix:
        build_flags: ["--max-jobs", "8"]
      secrets:                         # APPENDED to fleet secrets (none inherited)
        - local_path: ./secrets/infra/api.key
          remote_path: /var/secrets/api.key


      installables:
        nixosConfigurations:             # System-level: activates as root
          webserver:
            tags: [web]                  # Accumulated: [production, critical, web]
            rsync_default_flags: ["-rcEx", "--mkpath", "--perms"]  # Override at installable level
            nix:
              build_mode: remote          # Build on first machine instead of locally
            machines:
              web-01:                    # SSH from config/ssh block, no override needed
              web-02:
                ssh:
                  hostname: web-02.example.com  # Machine-specific hostname override


          database:
            machines:
              db-01:
                ssh:
                  hostname: 10.0.1.50
                  identity_file: ./keys/db.key
                rsync_default_flags: ["-rcEx", "--mkpath", "--perms"]  # Override at machine level
                bootstrap:
                  ssh:
                    hostname: 10.0.1.50
                    identity_file: ./keys/bootstrap.key
                  disk_encryption_keys:
                    - local_path: ./secrets/db/luks.key
                      remote_path: /tmp/luks-key
                  post_bootstrap_hooks:
                    - systemd-cryptenroll --tpm2-device=auto /dev/sda2
                  kexec:
                    curl_default_flags: ["--fail", "-#", "-L"]  # Override base curl flags (default shown)


        homeConfigurations:              # User-level: activates as SSH user
          admin:
            machines:
              web-01:
                ssh:
                  username: admin         # Activation runs as this user


    monitoring:
      url: github:myorg/monitoring#main
      installables:
        nixosConfigurations:
          prometheus:
            machines:
              prom-01:

Global flags options (activation mode, output mode, TUI, logging, snapshots, profiling) and the nix default flags (*_default_flags, per-level build_flags / copy_flags / nixos_install_flags) are all listed in the full schema below; nix flags are also explained in Nix Command Flags and the TUI theme setting in Themes.

The one used for testing to deploy infrastructure is at examples/panix.deploy.yml.

Full YAML Schema

Section titled “Full YAML Schema”
$schema: "http://json-schema.org/draft-07/schema#"
$id: https://raw.githubusercontent.com/mihakrumpestar/panix/main/gen/panix-schema.yaml
version: 0.12.0
title: Panix Configuration Schema
description: Schema for Panix deployment configuration file
type: object
properties:
  flags:
    type: object
    description: Flags (CLI and YAML)
    properties:
      activation_mode:
        type: object
        description: "Activation mode override. Bare value (e.g. 'test') applies to all types. Per-type: 'nixosConfigurations=test;homeConfigurations=switch'"
        properties:
          alltypes:
            type: string
          pertype:
            type: object
            additionalProperties:
              type: string
        additionalProperties: false
      dry_run:
        type: boolean
        description: Show what would be done without executing
      dry_run_with_inspect:
        type: boolean
        description: Show what would be done without executing, but with real inspect query
      exit_on_complete:
        type: boolean
        description: Exit TUI on completion
      local_machine_hostname:
        type: string
        description: "Hostname of the machine that is local (won't use ssh to connect to it) (default: your deployment machine hostname)"
      logging:
        type: object
        properties:
          debug:
            type: boolean
            description: Debug mode (enables logging)
          log:
            type: boolean
            description: Enable logging to file
          log_file:
            type: string
            description: "Log file path (epoch timestamp appended before .log) (default: panix.log)"
            default: panix.log
            format: file-path
        additionalProperties: false
      out_links:
        type: boolean
        description: 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
      out_links_dir:
        type: string
        description: "Directory for build outlinks (default: .panix)"
        default: .panix
      output:
        type: string
        description: "Output mode: tui, console, json"
        enum:
          - tui
          - console
          - json
      profile:
        type: object
        properties:
          block:
            type: string
            description: Path for block profile output (enables block profiling)
            format: file-path
          cpu:
            type: string
            description: Path for CPU profile output (enables CPU profiling)
            format: file-path
          goroutine:
            type: string
            description: Path for goroutine profile output (enables goroutine profiling)
            format: file-path
          mem:
            type: string
            description: Path for memory profile output (enables memory profiling)
            format: file-path
          mutex:
            type: string
            description: Path for mutex profile output (enables mutex profiling)
            format: file-path
        additionalProperties: false
      require_all_success:
        type: boolean
        description: Abort if any task fails, primarily for CI/CD ('retry' and 'restart' keybinds are disabled in this mode)
      rollback_generation:
        type: integer
        description: "0=current generation, -N=Nth before current, N=specific generation (default: -1)"
        default: -1
      runtime:
        type: object
        properties:
          disconnect_timeout:
            type: string
            description: "Timeout for waiting for a host to disconnect during reboot (e.g. '5s', '10m') (default: 5m)"
            default: 5m
          flake_validation_timeout:
            type: string
            description: "Timeout for nix flake metadata/eval during validation (default: 60s)"
            default: 60s
          max_concurrency:
            type: integer
            description: "Maximum concurrent workers in the worker pool (0 = unlimited) (default: 0)"
            default: 0
          reconnect_timeout:
            type: string
            description: "Timeout for waiting for a host to reconnect after reboot (e.g. '10s', '20m') (default: 10m)"
            default: 10m
          ssh_reachability_timeout:
            type: string
            description: "TCP dial timeout for SSH reachability probe (default: 2s)"
            default: 2s
        additionalProperties: false
      skip_phases:
        type: array
        description: Declare phases to skip (not all phases can be skipped)
        items:
          type: string
      snapshot:
        type: object
        properties:
          dir:
            type: string
            description: "Directory to save snapshots (default: .)"
            default: .
          on_exit:
            type: boolean
            description: Take snapshot on exit
          on_retry:
            type: boolean
            description: Take snapshot before retry
        additionalProperties: false
      tags:
        type: array
        description: Filter machines by tags (flakes, installables (output type and attribute name) and machine names are already registered as tags)
        items:
          type: string
      timeout:
        type: string
        description: "Timeout per command (eg. '1h', '1m15s') (default: 2h)"
        default: 2h
      tui:
        type: object
        properties:
          command_output_max_height:
            type: integer
            description: "Maximum height for command labels and outputs viewports in TUI (default: 8)"
            default: 8
          command_output_max_lines:
            type: integer
            description: "Maximum output lines to keep per command in TUI (older lines are trimmed from the front in batches) (default: 10000)"
            default: 10000
          show_active_only:
            type: boolean
            description: Show only running or errored logs in TUI build logs (keybind a)
          show_all_build_logs:
            type: boolean
            description: Show all build logs in TUI (keybind h)
          show_commands_in_labels:
            type: boolean
            description: Show raw commands instead of descriptions as labels in build logs (keybind c)
          theme:
            type: string
            description: "TUI color theme name (default: panix)"
            default: panix
          themes_file:
            type: string
            description: "Path to the themes file (default: ./panix-themes.yml)"
        additionalProperties: false
      validate:
        type: object
        description: Validator settings
        properties:
          bootstrap_secrets:
            type: boolean
            description: Validate that bootstrap disk encryption key local paths exist on disk
          flakes:
            type: boolean
            description: Validate flake URLs and configuration keys
        additionalProperties: false
    additionalProperties: false
  fleet:
    type: object
    description: Fleet configuration
    properties:
      activation_hooks:
        description: "Hooks around the activation step: pre hooks run before activation, post hooks after a mutating activation succeeds"
        $ref: "#/definitions/ActivationHooks"
      auto_rollback:
        type: boolean
        description: Automatically roll back to the pre-deploy generation when activation fails
      bootstrap:
        description: Bootstrap configuration for initial provisioning
        $ref: "#/definitions/Bootstrap"
      disabled:
        type: boolean
        description: Disable this
      flakes:
        type: object
        description: Flakes in the fleet
        additionalProperties:
          type: object
          properties:
            activation_hooks:
              description: "Hooks around the activation step: pre hooks run before activation, post hooks after a mutating activation succeeds"
              $ref: "#/definitions/ActivationHooks"
            auto_rollback:
              type: boolean
              description: Automatically roll back to the pre-deploy generation when activation fails
            bootstrap:
              description: Bootstrap configuration for initial provisioning
              $ref: "#/definitions/Bootstrap"
            disabled:
              type: boolean
              description: Disable this
            hardware_config_path:
              type: string
              description: Local path for the target's generated hardware config, written once the target runs the NixOS installer. Keep it inside your flake
            installables:
              type: object
              description: Installables (e.g. nixosConfigurations, homeConfigurations)
              additionalProperties:
                type: object
                additionalProperties:
                  type: object
                  properties:
                    activation_hooks:
                      description: "Hooks around the activation step: pre hooks run before activation, post hooks after a mutating activation succeeds"
                      $ref: "#/definitions/ActivationHooks"
                    activation_mode:
                      type: string
                      description: Activation mode (overrides preset default)
                    auto_rollback:
                      type: boolean
                      description: Automatically roll back to the pre-deploy generation when activation fails
                    bootstrap:
                      description: Bootstrap configuration for initial provisioning
                      $ref: "#/definitions/Bootstrap"
                    disabled:
                      type: boolean
                      description: Disable this
                    hardware_config_path:
                      type: string
                      description: Local path for the target's generated hardware config, written once the target runs the NixOS installer. Keep it inside your flake
                    machines:
                      type: object
                      description: Machines configuration
                      additionalProperties:
                        anyOf:
                          - type: object
                            properties:
                              activation_hooks:
                                description: "Hooks around the activation step: pre hooks run before activation, post hooks after a mutating activation succeeds"
                                $ref: "#/definitions/ActivationHooks"
                              auto_rollback:
                                type: boolean
                                description: Automatically roll back to the pre-deploy generation when activation fails
                              bootstrap:
                                description: Bootstrap configuration for initial provisioning
                                $ref: "#/definitions/Bootstrap"
                              disabled:
                                type: boolean
                                description: Disable this
                              hardware_config_path:
                                type: string
                                description: Local path for the target's generated hardware config, written once the target runs the NixOS installer. Keep it inside your flake
                              rsync_default_flags:
                                type: array
                                description: "List of base flags for rsync command (default: [-rcEx, --mkpath, --perms])"
                                items:
                                  type: string
                              secrets:
                                type: array
                                description: Files or directories to transfer to the remote machine
                                items:
                                  $ref: "#/definitions/TransferSource"
                              ssh:
                                description: SSH configuration for remote access
                                $ref: "#/definitions/SSHClient"
                              sudo_program:
                                type: string
                                description: "Override the elevation program used when the executing user (SSH or target user) is not root (default: sudo)"
                                default: sudo
                              tags:
                                type: array
                                description: Tags for filtering (flakes, configs and machines are already registered as tags)
                                items:
                                  type: string
                            additionalProperties: false
                          - type: "null"
                    nix:
                      description: Nix build and copy configuration
                      $ref: "#/definitions/nix_NixConfig"
                    preset:
                      $ref: "#/definitions/Preset"
                    rsync_default_flags:
                      type: array
                      description: "List of base flags for rsync command (default: [-rcEx, --mkpath, --perms])"
                      items:
                        type: string
                    secrets:
                      type: array
                      description: Files or directories to transfer to the remote machine
                      items:
                        $ref: "#/definitions/TransferSource"
                    ssh:
                      description: SSH configuration for remote access
                      $ref: "#/definitions/SSHClient"
                    sudo_program:
                      type: string
                      description: "Override the elevation program used when the executing user (SSH or target user) is not root (default: sudo)"
                      default: sudo
                    tags:
                      type: array
                      description: Tags for filtering (flakes, configs and machines are already registered as tags)
                      items:
                        type: string
                    user:
                      type: string
                      description: Target user for activation. When set, commands run as this user via su -l, which requires SSHing as root (su -l would prompt for a password otherwise; system-level types elevate each command with the sudo program unless the target user is root, which is the default; a non-root target user needs passwordless sudo). If empty, uses the SSH username.
                  required:
                    - machines
                  additionalProperties: false
            nix:
              description: Nix build and copy configuration
              $ref: "#/definitions/nix_NixConfig"
            rsync_default_flags:
              type: array
              description: "List of base flags for rsync command (default: [-rcEx, --mkpath, --perms])"
              items:
                type: string
            secrets:
              type: array
              description: Files or directories to transfer to the remote machine
              items:
                $ref: "#/definitions/TransferSource"
            ssh:
              description: SSH configuration for remote access
              $ref: "#/definitions/SSHClient"
            sudo_program:
              type: string
              description: "Override the elevation program used when the executing user (SSH or target user) is not root (default: sudo)"
              default: sudo
            tags:
              type: array
              description: Tags for filtering (flakes, configs and machines are already registered as tags)
              items:
                type: string
            url:
              type: string
              description: "Flake path (eg. './dir') or url (eg. 'path:...', 'ssh:...', 'github:...'), reference https://nix.dev/manual/nix/2.33/command-ref/new-cli/nix3-flake.html#url-like-syntax (default: .)"
              default: .
          required:
            - installables
          additionalProperties: false
      hardware_config_path:
        type: string
        description: Local path for the target's generated hardware config, written once the target runs the NixOS installer. Keep it inside your flake
      nix:
        description: Nix build and copy configuration
        $ref: "#/definitions/nix_NixConfig"
      rsync_default_flags:
        type: array
        description: "List of base flags for rsync command (default: [-rcEx, --mkpath, --perms])"
        items:
          type: string
      secrets:
        type: array
        description: Files or directories to transfer to the remote machine
        items:
          $ref: "#/definitions/TransferSource"
      ssh:
        description: SSH configuration for remote access
        $ref: "#/definitions/SSHClient"
      sudo_program:
        type: string
        description: "Override the elevation program used when the executing user (SSH or target user) is not root (default: sudo)"
        default: sudo
      tags:
        type: array
        description: Tags for filtering (flakes, configs and machines are already registered as tags)
        items:
          type: string
    required:
      - flakes
    additionalProperties: false
  output_types:
    type: object
    description: Custom output type presets, applied as defaults to installables of that type
    additionalProperties:
      $ref: "#/definitions/Preset"
required:
  - fleet
additionalProperties: true
definitions:
  ActivationHooks:
    type: object
    properties:
      post:
        type: array
        description: Commands to run after activation succeeds, only for mutating modes (skipped for non-mutating modes such as dry-activate); a failure fails the deploy without rolling back the successful activation
        items:
          type: string
      pre:
        type: array
        description: Commands to run before activation (same format as bootstrap hooks); a failure skips activation and fails the machine without rollback, the system is untouched
        items:
          type: string
    additionalProperties: false
  Bootstrap:
    type: object
    properties:
      allow_destructive_actions:
        type: boolean
        description: Allow destructive bootstrap actions (required for force_bootstrap and force_bootstrap_kexec)
      disable_automatic_reboot:
        type: boolean
        description: Disable automatic reboot after nixos-install (useful for manual inspection or custom reboot handling)
      disable_disko:
        type: boolean
        description: Disables building, transfer and execution of disko tool
      disable_nix_install:
        type: boolean
        description: "Skip installing Nix on targets that lack it (default: false)"
        default: false
      disk_encryption_keys:
        type: array
        description: Keys are transferred to root dir on remote, which is the installer. If you want them to be transferred to disk of the final system, prefix path with '/mnt'
        items:
          $ref: "#/definitions/TransferSource"
      force_bootstrap:
        type: boolean
        description: Force bootstrap even if machine is already NixOS (requires allow_destructive_actions)
      force_bootstrap_kexec:
        type: boolean
        description: Force kexec method even if already in NixOS installer (requires force_bootstrap and allow_destructive_actions)
      kexec:
        description: Kexec configuration for bootstrapping non-NixOS machines or reinstalling a live NixOS installation
        $ref: "#/definitions/KexecConfig"
      nix:
        description: Nix installer configuration used when the target lacks Nix
        $ref: "#/definitions/attributes_NixConfig"
      post_bootstrap_hooks:
        type: array
        description: Commands to run after disko partitioning (NixOS bootstrap) or after the Nix installer (Nix installer bootstrap)
        items:
          type: string
      post_bootstrap_install_hooks:
        type: array
        description: Commands to run after nixos-install (before reboot)
        items:
          type: string
      post_bootstrap_provisioned_hooks:
        type: array
        description: Commands to run after reboot (uses regular SSH)
        items:
          type: string
      ssh:
        description: Bootstrap SSH configuration (used during initial provisioning)
        $ref: "#/definitions/SSHClient"
    additionalProperties: false
  KexecConfig:
    type: object
    properties:
      curl_default_flags:
        type: array
        description: "List of base flags for curl when downloading kexec tarball (default: [--fail, -#, -L])"
        items:
          type: string
      extra_flags:
        type: array
        description: Extra flags to pass to kexec (e.g. '--no-sync')
        items:
          type: string
      image:
        type: string
        description: "https URL or local path to kexec tarball for bootstrapping non-NixOS machines (default: https://github.com/nix-community/nixos-images/releases/latest/download/nixos-kexec-installer-noninteractive-$PANIX_ARCH-linux.tar.gz)"
        default: https://github.com/nix-community/nixos-images/releases/latest/download/nixos-kexec-installer-noninteractive-$PANIX_ARCH-linux.tar.gz
      ssh_port:
        type: integer
        description: "SSH port for kexec installer (default: 22)"
        default: 22
    additionalProperties: false
  Preset:
    type: object
    properties:
      activation_default_mode:
        type: string
        description: Default activation mode
      activation_non_mutating_modes:
        type: array
        description: Activation modes that do not mutate the target system (auto rollback is skipped for these modes)
        items:
          type: string
      activation_path:
        type: string
        description: Activation script path in the closure
      activation_profile_skip_modes:
        type: array
        description: Activation modes that skip setting the profile before activation (the activation runs against the passed closure without switching the profile to it)
        items:
          type: string
      activation_supported_modes:
        type: array
        description: Activation modes
        items:
          type: string
      bootstrap_mode:
        type: string
        description: "Bootstrap mode for this output type: 'nixos' (full NixOS bootstrap) or 'nix-install' (install Nix on targets that lack it); empty disables bootstrap. Type-level field: set only under output_types declarations"
        enum:
          - nixos
          - nix-install
      build_path:
        type: string
        description: Build path within the flake output
      omit_type_from_attr_path:
        type: boolean
        description: "Omit output type from attrpath (for packages where nix auto-resolves bare names). Type-level field: set only under output_types declarations"
      output_type_attr:
        type: string
        description: Top-level flake output attribute used in the attrpath (defaults to the output type key)
      profile_path:
        type: string
        description: Nix profile path
      set_profile:
        type: boolean
        description: Run nix-env --profile --set before activation
      system_level:
        type: boolean
        description: "System-level (root) vs user-level. Type-level field: set only under output_types declarations"
    additionalProperties: false
  SSHClient:
    type: object
    properties:
      disable_auto_add_host_key:
        type: boolean
        description: "Disable automatically adding host key to known_hosts on first connection (default: false)"
      disable_strict_key_checking:
        type: boolean
        description: "Disable strict host key checking (default: false)"
      extra_flags:
        type: array
        description: Extra flags passed to ssh (e.g. '-o', 'StrictHostKeyChecking=yes')
        items:
          type: string
      hostname:
        type: string
        description: SSH hostname or IP address
      identity_file:
        type: string
        description: Path to SSH private key
        format: file-path
      known_hosts_file:
        type: string
        description: "Path to known_hosts file for SSH host key verification (default: user's ~/.ssh/known_hosts, bootstrap SSH uses a temporary file)"
        format: file-path
      port:
        type: integer
        description: "SSH port number (default: 22)"
        default: 22
      username:
        type: string
        description: "SSH username (default: root)"
        default: root
    additionalProperties: false
  TransferSource:
    type: object
    properties:
      command:
        type: string
        description: Command whose stdout is streamed to remote_path. At least one of local_path or command is required, when both are set the command receives the path as PANIX_SECRET_LOCAL_PATH
      gid:
        type: integer
        description: Optional Group ID for remote
      local_path:
        type: string
        description: Path to a local file or dir. At least one of local_path or command is required, when both are set the command receives the path as PANIX_SECRET_LOCAL_PATH
      permissions:
        type: string
        description: "File permissions (default: 0700)"
        default: "0700"
        pattern: ^(?:[1-7][0-7]{3}|0[1-7][0-7]{2}|00[1-7][0-7]|000[1-7])$
      remote_path:
        type: string
        description: Absolute path on remote machine
        pattern: ^/.*
        format: uri-reference
      uid:
        type: integer
        description: Optional User ID for remote
    required:
      - remote_path
    dependencies:
      gid:
        - uid
      uid:
        - gid
    anyOf:
      - required:
          - command
      - required:
          - local_path
    additionalProperties: false
  attributes_NixConfig:
    type: object
    properties:
      args:
        type: array
        description: "Arguments passed to the installer after the installer path (default: [install, --no-confirm])"
        items:
          type: string
      curl_default_flags:
        type: array
        description: "List of base flags for curl when downloading the Nix installer (default: [--fail, -#, -L])"
        items:
          type: string
      url:
        type: string
        description: "Installer used to install Nix when the target lacks it (a shell script or an installer binary, e.g. the nix-installer release binary), as an https URL or a local path (default: https://install.determinate.systems/nix)"
        default: https://install.determinate.systems/nix
    additionalProperties: false
  nix_NixConfig:
    type: object
    properties:
      build_default_flags:
        type: array
        description: "List of base flags for 'nix build' command (default: [--no-link, --print-out-paths, --keep-going])"
        items:
          type: string
      build_env:
        type: object
        description: Environment variables for 'nix build' only (merged on top of env)
        additionalProperties:
          type: string
      build_flags:
        type: array
        description: List of extra flags for 'nix build' command (e.g. [--max-jobs, 4])
        items:
          type: string
      build_mode:
        type: string
        description: "Build mode: local or remote. In local mode, build runs on the local machine and the closure is copied to targets. In remote mode, build runs on the first target machine via --store ssh-ng://<target>. For single-machine installables, transfer is skipped (closure is already on target). For multi-machine installables, the closure is copied from the first machine to the rest. (default: local)"
        default: local
        enum:
          - local
          - remote
      copy_default_flags:
        type: array
        description: "List of base flags for 'nix copy' command (default: [--no-check-sigs])"
        items:
          type: string
      copy_env:
        type: object
        description: Environment variables for 'nix copy' only (merged on top of env)
        additionalProperties:
          type: string
      copy_flags:
        type: array
        description: List of extra flags for 'nix copy' command (e.g. [--compress])
        items:
          type: string
      env:
        type: object
        description: Environment variables applied to all nix commands (e.g. NIX_USER_CONF_FILES, NIX_STORE_DIR). Command-specific env fields override these.
        additionalProperties:
          type: string
      experimental_features:
        type: array
        description: "List of flags to enable nix experimental features (default: [--extra-experimental-features, nix-command flakes])"
        items:
          type: string
      extra_flags:
        type: array
        description: List of extra flags applied to both 'nix build' and 'nix copy'
        items:
          type: string
      nixos_install_default_flags:
        type: array
        description: "List of base flags for 'nixos-install' command (default: [--no-root-passwd, --no-channel-copy])"
        items:
          type: string
      nixos_install_env:
        type: object
        description: Environment variables for 'nixos-install' only (merged on top of env)
        additionalProperties:
          type: string
      nixos_install_flags:
        type: array
        description: List of extra flags for 'nixos-install' command (e.g. [--no-bootloader])
        items:
          type: string
      profile_add_default_flags:
        type: array
        description: "List of base flags for 'nix profile add' command (default: [])"
        items:
          type: string
      profile_add_env:
        type: object
        description: Environment variables for 'nix profile add' only (merged on top of env)
        additionalProperties:
          type: string
    additionalProperties: false