Snapshots
Capture the full state of a deployment workflow at a point in time, then replay it later in the TUI for inspection, debugging, or sharing (for example, as context for an LLM).
A snapshot is a self-contained JSON file containing machine states, phase results, command outputs, inspect metadata, timing information, and the theme name the TUI was using. Replaying a snapshot never depends on your current working directory or on themes files still being present: when the recorded theme is not available, the default theme is used. Real snapshot examples live in the examples directory. Here is what one contains (trimmed for brevity):
{ "nix": "nix (Nix) 2.35.1", "snapshot": { "panix_version": "0.9.1", "start_time": "2026-08-15T16:46:07.799909311+02:00", "reason": "manual", "snapshot_time": "2026-08-15T16:47:10.796833231+02:00" }, "phases": ["inspect", "build", "transfer", "activate"], "flags": { "config": "examples/panix.deploy.yml", "tags": ["personal-workstation"], "output": "tui" }, "fleet": { "flakes": [ { "key": "infrastructure", "value": { "url": "../infrastructure", "installables": [ { "key": "nixosConfigurations", "value": [ { "key": "personal-workstation", "value": { "machines": [ { "key": "personal-workstation", "value": { "ssh": { "hostname": "10.0.200.48", "port": 22222, "username": "root" }, "meta_inspect": { "reachable": true, "is_root": true, "bootstrapped": true, "architecture": "x86_64", "generations": { "current": 205 }, "nixos": "26.11 (Zokor)", "kernel": "7.1.5" }, "logs": { "phase_logs": [ { "key": "inspect", "value": { "command_logs": [ { "description": "bootstrap detection", "command": "ssh ... personal-workstation 'cat' '/etc/os-release'", "output": ["ID=nixos", "PRETTY_NAME=\"NixOS 26.11 (Zokor)\"", "VERSION=\"26.11 (Zokor)\""], "time_and_state": { "duration": 11652245 } } ] } }, { "key": "activate", "value": { "command_logs": [ { "description": "activate", "command": "ssh ... personal-workstation '/nix/store/.../bin/switch-to-configuration' 'switch'", "output": [ "activating the configuration...", "setting up /etc...", "restarting the following user units: nixos-activation.service", "the following new units were started: NetworkManager-dispatcher.service" ], "time_and_state": { "duration": 7738726666 } } ] } } ] }, "machine_state": { "status": "done", "phase": "activate", "active_ssh": "regular" } } }, { "key": "fake", "value": { "ssh": { "hostname": "fake", "port": 22, "username": "root" }, "meta_inspect": {}, "logs": { "phase_logs": [ { "key": "inspect", "value": { "command_logs": [ { "description": "SSH reachability check", "command": "", "output": [], "time_and_state": { "duration": 66892226, "end_error": "regular SSH is unreachable" } } ] } } ] }, "machine_state": { "status": "failed", "status_msg": "SSH unreachable", "phase": "inspect", "error": "reachability check failed: regular SSH is unreachable" } } } ], "meta_build": { "closure": "/nix/store/bh3m91dqz2390fwgmvda408f2dnl8p0s-nixos-system-personal-workstation-26.11.20260802.6438090" }, "logs": { "phase_logs": [ { "key": "build", "value": { "command_logs": [ { "description": "build system closure", "command": "nix ... build --no-link --print-out-paths ../infrastructure#nixosConfigurations.personal-workstation.config.system.build.toplevel", "output": ["/nix/store/...-nixos-system-personal-workstation-..."], "time_and_state": { "duration": 51724055792 } } ] } } ] } } } ] } ] } } ] }}Each machine carries meta_inspect (reachability, OS, architecture, generations), machine_state (status, phase, error), and logs.phase_logs with full command outputs; the flake level adds meta_build.closure with the built store path.
Taking Snapshots
Section titled “Taking Snapshots”Three ways to take a snapshot:
| Method | Description |
|---|---|
Press s in TUI | Manual snapshot at any time |
--snapshot.on-retry | Automatic snapshot before retrying failed phases |
--snapshot.on-exit | Automatic snapshot on exit |
Snapshot files are written to --snapshot.dir (default: current directory) with the naming format:
panix-snapshot-<start_epoch>-<snapshot_epoch>-<reason>-<suffix>.jsonWhere <reason> is manual, retry, or exit, and <suffix> is a short random string so two snapshots taken in the same second do not collide.
Replaying a Snapshot
Section titled “Replaying a Snapshot”panix snapshot --path panix-snapshot-1776379281-1776379290-manual-x7k2m9.jsonReplay opens the familiar TUI view with all phase statuses, build logs, command outputs, and machine stats frozen at the time the snapshot was taken. Phases and commands that were running at capture time also appear as running (loading spinners). The r (retry) and ctrl+r (restart) keybinds are disabled since the workflow is not running.
For the panix snapshot command, see Other Commands; for the --snapshot.* capture flags, see Deploy Flags.
Configuration
Section titled “Configuration”flags: snapshot: dir: . # Directory to save snapshots on_retry: true # Take snapshot before retry on_exit: true # Take snapshot on exit