panix

README

Panix

Universal NixOS Deployment Tool

Stateless, phase-oriented deployment with real-time visibility across multi-flake fleets

Documentation

---

[!WARNING] The tool is currently in beta stage. There might be breaking changes.

Demo

Screenshot:

---

The Problem

Deploying NixOS as a single machine or at scale is a fragmented mess. You bootstrap bare metal with nixos-anywhere, then use nixos-rebuild for one machine at a time or orchestrate fleets with Colmena, deploy-rs, etc. Each tool is excellent, in isolation, the moment you try to compose them, you're on your own.

There's no unified pipeline. Bootstrap and deploy are separate workflows with separate configs. A failed phase means restarting from scratch, and partial progress is lost. Failures hide in scrollback logs or are non existent, discovered only after the damage is done. Most tools require modifying your flake to include their module or output, preventing you from bootstrapping as the tool is only build for deploy.

Panix eliminates all of this: one binary, one config file, full lifecycle. From bare metal to running NixOS, in a single orchestrated pipeline.

What Panix Does

Panix is a stateless deployment orchestrator for NixOS flakes. It manages the entire lifecycle of deploying NixOS configurations to machines, from provisioning bare metal to ongoing updates, as a single, observable, recoverable pipeline.

Six phases, one execution:

Inspect → Bootstrap → Build → Transfer → Secrets → Activate

Each phase has a defined scope and purpose:

• Inspect detects OS, architecture, SSH reachability, and existing generations.
• Bootstrap kexecs into a NixOS installer, partitions disks with disko, and optionally encrypts.
• Build compiles the system closure once per configuration, deduplicated across machines sharing the same config.
• Transfer copies closures to targets in parallel via nix copy.
• Secrets rsyncs files with ownership and permissions, never entering the Nix store.
• Activate switches to the new configuration, or installs from scratch on fresh machines.

And an additional phase for rollbacks.

What makes it different:

• Real-time TUI: per-machine, per-phase visibility. Watch every phase unfold. Press r to retry only failed phases. Press ctrl+r to restart the entire workflow. No scrollback parsing.
• Scope-aware deduplication: three machines sharing the same nixosConfiguration trigger one build, not three.
• Remote builds: build on a target machine when it has more resources or a different architecture. The closure copies directly between machines.
• Multi-flake deployments: span multiple repositories in a single run. Each flake is independently buildable.
• Tag-based filtering: every name is a tag. Deploy subsets: panix --tags production, panix --tags webserver.
• Secret management: files transferred with configurable uid, gid, permissions. Never stored in /nix/store. Bootstrap-aware path prefixing.
• Hooks system: post_bootstrap_hooks, post_bootstrap_install_hooks, post_bootstrap_provisioned_hooks. Special commands: waitForOnline, waitForOffline.
• Dry-run modes: preview without connections (--dry-run), or with real machine inspection (--dry-run-with-inspect).
• Snapshot & replay: capture workflow state to JSON. Replay in TUI for debugging or sharing.
• Flake-agnostic: zero modifications to your flake. Configuration lives in panix.yml.

---

At glance

panix.yml:

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

# Minimal Panix configuration demo.
#
# All fields have sensible defaults:
#   config file: panix.yml          (can be overridden with -c)
#   flake url:   .                  (current directory, can be omitted)
#   build_mode:  local              (build locally, then nix copy)
#   activation:  switch             (switch-to-configuration switch)
#   SSH:         machine name matched against ~/.ssh/config
#   flake attr:  nixosConfigurations.<name>
#   inheritance: fleet → flake → configuration → machine
#                (tags, secrets, SSH, bootstrap, nix cascade down)

fleet:
  flakes:
    my-infra:
      # url defaults to ".", can be omitted when flake is in current dir
      configurations:
        workstation: # nixosConfigurations.workstation
          machines:
            workstation: # matched against ~/.ssh/config

        servers: # multi-machine, build once, copy to both
          machines:
            server-eu: # matched against ~/.ssh/config
            server-us:
              ssh: # SSH not in ~/.ssh/config → specify here
                hostname: server-us.example.com

        vps: # another single machine
          machines:
            my-vps:
              ssh:
                hostname: 10.0.0.100
                port: 2222

And run it with:

nix run github:mihakrumpestar/panix -- deploy

For the complete schema, see panix-schema.yaml.

---

Documentation

Available on panix.xyz or locally in docs dir.

---

Contributing

Contributions are welcome! Whether it's bug reports, feature requests, constructive criticism, or pull requests - all feedback is appreciated. See CONTRIBUTING.md.

---

License

Panix is licensed under AGPL-3.0. Packages under pkg are licensed under MIT.

For more details about licenses, see choosingalicense.com/licenses.

---

If Panix has improved your deployment workflow, consider giving it a star.