pu

name

pu

description

Provision and drive a `pu` box — an Incus container used as a clean Linux host for CI, builds, and evidence capture. Use when you need to run something on a fresh remote box instead of the user's machine: `nix run` a build, run CI against a real host, capture screenshots/video off-machine, or reproduce on a pristine environment. Covers create/connect/scp/destroy, running remote commands, copying artifacts back, and the no-egress failure mode. Triggers on "pu box", "spin up a box", "run this on a box", "ephemeral host", "pu create/connect/destroy".

pu — on-demand Incus boxes

pu hands out Linux containers. Each box is a clean NixOS host with Nix

• flakes, reachable over SSH through pu's own proxy. Use one whenever work should run off the user's machine — a CI run, a nix run build, evidence capture — so nothing local is at risk and the environment is reproducible. A box can be short-lived (spin up, use, destroy) or kept around long-term — the lifetime is yours to choose.

Lifecycle

pu create "$host"          # create; writes ~/.pu-state/$host/ssh_config
pu list                    # NAME + LOCATION (the physical host it landed on)
pu connect "$host"         # interactive ssh
pu connect "$host" -- CMD  # run CMD on the box and return
pu destroy "$host"         # tear down — always do this when finished

Name is positional. Pick a descriptive, collision-free name (e.g. ).