zap ↯

Set up and ship to Linux machines you own, from a TypeScript file. Zap reads the machine, shows you the diff, and changes nothing until you say --wetrun.

Convergent machine-state management: a Rust binary and Gro's sandboxed runtime, no agent, no server, no state backend. Over SSH or on your own laptop. Debian/Ubuntu and Alpine. Pre-alpha.

a config, a run

A zap.ts is a function that declares a target and resources. It runs in a sandbox with no network, no writes, no environment, no clock, and emits a JSON declaration; the engine does the rest.

// zap.ts export default (zap) => { zap.target({local: true, package_manager: 'apt', service_manager: 'systemd'}); zap.pkg({id: 'ripgrep', from: {apt: 'ripgrep'}}); zap.file({ id: 'gitconfig', path: '~/.gitconfig', content: {type: 'inline', content: '[user]\n\tname = Ada\n'}, }); }; $ zap apply apply — target local (dry-run) user: ada home: /home/ada target: {"local":true,"package_manager":"apt","service_manager":"systemd"} [+] cache-update-apt (script) check: true > sudo apt-get update [+] gitconfig (file) path: ~/.gitconfig content: inline (19 bytes, sha512 0435b012ac1a81df…) [+] ripgrep (package) > sudo DEBIAN_FRONTEND=noninteractive apt-get install -y ripgrep (dry-run — re-run with --wetrun to apply) plan_hash: d317a15e82f2f1117f0d9fa1fdafc079b70f9e3ac5e3103c4b3333f1b6afeab0 $ zap apply --wetrun apply — target local (wetrun) user: ada home: /home/ada target: {"local":true,"package_manager":"apt","service_manager":"systemd"} ok cache-update-apt 2.8s ok gitconfig 0.0s ok ripgrep 3.1s applied: 3 ok, 0 failed, 0 skipped (of 3) converged local in 6.4s, the re-detect included plan_hash: d317a15e82f2f1117f0d9fa1fdafc079b70f9e3ac5e3103c4b3333f1b6afeab0

Point the target at a host instead and the same config converges a server over SSH.

provision, then ship

zap apply converges the host: packages, files, users, services with restart triggers, PostgreSQL, swap, a firewall, from-source builds pinned to their source. zap deploy then ships your app to it as a versioned release with an atomic swap, a health gate, and rollback, and refuses to ship onto a host that has drifted. The shipped recipes carry the standard pieces: SSH hardening, a hardened systemd or OpenRC unit, an nginx site with a CSP, certbot, fail2ban.

the loop

  1. describe — declare what should be true of the machine, in TypeScript
  2. detect — read what the machine looks like now, live, every run
  3. plan — the difference, with a hash — the dry run
  4. apply — change only that difference, and only the plan you reviewed
  5. observe — read the machine again; typed events, not log soup

what it does differently

  • A wetrun executes only the plan you reviewed. Dry run is the default, with no flag to auto-approve. --wetrun re-plans against the live machine and refuses unless the hash matches the plan you saw; on a terminal, when the plan isn't the reviewed one, it shows you the plan and asks for the start of its hash first.
  • Unknown means hold. A resource Zap can't read is left out of the plan and reported, exit 1. It never reads as “converged” because a probe failed.
  • Every run reads the live machine. No detection cache, no stored copy of the machine. Firewall rules, SSH keys, sudoers, and database auth are read live, because they're what gets changed by hand.
  • Apply checks its own work. After acting, Zap reads the machine again and fails on anything that didn't converge. A reload a failed run owed is remembered on the host and re-fired.
  • The config can only describe. Secrets are zap.env('NAME') references, resolved when Zap acts and masked everywhere else.

what Zap is not

  • not a cloud provisioner — no VPCs or DNS; pair it with OpenTofu.
  • not an orchestrator — no branching on mid-run results.
  • not a fleet tool — one host per config, resources in order.
  • not an agent platform — nothing runs on the host between runs.

How it compares to Ansible, pyinfra, Terraform, Pulumi, NixOS, Puppet, and Kamal, with tables: comparison.