punix 0.2.0

Punix v2 — a typed, order-independent declarative build & multi-backend service deployer on the inheritance-calculus model

Punix

Install tools, set up machines, deploy apps — without breaking anything.

Punix is a package manager and service deployer for macOS and Linux. Every install is reversible, every deploy can be rolled back in one second, and the same workflow runs on your laptop, your VPS, or any host you can reach over SSH.

What you get

• Reproducible, from-source builds. Each package builds into its own hash-named directory in a content-addressed store. The same recipe and sources produce a bit-for-bit identical result — the build you run today and the one you run in two years match, even if the upstream tarball server is long gone.
• Atomic installs and updates. Your active profile is a directory of symlinks on your $PATH. Installing, updating, or switching to "the set I had last week" flips the live state in a single syscall. Uninstall is exact — no leftover files, no broken links. Two versions of the same tool can coexist.
• One-second rollback. Every deploy is a complete numbered snapshot; the previous one stays whole on disk. Rollback just repoints a symlink — no rebuild, no reconfigure, no replay. There is no half-deployed state, even after a power loss mid-deploy.
• Deploy anywhere, one command. Describe your stack once — config files, binaries, and service units — and target systemd, launchd, supervisord, docker-compose, or a remote host over plain SSH. SSH deploys use real ssh/rsync with no agent or daemon on the target; only content that's actually new is transferred.
• A configuration language that catches mistakes early. Recipes and stacks are written in PCL and type-checked end-to-end before any build runs. A typo, a missing dependency, a bad URL shows up instantly with a file:line:col location — not at minute 11 of a 12-minute build.

Install

curl -fsSL https://punix.lab.abilian.com/install.sh | sh

The installer prints what it will do and pauses before doing it. It only writes under ~/.punix/, and it plays nicely with an existing Homebrew setup. Prefer Python packaging? pip install punix works too (Python 3.13+). See the install guide for other paths.

A quick taste

Install a few tools into your profile:

punix install ripgrep fd wget

Or describe a package or stack in PCL:

module curl {
  version = "8.20.0"
  recipe  = "std.autotools"
  source  = {
    type = "url"
    url  = "https://curl.se/download/curl-8.20.0.tar.xz"
    hash = "63fe2dc1...e2b896"
  }
  deps = [openssl.pname, zlib.pname]
}

…then check it, deploy it, and roll back if you need to:

punix check stack.pcl                          # type-check, no build
punix service deploy MyStack --file stack.pcl  # → gen-002
punix service rollback MyStack                 # → gen-001, instantly

Deploy to a server instead — same file, same command, just add a target:

punix service deploy MyStack --file stack.pcl --target ssh://you@server

Why not just use…?

• Homebrew — great for installing tools, but not a service deployer, and brew update can move installed paths underneath you. Punix coexists with it.
• Nix — the same content-addressed store and correctness model, with a typed, lighter configuration language.
• Ansible — built to mutate existing hosts step by step; Punix replaces a host's app stack atomically and rolls the whole thing back in one move.
• Docker Compose — Punix can drive a Compose stack as one of its backends.

There's a fuller comparison in the docs.

Documentation

Full docs live at punix.lab.abilian.com:

• Install → first build → first deploy
• The PCL configuration language
• Deploy, rollback, and SSH
• CLI reference
• What works today and the roadmap

Runnable demos live in examples/ — start with examples/hello for a first build, or examples/tangled-deploy for a real server built from source with HTTPS, secrets, and reboot-persistence.

Contributing

uv sync            # set up the environment (needs uv + Python 3.13+)
make test          # run the test suite
make lint          # ruff + type checkers

Every advertised property is backed by a conformance test that gates each release. Punix is under active development — contributions and issues are welcome.

License

Apache 2.0.