Zap sets up and ships to Linux machines you own, from a TypeScript file.

You have a few Linux machines, and each one has to be set up a particular way and kept that way as its needs change. With Zap you declare what should be true of a machine: these packages installed, this file with this content, this user with these SSH keys, this service running, this firewall. Zap reads the machine, shows you exactly what it would change, and changes nothing until you pass --wetrun. Run it again tomorrow and it touches only what drifted. The same tool then ships your app to that machine as a versioned release with a health check and rollback.

If you know Terraform, Zap brings its plan-then-apply discipline to the inside of a machine. If you know a virtual DOM, it works the same way: you describe the whole result, and it works out the smallest set of changes to get there. Unlike both, Zap keeps no stored copy of the machine: it diffs against the machine itself, read fresh on every run, so a change someone made by hand shows up in the plan.

Zap is a Rust binary that works over SSH or on the machine it runs on, with no agent on the host and no server. It evaluates your zap.ts with fgro, Gro's sandboxed JS runtime (install.md).

Who it's for

• You run a few Linux machines by hand. A laptop, a VPS or two, a home server. You want them described in one place and set up the same way every time, without learning a fleet tool.
• You ship your own services. A web app behind nginx with PostgreSQL on the box, deployed as release directories with an atomic swap, where the deploy refuses to ship onto a host whose config has drifted.
• You let an assistant drive. An AI agent, or a teammate who isn't an ops engineer, runs the tool for you. Planning changes nothing, so they can do it freely; you review the plan, and a wetrun executes only that plan. Every run ends in an exit code that says what was established, and --json streams a wetrun as typed events rather than free-form logs.

What a run looks like

The cache-update-apt change is the package index refresh Zap puts in front of an install. The wetrun planned again, got the same plan_hash the dry run printed, and only then acted. Had the machine changed in between, it would have shown the new plan and refused it, or, on a terminal, asked before running it.

Point the target at a host instead and the same config converges a server over SSH. Getting started walks through both.

What Zap does differently

1. 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, then refuses unless the plan matches the one you saw, by hash; on a terminal, when the plan isn't the reviewed one, it shows you the plan and asks first.
2. Unknown means hold, not guess. A resource Zap can't read is left out of the plan and reported as undetermined, with exit 1. It never reads as "converged" because a probe failed. (A few kinds whose create step is idempotent read a failed probe as absent; see detection.md.)
3. Every run reads the live machine. No detection cache, no stored copy of the machine. The security controls (firewall rules, SSH keys, sudoers, database auth) are read live every time, because they are what gets changed by hand.
4. Apply checks its own work. After acting, Zap reads the machine again and fails the run if anything didn't converge.
5. The config can only describe. zap.ts runs in a sandbox with no network, no writes, no environment, no clock, and emits a JSON declaration. Secrets are references, resolved by Zap when it acts and masked everywhere else.

Plus: a reload a failed run owed is remembered on the host and re-fired, and fetched content is pinned by hash in a lock file next to the config.

What Zap converges

• Software: apt and apk packages, apt repositories, and from-source builds pinned to their source archive.
• Files: files (inline, templated, copied, or fetched and pinned), directories, and symlinks.
• Users: shell, home mode, SSH keys, sudoers, and groups.
• Services: systemd and OpenRC, with restart and reload triggers.
• PostgreSQL: databases and roles, with pg_hba rules.
• System: swap files and firewalls (ufw, nftables).
• Everything else: idempotent scripts, installers, assertions, and pipelines.

The full reference is resources.md.

Hosts: Debian/Ubuntu and Alpine. Zap manages real servers in both families, and the firewall, user, and database controls are read live on both.

What Zap is not

• Not a cloud provisioner. No VPCs, load balancers, DNS, or managed databases, and no provider ecosystem. Zap converges the inside of machines you already have. Pair it with OpenTofu or Pulumi for the outside.
• Not an orchestrator. No data-dependent branching mid-run. A script's shell can do anything, but Zap doesn't model it.
• Not a fleet tool. One host per config, resources applied in order. Loop a shell over configs for a handful of hosts; reach for Ansible or pyinfra for hundreds.
• Not an agent platform. Nothing runs on the host between runs.
• Not a remover. Delete a resource from the config and the thing stays; Zap reports it as orphaned. Declare removals explicitly.
• Not macOS or Windows. Zap manages Linux hosts only.

The full picture, against each alternative: comparison.md.

Status

Zap is pre-alpha and has one maintainer. It runs the servers of the project it comes from and the maintainer's own machines. The resource set is small and fixed, there is no plugin system, and the config schema will change before 1.0 without a compatibility layer. Read security.md before pointing it at a machine you care about, and faq.md for the questions that come up first.

Where next

• install.md, then getting-started.md
• concepts.md: the model, in one page
• configs.md: writing zap.ts
• cli.md: every command and exit code

Zap is built from source, and so is fgro, Gro's runtime, which evaluates your TypeScript config. Zap never runs a config without it.

What you need on your machine

Build

Zap depends on crates from the sibling fuz repository, resolved by relative path, so the two checkouts sit next to each other:

cargo xtask install makes a release build and puts the binary at ~/.zap/bin/zap. Add that directory to your PATH:

Then:

Debug and static musl builds are in contributing.md.

The binary on your PATH doesn't update when you pull. Run cargo xtask install again after pulling changes.

Getting fgro

Build fgro from a checkout of Gro, on x86_64 Linux. The build downloads and verifies a pinned V8 first, and the binary must carry its startup snapshot, which cargo xtask build embeds:

The binary is target/gro_snapshot/release/fgro. Don't point ZAP_FGRO at it there: each build replaces it, and a project's zap.lock pins the exact binary its configs are evaluated with (lock.md), so a rebuild would make every pin stale. Copy it to a place you update deliberately, and name that copy:

Zap takes the binary by absolute path, from --fgro <path> or ZAP_FGRO, and never looks it up on PATH. sudo resets the environment, so under sudo only --fgro reaches Zap: sudo zap apply --fgro ~/.zap/bin/fgro. Name the binary itself, not a link to it or a wrapper script.

Then pin it in each project: zap lock evaluates the config with that binary and records its blake3 in zap.lock; commit the lock. When you update the copy, run zap lock again in each project.

Zap and fgro talk through a versioned eval protocol. An fgro that answers in a version this zap doesn't read is refused, exit 2, whatever the pin says: update the older of the two, then zap lock.

Types and recipes for your config

A config needs a project of its own: a package.json beside it, or in a directory above it that you own and no other user can write. One holding only "type" or "sideEffects" doesn't count; a "name" is enough. A .js module the config imports needs "type": "module":

A bare config needs nothing else installed:

For editor completion and type checking, import the builder type. The import is type-only, so the evaluator strips it and needs nothing resolvable at run time:

To use the shipped recipes (nginx sites, hardened systemd units, SSH hardening, certbot, firewalls), your project needs the @fuzdev/zap package resolvable under node_modules/@fuzdev/zap. The package isn't published to npm; point a path dependency at your checkout:

npm install then symlinks the checkout into node_modules. That link, in the config's own project, is the one way its import of @fuzdev/zap resolves: a node_modules above the project is never searched (security.md). The checkout must not sit under a directory every user can write. fgro resolves recipe imports through the package's exports, which carry a gro condition pointing at the TypeScript sources, so a recipe edit in the checkout reaches your next plan with no build step. TypeScript and your editor resolve the same imports through the built dist/, so run npm install && npm run build in the zap checkout once (and after pulling) to keep types current.

See recipes.md for the catalog.

What a target needs

A local target needs sudo only if the config touches files you don't own or runs privileged commands. A remote target needs sshd, a POSIX shell with coreutils or BusyBox, and a sudo that works without a password for the user Zap connects as. Details per distro: targets.md.

Uninstall

Remove ~/.zap (the binary and, unless ZAP_HOME moved them, the caches, last-run reports, deploy previews, SSH sockets), and $ZAP_HOME if you set one; a zap run under sudo keeps its own, in the home sudo gives it (root's ~/.zap). Zap keeps no other state on your machine. On a target it leaves only what your config declared, plus any pending-trigger markers under /var/lib/zap/pending/, a build's <output>.zap-build provenance sidecar, an extracted remote file's .zap_remote_hash sentinel, and in a deploy's path, deploy_info.json and the .zap-deploy.lock file. A run killed outright can also leave a .zap.* staged file beside a file it was writing, or a release archive (.zap-deploy-<user>-<version>.tar.gz) in a deploy's path. A killed deploy can leave releases/.zap-stage and releases/.zap-old-* there too, which the next deploy to that path cleans up.

Two walks: your own machine first, then a server over SSH. Each takes a few minutes. Install Zap and fgro before you start.

1. Your own machine

Make a directory for the config, give it a package.json, which marks it as the config's project, and write a zap.ts that manages a directory and a file you own, so nothing needs sudo:

A config is a function. It receives a builder and declares a target and resources; it returns nothing. Every resource has an id you choose, which is how other resources and Zap's output refer to it.

Pin the evaluator. zap lock records the fgro build that evaluates the config in zap.lock; every other command that reads the config refuses until it does:

Preview. zap apply without --wetrun reads the machine and shows what it would change. It changes nothing, and exits 2 to say changes are pending:

[+] is a create, [~] an update, and the lines under each say what the change declares: a file's content shows as its length and the start of its SHA-512, never the bytes. The plan_hash names this exact plan. zap plan prints the same plan with a change count and exits 0: it reports, where apply judges.

Apply. Now act:

After the changes ran, Zap read both resources again and found them converged, which is why the exit was 0. Had anything still read wrong, the report would say RESIDUAL and exit 1.

The wetrun went through because your preview a moment ago bound it: a wetrun executes only the plan you reviewed.

Had you run zap apply --wetrun first, with no preview behind it, it would have shown the plan and asked:

Typing 5bb79cc9 would have run exactly that plan: the answer is the start of a hash you can only know by looking at the plan. Declined, it changed nothing, exited 2, and became the preview: running it again executes if nothing moved. Without a terminal (a script, CI, < /dev/null) the wetrun doesn't ask; it renders the same plan under a REFUSED banner and stops the same way. --expect-plan <hash> binds explicitly. concepts.md has the rules.

Status. zap status tells you what the last run saw, offline:

Again. Preview once more:

Now edit hello.txt by hand, add a line, and run zap plan --diff: the file reads [~] hello with ~ content: differs → inline (15 bytes). That is drift, and zap apply --wetrun would put the declared content back.

Add a package

Declare the package manager on the target and a package:

zap apply now plans two changes: cache-update-apt, the index refresh Zap puts in front of an install, and the apt-get install -y ripgrep itself, both run under sudo on the wetrun. Packages are detected by existence: Zap asks dpkg-query whether ripgrep is installed, not which version. An entry written name=version pins a version instead (package names).

Add types

For completion in your editor, import the builder type (type-only, so the evaluator needs nothing installed):

See install.md for resolving the import.

2. A server over SSH

You need a Debian, Ubuntu, or Alpine host you can reach as a user who has password-less sudo. On a fresh Debian cloud image the stock user usually qualifies. On Alpine, as root:

Install your key and check that plain ssh works silently:

The config. It lives in a project of its own, with a package.json as before. The host and user are references: they come from your environment when Zap runs, never from the config file, so the config can be committed and reused. The user's variable is USER_NAME and not USER on purpose: your shell already sets USER, so a run that forgot the env file would connect as your local login name where an unset USER_NAME fails.

The env file. Put the variables in a file Zap loads with --env-file. Keep it out of version control; commit a .example instead.

Drive it.

The dry run shows the apt-get update and the apt-get install, the systemctl enable and start, each with the exact command, and the file it will write. The wetrun reports 4 ok: the three resources plus the index refresh.

Edit the probe file on the host, or systemctl stop chrony, and zap plan shows the drift. That loop, plan then wetrun, is all of Zap.

What to commit

Where to go next

• A real server. The recipes carry the standard pieces: SSH hardening, a hardened systemd or OpenRC service, an nginx site with a CSP, a firewall, certbot, fail2ban, PostgreSQL. configs.md shows how to compose them.
• Shipping an app. zap deploy releases a build to the host you just converged, with a health gate and rollback: deploy.md.
• A host that locks itself down. When SSH hardening changes the user Zap connects as, declare both users and run the first apply with --bootstrap: targets.md.
• What every command and exit code means. cli.md.

The ideas behind every zap command. Read this once; the other docs assume it.

The loop

You describe a machine in zap.ts: these packages, this file with this content, this user with these keys, this service running. Zap detects what the machine looks like now, plans the difference, applies only that difference when you say so, and observes the result by reading the machine again. Every command is a slice of that loop.

A task fits Zap when it can be put as: I want the machine to look like X. What does it look like now? What needs to change? Do it. Tell me what happened.

Convergence

A resource is one typed piece of desired state with a stable id. Most resources are convergent: Zap reads their current state, compares it to the declaration, and changes only what differs. Re-running is always safe. A converged resource contributes nothing to the plan.

How much of the live state a declaration claims depends on the field:

One resource kind is imperative: a pipeline runs every time, as does zap deploy, which produces a new release every run. You make their steps safe to repeat.

Drift is the gap between the live machine and the declaration: a file edited on the host, a service stopped, a firewall's default policy flipped at the console. Zap doesn't track drift; it finds it by reading the machine on every run, and the plan is the repair.

What Zap doesn't do: it never removes something you stop declaring. Delete a package resource from the config and the package stays installed. zap status lists such resources as orphaned, as a warning. To remove something, declare the removal (a script whose check confirms it's gone).

Detection

For each resource, detection answers one question, does the desired state already exist?, with one of four verdicts:

When Zap can't read a resource (a probe failed, a remote path's home isn't declared, a tracked pin has no lock entry), it doesn't guess: the resource is held, the command leads with an UNDETERMINED banner naming it and why, and the exit code is 1 (deploy's preflight refuses with 2), never 0. Nothing carries over between passes; the next run reads it again.

The hold spreads to what can't run without the held resource: a change that depends on it (directly, or through resources that are converged) and a change that would restart or reload it are held behind it, and the banner lists them under it. detection.md

A few kinds on the bring-up path read a failed probe as absent instead, because on a fresh host the probe fails for the reason the config exists (ufw status fails before the same run installs ufw). Which kinds, and how database splits the two cases: detection.md.

Depth follows idempotency. If re-running a change is a true no-op, shallow detection is fine: a package is checked for existence (or, when its name pins a version, that version), because installing it again does nothing. If re-running has side effects, detection goes deeper: a file is compared by digest, mode, and owner; a user's keys and sudoers by content; a firewall rule by rule. A script's depth is yours: its check command is the whole idempotency contract.

Everything is read live, every time. Zap keeps no detection cache. A stored answer is only sound when nothing else could have changed the machine, and Zap never assumes it is the only writer. The security controls make the point: firewall, user, and database guard the host's access surface and are exactly what gets changed by hand.

Dry run and wetrun

No command changes the target unless you pass --wetrun. zap apply shows what would change and exits 2 when something would; zap apply --wetrun changes it. Most tools make the dry run the option. Zap makes it the default, and gives the flag that acts an unusual name so it isn't typed by accident or appended by a script's --yes habit. The default is safe with no terminal and no prompt, which is what makes Zap safe to hand to a script or an AI assistant.

The plan

A plan is the changeset for one run: per resource, the action (create or update), the steps, the desired state (its references kept as written), and the dependency order. It is content-addressed: plan_hash is the blake3 of the plan's canonical JSON and of the text Zap's own steps execute, printed at the end of every plan and apply.

Two things with different stability go into it. The declaration is a function of your config and the files it reads: the same zap.ts over the same files evaluates to the same desired state, because the config runs in a sandbox with no network and no environment, with the clock and randomness closed and the time zone and locale fixed (configs.md). The changeset also depends on what detection found. So the hash addresses "what this run decided to do against this target."

The plan is for one machine. Its header names the target it resolves to; a local plan also names the user Zap runs as and the HOME a ~ resolves to:

A remote plan prints the connecting user in a user: line, and the host in a host: line when the declared host is a reference. All of it is in the hash, so one config under two env files is two plans, and so is the same host with and without --bootstrap. A local plan's hash covers the user Zap runs as and its HOME, so a review made as you binds no local wetrun under sudo, which runs as root, or under another HOME.

The plan is for one environment too. A reference in a resource stays written as its reference ({env:NAME}), and the plan records beside it what each reference its changes use resolves to, printed in a references: block under the target: the value of a plain one, and for a secret only that it is one. So plan_hash covers those values: the same config under another value of APP_DIR is another plan. A secret reference's value is never in the plan or its hash, so rotating one changes neither.

A wetrun executes only the plan you reviewed

A wetrun doesn't take a saved plan as input; it detects and plans again, because the machine may have moved. What it guarantees instead is that the plan it executes is the plan you saw. Before it changes anything, it compares its fresh plan_hash against the plan you reviewed:

• --expect-plan <hash> names the reviewed plan explicitly, and the wetrun executes only if the fresh plan has exactly that hash;
• with no flag, the reviewed plan is the one in this host's last-run report, when the pass that wrote it was a preview: zap plan, a dry zap apply, or a wetrun that refused. Its recorded plan_hash must equal the fresh one.

Otherwise the wetrun refuses. It changes nothing, renders the plan it would have run under a REFUSED banner that says why (no preview yet, the last run wasn't a preview, or the plan changed since the preview), records that render as the new preview, and exits 2. The everyday flow is zap apply, read it, zap apply --wetrun. A wetrun fired cold becomes the preview, and the next one executes if nothing moved. A preview covers one wetrun: one that executes, whether its changes succeed or fail, spends it, and of two started on one preview only one goes on. An agent given --expect-plan with the hash it showed you can execute only that plan: the same changes, on the same machine, as the same user, with the same values for every reference that isn't a secret. An empty plan needs no review.

On an interactive terminal, a wetrun whose plan has no review asks for the first eight characters of its plan_hash instead of refusing (cli.md).

A plan can only be reviewed if it names its machine. A plan whose host or connecting user resolves through a reference Zap masks has no plan_hash: zap plan and a dry zap apply show it under an UNBINDABLE note, and zap apply --wetrun is an error before anything runs, even when nothing would change. The ways out are in env.md.

zap deploy has its own plan, hash, and recorded preview, and its wetrun follows the same rule against them (deploy.md).

Apply asserts convergence

A wetrun doesn't stop at command success. After the changes run, it reads every resource again. Any resource that still doesn't read converged is reported as RESIDUAL and the run exits 1: a script whose check still fails after its run, a mutation that read back wrong. A change that failed or was skipped is the run's failure already, a held resource its undetermined, and a pipeline never reads converged (it always runs), so none of them is residual. "Applied: N ok" alone would be a claim about commands; the re-detection makes it a claim about the machine. If the re-detection itself fails, the run says so and exits 1 too, because "converged" was not established.

The last-run report

Every detection pass writes a last-run report under ~/.zap, one per config and host, latest only (none for a host that resolves through a masked reference, since it would stand for every machine the reference names): when it ran, which command, the host, each resource's verdict and a hash of its declaration, the names of the references it couldn't resolve, the batches it ran, and the plan_hash when the pass planned. Nothing the target returned is in it, and no secret's value reaches any hash (env.md).

Detection never reads it. zap status renders it offline, marking each resource whose config changed since the run, and it holds the preview a wetrun binds to. Exit codes are about the last run, not the live machine; the live answer is always zap plan.

Triggers

Service detection reads running and enabled, not whether the service's config is fresh. Triggers close that gap: a file names the services it triggers, or a service names the resources it restart_on / reload_on. When a source changes in the current plan, the service is promoted from skip to restart or reload. A trigger restarts or reloads only a running service: a stopped one is left stopped and starts on the new state when it starts. A trigger on a service declared running: false is a config error.

A trigger fires only on a change in the current plan, so a failed reload would be lost: next run the file is converged and the service is running, on the old config. Zap keeps one marker per owed service on the target under /var/lib/zap/pending/, written before the first source changes and cleared after the service's change completes. A failed reload stays owed and re-fires on the next plan. At least once, never zero.

A held service, whether detection can't read it or it is held behind another, holds every source whose change would trigger it: run alone, the source would owe a restart that no change in the plan performs. Both wait for a plan that can run the service.

The lock file

A moving reference makes intent ambiguous in time: a tracked remote file's URL or a build's source archive can serve different bytes tomorrow. zap.lock, next to zap.ts and committed with it, pins each tracked reference to the blake3 of its resolved bytes. Detection compares the target against that pin, and only an explicit act moves it: zap update (advance one or all), zap lock (rebuild), or a wetrun recording a pin that was missing. A pin that isn't current is withheld from the read-only commands, so the resource holds rather than being compared against stale bytes. Full detail: lock.md.

Targets and privilege

A config has one target: your own machine (local: true) or a host over SSH. Your authority on a remote host is SSH: Zap connects as the user you declare, with your keys, and escalates with the host's sudo. Commands that are privileged by nature (apt-get, systemctl, ufw) carry sudo. On a local target file operations try natively first and escalate only when denied; over SSH they run under sudo. There is no agent, no server, and no shared secret. See targets.md.

Secrets and references

A config never reads the environment. Anything that varies per machine or is secret is written as a reference, which the plan's steps keep as written and Zap resolves when it acts; the plan records what each plain one resolves to, so a review covers it. A secret's value is masked out of every output, event, and report. A secret written literally into a config is rejected when Zap can tell (its value is referenced and set in the environment). See env.md.

Deploy

zap deploy is the one imperative command: it ships a versioned release to a remote host as releases/<version> plus a current symlink, restarts the service, polls health, and rolls back if the health gate fails. Before shipping, its preflight runs the convergence pass and refuses to ship onto a host that has drifted from its config. The same tool that built the machine ships the app. See deploy.md.

How a zap.ts is shaped, what it may and may not do, and the patterns that keep one readable. The per-resource fields are in resources.md.

The shape

A config is a module whose default export is a function. It receives a builder, declares one target plus any number of resources, and returns nothing:

The builder has one method per resource kind (pkg, apt_repo, script, installer, user, directory, file, link, service, database, swap, firewall, verify, pipeline, build), plus target, deploy, mask, unmask, and env (which returns a reference). Every other call returns the builder, so chaining works, and every resource takes these shared fields:

The import is type-only. The evaluator strips it, so a config with no recipe imports needs nothing installed. Without it, write (zap) => and lose completion.

The function may be async: Zap waits for it, so a declaration after an await counts. Once it returns, the builder closes, and a call that arrives later (from a promise the config didn't await) fails the evaluation, even when the config catches the error, so a forgotten await can't drop a resource silently.

Plain TypeScript is the templating language

There is no DSL for loops, conditionals, or includes; the language has them.

Keep every value two resources must agree on (a user name, a config directory, a port) in one constant. Nothing fails when two copies drift apart.

Split a large config into local modules and import them by relative path from the project. The shipped recipes are the same idea packaged: pure functions that return a string or a spreadable payload.

One target per config

A config declares one target. For several hosts, write one config per host (or one module per role, imported by each host's config) and run zap once per host. A zap.env('HOST') reference plus one env file per host is the usual shape. A second zap.target call, or a second zap.deploy, fails the evaluation.

References

A config never reads the environment. Anything that varies per machine or is secret is a reference, zap.env('NAME'), left inert in the declaration and resolved by Zap when it acts, from your environment or an --env-file:

Not every field takes a reference, a wetrun refuses one that is unset or empty, and one Zap reads as a secret is masked out of every output; the rules are in env.md.

~ and $HOME in a path are different: they resolve against the target's home (declared home for a remote target, your own locally), never the operator's. A remote path that uses them with no home declared is undetermined.

mask and unmask

Zap treats a reference as a secret by where it is used (an auth credential), by its name (API_TOKEN, DB_PASS), or by the form of its value (a URL with a password, a private key); the rule is in env.md. Say so where it reads one wrongly:

Both take variable names, not references: zap.mask(zap.env('X')) fails the evaluation, and so does a name given to both.

Order

Resources apply in dependency order: depends_on edges first, and among resources with no edge between them, alphabetically by id, not in declaration order. Declaration order is not a dependency. When one resource must precede another, say so with depends_on; the structural gate rejects a dangling id or a cycle. A trigger is an edge too: a service runs after each resource it restart_on / reload_on and each file that triggers it, and a cycle through those edges is rejected the same way.

Detection for the whole run happens before any change executes. So a probe can't see a tool the same run installs; the detectors on the bring-up path read that failure as "not set up yet" rather than holding (detection.md), and the run both installs and configures. concepts.md has the rule.

An edge is also how a hold travels: a resource detection can't read is held, and every change that depends on it is held behind it rather than run ahead of it (detection.md).

Triggers

A file lists the services it triggers; a service lists the ids it restart_on or reload_on. Either direction works; pick one per pair. When the source changes in a plan, the service is promoted to a restart or a reload. A reload the run couldn't complete is remembered on the host and re-fired next plan (concepts.md).

The sandbox

Your config runs in fgro eval, Gro's runtime, with no network, no writes, and no environment: it can compute and import, and that is all. These rules shape how you write one:

• It lives in a project: the nearest directory at or above it whose package.json holds more than "type" and "sideEffects". The project can't be your home directory or a directory holding it.
• Its imports are static, from that project and the packages it links, and must all resolve: import() is refused, and so are node: built-ins.
• Resolution is strict ESM: a relative import names its extension, and a bare import goes through the package's exports (never its main) under the conditions gro, import, and default. No deno.json or import map is read.

Zap refuses a config that breaks one, exit 2, saying what to change. The walls in full: security.md.

The config's only output is a JSON declaration, which every command validates against a strict schema: an unknown field, a wrong enum value, a value of the wrong JSON type (an array where an object goes, a number where a name goes), or a contradictory combination (a local target with a host, sudo: true on a user) fails with a message that names it.

What a config declares is plain data: strings, finite numbers, booleans, arrays, and plain objects. A NaN, a function, a Map, a Date, a class instance inside a declaration, an undefined array item, or a value that holds itself fails the evaluation with the field's name, where JSON.stringify would have dropped it or written something else. A field is left out by leaving it out, or by giving it undefined (so mode: opts.mode forwards an option that may not be set). A null is an error that names the field, since a null where a mode, a sudo, or a blake3 pin goes would otherwise read as "not managed". The one place a null is data is inside a template variable's value.

Zap also closes what a config could read by mistake and get a different answer from on another run or another machine: the clock, randomness, facts of the machine, and timers. Each throws, naming itself and what to write instead, or isn't there. The time zone and locale are fixed rather than closed: every evaluation runs in UTC, and its default locale is en-US. A config reads no file but the modules it imports, so the same files declare the same thing on every machine.

Consequences worth knowing:

• The clock and randomness throw: Date.now(), new Date(), performance.now(), Temporal.Now.instant(), Math.random(). There is no crypto, no setTimeout, and no Blob or File. Write the value as a literal, or reference it.
• Local time is UTC: new Date(2026, 0, 1) and getHours() read the same as Date.UTC(2026, 0, 1) and getUTCHours() on every machine.
• Comparing and formatting with no locale given use en-US: (1234.5).toLocaleString() is 1,234.5.
• There is no process, no Deno, and no environment API. Use zap.env('NAME'). A guarded read such as globalThis.process?.env?.HOME is undefined, not an error, so a config that falls back on it always takes the fallback.
• What a config prints is not part of the declaration: console writes to stderr, which Zap shows when the evaluation fails. console.time, console.timeLog and console.timeEnd print nothing.
• The evaluation is jitless, so WebAssembly is absent; separately, code generation from strings is off, so eval() and new Function() throw.
• WeakRef and FinalizationRegistry are inert: a weak reference never clears, and a cleanup callback never runs.
• fetch and remote import fail. Vendor what you need or import it from the project.
• A script's run is shell that executes on the target at apply time. The sandbox bounds the config, not the commands it declares. Review them.

What the gates reject

Every command that reads a config runs two machine-free gates before touching anything, and zap config validate runs only them:

• Secrets. A literal that matches a resolvable secret is rejected; reference it with zap.env('NAME').
• Structure. Each of these is rejected:
  • a NUL byte in a string a shell or path would see;
  • a duplicate id, or an id that isn't a name;
  • a blank string where a name, a path, a URL, or a command goes, and a line break or other control character in a field that is one line (a command, a validate included, a file's content and template variables, an env value, and a verify assertion's expect may span lines);
  • a path that must be absolute and isn't, and a path, link target, host, or user that begins with -;
  • a remote target with no host;
  • two resources that manage one thing: the same path, account, service, or database, or a second firewall (resources.md);
  • a template whose placeholders and variables don't match (resources.md);
  • a URL Zap or the target would fetch that isn't https:// (resources.md);
  • a database name, role, or auth.hosts entry that pg_hba.conf would read as something else;
  • a depends_on, triggers, restart_on, or reload_on naming an id that doesn't exist, a triggers naming a resource that isn't a service, or a dependency cycle, trigger edges included;
  • a user whose ssh_keys.keys holds no key;
  • pipeline features the executor doesn't run (env, a max_concurrency above 1, a step's cwd, env, or depends_on);
  • a named firewall profile under nftables, or an nftables firewall with no enabled nftables service in the same config;
  • a service, a file with triggers, or deploy.service on a target with no service_manager;
  • a validate command that is blank or on remote content;
  • a script cwd or a deploy.path that isn't an absolute path;
  • a deploy.shared entry that isn't a plain relative name, or a deploy.artifacts entry beginning with - or @ (deploy.md);
  • an env name beginning with __zap_;
  • a deploy.releases below 2;
  • a blank deploy.health.domain.

Two kinds of mistake fail earlier, when Zap reads the config, so the gates never see them: a value of the wrong form (a package or service name that isn't one word, a mode above 7777, a port or a count of 0), and a reference in a field that takes none (env.md). An object key $env or $text anywhere in a declaration is reserved and fails the evaluation.

Run zap config validate in CI and before committing; it needs no target, no network, and no secrets.

Checklist for a new config

1. zap config validate passes.
2. zap plan --env-file … reads every resource (no UNDETERMINED, no UNVERIFIABLE).
3. Every script has a check precise enough that a converged host plans no change. A check that always fails makes the script run on every apply and reads RESIDUAL after it.
4. Services that depend on files declare the trigger, and the files that must be valid before a reload declare validate.
5. A second zap apply after the wetrun prints (no changes — converged).
6. zap.ts and zap.lock are committed and the env files aren't (getting-started.md).

zap deploy ships a versioned release of your application to a remote host over SSH and swaps it in atomically, with a health gate and automatic rollback. The host is one your config already converges with zap apply: the same tool that built the machine ships the app, and the deploy refuses to ship onto a host that has drifted from its config.

Deploy is the one imperative command. Each run produces a new release, so there is nothing to converge to. It still plans before it acts: a dry run prints every step with the command, script, or URL behind it, and a wetrun executes only the plan a dry run showed.

Configuration

health

Omit the block to deploy with no health gate and no readiness check; there is no flag to disarm a declared one.

Commands

A wetrun binds to a preview made with the same plan-changing flags (below). --env-file <path> loads the operator env first, as for every command. Flags, exit codes, and what a dry run reads: cli.md.

What it needs. On your machine: git, tar with gzip, and ssh, with zap run from inside the application's git checkout. On the target: what a file write needs (targets.md), plus tar, id, and flock.

First deploy

A first deploy onto a fresh host is a chicken-and-egg: the binary lands via deploy, but deploy's preflight requires a converged apply, and a service declared running: true can't be running before there is anything to run. Resolve it in the config: declare the service enabled and leave running unset.

Then the bring-up is two reviewed runs: zap apply, then zap apply --wetrun, provisions the host (firewall included, so deploying first would bail), and zap deploy, then zap deploy --wetrun, ships the first release, whose restart step starts the service. Preview the deploy after the apply has run: the dry run connects as the user the apply sets up, and a pin the apply writes to zap.lock is part of the deploy plan.

The trade is explicit: a config that leaves running unset tells Zap never to assert that the app is up, so zap apply on a host whose daemon crashed and stayed down reports converged. Declaring running: true buys that assertion back at the cost of one deploy --wetrun --skip-preflight on the very first release (previewed with deploy --skip-preflight, since the flag is part of the plan), and --skip-preflight disables the whole drift gate for that run.

When SSH hardening changes the user Zap connects as, add --bootstrap to the first apply: targets.md.

Binding a wetrun to a reviewed plan

A dry run prints the whole plan and ends with its hash:

A wetrun executes only a plan you were shown. It computes its plan again, and that plan's hash must equal the reviewed one:

• --expect-plan <hash> names the reviewed plan explicitly, and binds alone;
• with no flag, the reviewed plan is the deploy preview recorded for this config and host: the last zap deploy dry run, or a wetrun that refused.

Otherwise the wetrun refuses before the drift preflight and any step, prints the plan it would have run under a REFUSED banner that says why (no preview yet, the plan changed since the preview, or the hash doesn't match), records that render as the new preview, and exits 2. Nothing is built or uploaded. The everyday flow is zap deploy, read it, zap deploy --wetrun with the same flags. A wetrun fired cold becomes the preview, and the next one executes if nothing moved. There is no flag that skips the review, and a dry run rejects --expect-plan.

On an interactive terminal (standard input and standard error both terminals), a wetrun with no review and no --expect-plan shows the plan instead, under an UNREVIEWED banner with its plan_hash, and ends with the question:

Typing those eight characters back is the review: the wetrun goes on with exactly the plan shown, to the drift preflight, the withdrawal of any recorded preview, and the steps, as a bound wetrun does. Any other answer is the refusal above, under a DECLINED banner. The prompt follows zap apply's rules: no flag answers it, --json never asks, and a script stays non-interactive by previewing first, passing --expect-plan, or running with standard input that isn't a terminal (cli.md).

One recorded preview covers one execution: a wetrun that passes the review and the preflight withdraws it before its first step, so a deploy that fails needs a new preview (or --expect-plan) before it runs again, and of two wetruns started on one preview only one goes on. An --expect-plan hash is not single-use. A preflight bail or an already-deployed exit leaves the preview in place. A preview doesn't expire.

The preview is a small file under ~/.zap (lock.md), separate from the last-run report that zap apply binds to: a zap plan doesn't disturb a deploy preview, and a deploy dry run doesn't disturb a convergence one. It holds the hash, not the plan. A deploy wetrun's drift preflight does replace the convergence record: it records its pass as the last-run report, which is no preview, so a zap apply previewed before it needs a new preview before its wetrun. With no state directory nothing is recorded, the run says so, and only --expect-plan binds.

Everything the hash covers is printed but two of Zap's own scripts: the one the upload installs the archive with, and the swap the auto-rollback runs. So a plan reviewed under one zap build doesn't bind one whose scripts differ. It covers:

• the version, the tree state, and the previous release on the target;
• the declared target, the host it resolves to, and the connecting user (in the uploaded archive's name);
• who is deploying (user@host of the operator machine, recorded in deploy_info.json);
• the preflight's state: skipped, nothing declared, or which apply-managed resources it checks, as a count and a digest of their declarations and the current pins zap.lock holds for them;
• every step: the build and tarball commands, the upload paths and the script that installs the archive, the remote script with its shared links and prepare commands, the restart command, the health and readiness URLs as they resolve, and the swap the auto-rollback would run;
• the value of each reference the deploy block uses (its health domain), printed in its references: block (a secret's value excepted: the plan records only that it is one).

So a plan reviewed for one host, tree, flag set, or operator does not bind a wetrun for another: a new commit, a deploy or rollback by someone else in between, an edit to any declared resource, a changed pin in zap.lock, --force on a dirty tree, --skip-build, --skip-preflight, or --bootstrap each make a different plan. The hash is printed, and the preview recorded, only when the steps are shown: an already-deployed dry run does neither, so a redeploy binds to the plan a --force dry run shows.

It does not cover:

• the artifact bytes. The version names the commit, and the plan says whether the tree was dirty, but what the build produces is not hashed. The review covers the script that verifies the archive it was sent, not the archive.
• the values a resource's references resolve to. The digest takes each declaration as written, so it is the same in every environment; the environment reaches the hash only through the host, the connecting user, and the health domain. The same holds for the bytes of a local source file.

A masked host, connecting user, or health domain can't be deployed to. No review can bind such a plan: a wetrun is an error that names the reference before anything runs, and a dry run shows the plan under an UNBINDABLE note, with no plan_hash and no recorded preview. The ways out: env.md.

Text from the config, the environment, and the target is printed with control characters written out as <U+XXXX>, so a value can't hide or forge a line of the preview (security.md).

Preflight

Before deploy touches the network, the machine-free gates run (secrets, structure, and, for a deploy config, a present health.domain), and a wetrun rejects any unset reference and a host, connecting user, or health domain behind a masked reference. zap.lock is read here too, when the drift preflight will check. --skip-preflight doesn't skip the gates.

Then a wetrun checks its review and runs the drift preflight: the convergence pass against the config, before building or uploading. If apply-managed state (an nginx site, the env file, the service unit) was edited in the config but never applied, shipping a new artifact against it would be a silent mismatch; the preflight bails with exit 2, and a change held behind a resource it couldn't read counts as drift. A pipeline, which detects absent and runs on every apply, is not drift, and neither is a service that changes only because its trigger fires, planned or held: it reads converged, no pending restart or reload is recorded for it, and every source that fires it is itself not drift (a pipeline, or another such service). A service that also drifted, one owed an action an earlier apply never completed, or one fired by any other change is drift. It also bails, with the same code, when any resource is undetermined: a gate that couldn't check everything doesn't pass by default.

After a drift bail, review the changes with zap apply, converge with zap apply --wetrun, and re-run the deploy: its review still binds unless zap.lock changed.

--skip-preflight skips the drift preflight, and a config that declares no apply-managed resources has nothing to check. Either way the plan says so on its preflight: line.

The deploy also refuses when the live release already has this version, on a dry run too (server already at this version, exit 0). --force ships anyway. A current that names this version but whose release isn't on the host serves nothing, so it isn't refused: the run plans a redeploy and warns that current names a release that is not on the host.

Dirty trees

A tree with uncommitted changes or untracked files git doesn't ignore deploys only under --force, as <hash>-dirty-<id>. Without it, a wetrun is refused before the target is contacted (exit 2), since the release would ship the tree under the commit's version; a dry run shows the plan (tree: uncommitted changes or untracked files) with no hash, records nothing, and says the wetrun is refused, even when the commit is the live release.

The id is 8 lowercase hex of a blake3 over what the tree adds to the commit, so the same tree gets the same id (a dry run and its wetrun agree) and a second dirty tree on one commit is a release of its own:

Zap reads the tree against a copy of the index's entries that holds no timestamps or flags, so every file is compared by its contents: a file the index marks unchanged (assume-unchanged, skip-worktree) counts like any other, and so does one whose timestamps the index's cache would take for unchanged. Each read sets core.fsmonitor=false, core.untrackedCache=false, core.ignoreStat=false, core.fileMode=true (a mode change counts), core.autocrlf=false (line endings are not converted), and core.splitIndex=false, and passes --untracked-files=normal and --ignore-submodules=none, so status.showUntrackedFiles, a submodule's ignore setting, and diff.ignoreSubmodules don't narrow it either. So a checkout on a filesystem without executable bits, or one checked out with core.autocrlf=true, reads dirty, and deploys only under --force.

Two things still decide what counts as a change. The checkout's attributes (.gitattributes, .git/info/attributes) are applied: a clean filter, LFS among them, or an eol or text attribute can make a file that differs from the commit compare equal to it, and no flag turns them off. A submodule's own index is read as it is, so an assume-unchanged edit or stale timestamps inside one can read clean.

A sparse checkout reads dirty and deploys only under --force: the files outside its cone aren't there, so the tree the build sees is not the commit's.

A tree Zap can't read is an error that says what git said, not a clean tree.

The release mechanism

Once the preflight passes, a wetrun runs these steps in order:

1. build: run deploy.build locally (gro build, cargo build --release, whatever produces your artifacts). With --skip-build, or when no build command is declared, the plan has no build step.
2. tarball: package deploy.artifacts into a release archive, a file in a private directory of this run on your machine, removed when the run ends.
3. upload: install the archive into <path> as the connecting user, mode 600, under .zap-deploy-<user>-<version>.tar.gz. It is staged beside that name and checked against its SHA-512 before it is renamed in, so a transfer cut short installs nothing. The archive is held in memory while it uploads.
4. extract + swap: one remote script, generated deterministically and printed whole by the dry run, does the release-directory work. It reads the archive's SHA-512 on its stdin, opens the archive once, requires it to be the connecting user's own file, writable by no one else, with that digest, and extracts through the open file, so another account on the host can't swap the archive between the upload and the extraction. Extracted files belong to the connecting user, under that user's umask, without set-id bits on files. The script removes the archive on every exit of its own. Then:
   • lock: take the app's deploy lock, a kernel flock on <path>/.zap-deploy.lock, held until the script exits. The file is never removed and holds no data; when Zap creates it, other users get no permission on it. It is opened read-only, so the connecting user and its group can hold it, the group even under a umask that gives it read alone (022). A deploy that finds the lock held stops at once, before it touches releases/, with another deploy is running for this app (exit 1); it doesn't wait. The kernel releases the lock when the script's process ends, however it ends; a lock held by a hung deploy is cleared by ending that process (fuser <path>/.zap-deploy.lock names it). The prepare commands run with the lock's descriptor closed, so a process one of them leaves running doesn't keep the lock once the script ends;
   • recover: under the lock, repair what an unfinished deploy (killed, or its connection cut) left in releases/: a staging directory is removed, and a release it had moved aside is put back under its version when that name is empty, or removed when it is filled. So a current that a killed --force left naming nothing resolves on the next deploy (a redeploy of that version needs no --force: Preflight). Each repair is a warning in the run's text report (not in a --json stream), and happens even when that deploy then fails;
   • check: still under the lock, confirm current names the release the plan read as live (by the link's last segment, trailing slashes dropped; nothing at all at current, no link and no file or directory, on a first deploy). A deploy planned before another one swapped stops here, saying current changed since this deploy was planned (exit 1), having made nothing of its own; run zap deploy again. So the release a rollback returns to, and the one the prune keeps, is the one live just before this deploy's swap. A plan that couldn't read current (it warns) stops here too when the host has one;
   • extract into a fresh hidden directory, <path>/releases/.zap-stage;
   • link shared: symlink each deploy.shared entry from <path>/shared/ into the new release (an apply-managed env file, for example); a release that ships a directory at a shared name fails the deploy here;
   • prepare: run each deploy.prepare command in the new release, before the swap, in a shell of its own (sh -ec): an exit or exec in one ends that command, not the script, and a command that fails stops the deploy before the swap. Its working directory is the hidden one, not the release's final path, and its output goes to the script's error stream: a step that fails shows the script's own reason when it stopped itself, or else the stream's last lines, and what a command prints becomes no run warning. A command that reaches the script's own output anyway (through /proc, or a descriptor it was handed) can print a line the script marks, a warning or its reason for stopping, which is then read as the script's: text only, since what the deploy does turns on the exit status and the swap;
   • place: rename the complete release to <path>/releases/<version>, where the version is the commit's hash abbreviated to 12 hex digits (git rev-parse --short=12, longer only where 12 would be ambiguous), with -dirty-<id> for a forced dirty tree, above. When that name already exists (an earlier deploy of the same version, or the live release under --force), it is renamed aside first, to .zap-old-<version>, and removed after the swap, so a release never mixes files from two archives. A run that fails before this point leaves no hidden directory and changes no release beyond what it recovered; under --force of the live version, current names nothing for the instant between the two renames, and a run that fails after this point leaves the new contents live under that name, the old ones not kept. A run killed between the two renames leaves the old release aside for the next deploy's recovery to put back;
   • swap: re-point <path>/current at the new release atomically. From here the release is live, and the run goes on to restart and check it whatever the rest of the script does: what follows is housekeeping, and a failure there is a warning in the run's output, not a failed step. A script that fails after saying it swapped is taken as swapped only when current, read again, names the new release;
   • record: write <path>/deploy_info.json (version, who, when, previous release);
   • prune: keep deploy.releases releases: the one just deployed, the one it replaced, then the newest others. Only a directory named the way Zap names a release (a commit hash of 4 to 64 hex digits, alone or with -dirty-<id>) is ever removed; anything else under releases/ is left alone. As a guard, the prune removes nothing unless current names a release, and on a target with no sort it removes nothing and warns.
5. restart: restart deploy.service through the target's service manager (with a daemon-reload first on systemd).
6. health: poll https://<domain><path> from the operator machine (the one you run zap on) until it answers 2xx, up to attempts times, interval_ms apart. Neither poll follows a redirect: a 3xx is not healthy or ready, so a release that redirects to a login page doesn't pass on that page's 200.
7. readiness: when health.path isn't already /ready, poll /ready too. 2xx proceeds. When the attempts run out, the last HTTP status decides; a connection failure after it doesn't replace it. A 404 means the app doesn't serve /ready: the step is recorded as skipped, warns loudly, and the deploy proceeds on liveness alone. Any other answer fails the deploy and rolls back: a 503 (the convention for a database schema that doesn't match the running code, or an unreachable database), any other status, or no answer at all. Point health.path at /ready to make that one check the gate; then any non-2xx, 404 included, rolls back.

Auto-rollback

If a step after the swap fails (the restart errors, health never goes green, /ready answers 503), Zap re-points current at the previous release, restarts, and re-checks health (the health URL, not /ready), recording the rollback as warnings and step events. The deploy still exits 1: rollback restores service, it doesn't paper over the failure.

The re-point is a compare-and-swap under the app's deploy lock, taken without waiting. It moves current back only while current still names this deploy's release and the previous release is still on the host. Otherwise (another deploy holds the lock or has replaced the release, someone re-pointed current by hand, current names nothing, or the previous release is gone) the rollback is skipped with a warning that says why: nothing is re-pointed or restarted, and the deploy still exits 1.

There is nothing to roll back to on a first deploy, or on a --force redeploy of the live version: current stays at the failed release, and the run warns that a manual rollback is needed.

When the restored release's health check fails too, the rollback step is recorded as failed, and the warning says manual intervention is needed.

The previous release is read from the live current symlink at deploy time, not from a recorded file, so a manual rollback done by hand is seen correctly on the next deploy. A current whose last segment, trailing slashes dropped, is no release's name names no previous release, so the deploy refuses before it builds anything: point current at the live release by hand, or remove it to deploy as onto a fresh host.

Concurrent deploys

A deploy planned before another deploy's swap stops at its check (step 4), so a rollback never undoes a newer deploy, with one exception: a --force redeploy of the same version, planned after a deploy's swap while that deploy is in its health check, writes the same current, which the first deploy's rollback can't tell from its own and can undo. A rollback skipped because another deploy held the lock leaves current at the failed release if that other deploy then fails before its own swap; the warning says to check it.

The lock covers the release-directory work only: the restart and the health checks run after the script releases it, so a deploy can report on a host that another deploy has since moved on. Two simultaneous deploys of one version by one connecting user upload to the same name, so either can replace or remove the other's archive; the other then stops at its digest check or finds no archive (exit 1) rather than ship bytes it didn't build.

What Zap trusts, what it refuses to trust, and where the walls are.

The threat model in one paragraph

The operator is trusted: whoever runs zap apply --wetrun already holds SSH and sudo on the target, and could do anything by hand. Zap's job is to make what that person (or the assistant working for them) does reviewable, bounded, and observable: a config can't act on its own, nothing Zap does to the target goes unshown except the checks a config declares (they run as written on every pass, before any review, and Zap can't make them read-only), a read that fails never passes as "fine", and secrets don't leak into the places people and agents read. Zap is not a sandbox for hostile configs you didn't write; see the config is first-party.

The config can only describe

What this means for writing a config is in configs.md. The walls themselves: zap.ts runs in fgro eval, Gro's runtime, a separate binary Zap runs once per evaluation. Its walls are its own, set up before any of the config's code, or V8 itself, runs:

• a kernel box: Landlock admits reads only under the config's project and the packages linked into its node_modules, and seccomp narrows the system calls. No write anywhere, no network socket, no exec, no read outside those directories (/proc and /dev included; metadata such as whether a path exists stays visible), and no signal to another process. There is no setting that weakens it, and on a host that can't hold it (Linux below Landlock ABI 6, an architecture its filters aren't built for) the evaluation fails rather than run without it;
• no environment: the evaluator starts with TZ=UTC and nothing else of yours, reads no variable for its own settings, and gives the config no process and no environment API. A variable in your shell can't loosen the sandbox or reach the declaration except through zap.env(), which is a reference resolved later by Zap, never a value;
• only static imports: every import() is refused, and a node: built-in doesn't resolve. Resolution is strict ESM: a relative import names its extension, and a bare import resolves through the node_modules of the project and the exports of the package found there (never its main), under the conditions gro, import and default;
• no clock, no randomness, no timers: reading the clock, a random source, or a fact of the machine throws, and there are no timers; the time zone is UTC and the locale en-US (configs.md lists what is refused);
• jitless: V8 runs in its interpreter, so WebAssembly is absent;
• no code from strings: eval and new Function throw;
• bounds: a capped heap and process memory, a 30 second timeout, and a cap on the JSON it may emit.

The config's only output is a JSON declaration that Zap validates against a strict schema. It cannot run commands, write files, or call back into the engine.

The config needs a project. The project is the nearest directory at or above the config whose package.json holds more than "type" and "sideEffects" (a {"type": "module"} marker in a subdirectory is passed over), outside any node_modules, looking only through directories you own that no other user can write. Zap finds it before the evaluator runs and refuses, exit 2, when:

• the config file or its directory is writable by every user (for a config reached through a link, the mode of the file it leads to);
• a package.json on the way up can't be read or isn't valid: not a JSON object, a "name" or "type" that isn't a string, a FIFO, socket or device (refused unopened), a link to nothing, or a path through something that isn't a directory;
• the walk stops below a directory another user owns (the evaluator's own walk would go past it) or every user can write, or reaches /, with no project package.json found. The refusal names where it stopped and why.

The evaluator then finds the project itself and must report the same one, or nothing it wrote is used. Its box admits the project and the packages its node_modules links in from outside it; a package reached through a directory every user can write isn't read. A package that isn't installed in the project doesn't resolve: the search for a bare import stops at the project's package.json, so a node_modules above the project is never searched. npm and yarn workspaces aren't supported: a workspace member with its own package.json is its own project, and the workspace's node_modules above it isn't searched.

"You own" means the user Zap runs as. Run as root, that is root, and under sudo also the user who ran sudo (SUDO_UID), so sudo zap apply on a config in your own project walks your directories as it would without sudo.

The evaluator never runs as root. Run as root, Zap runs it as the user who ran sudo when that user owns the project, and otherwise as the project's owner; a project root owns is refused, exit 2, since no user who could already edit the config is there to run it as. A project that is the evaluating user's home directory, or holds it, is refused too: the box would admit all of it. The user it runs as must be able to search every directory down to the project, and is never dropped into group 0: a drop whose group would be root's is refused. Dropped to the user who ran sudo (who owns the project), its group is SUDO_GID (the group you ran sudo with; unset or not a number is refused); otherwise, dropped to the project's owner, that owner's primary group. A drop keeps no supplementary groups. Its home, and the primary group, come from the passwd database; a static (musl) zap reads only /etc/passwd and nscd, so a user known only through LDAP, sssd, or systemd-homed can have no entry there, and the evaluation is then refused.

The evaluator is pinned. Zap runs the fgro binary --fgro or ZAP_FGRO names, by absolute path, never one found on PATH, and only when its blake3 is the toolchain pin in the config's zap.lock; zap lock is the one command that records the pin rather than checking it (lock.md). The binary is opened once and run through the descriptor that was checked, so a binary replaced at its path afterward isn't what runs. Its blake3 is read through that descriptor, or, once the file has settled, from the pin cache (~/.zap/cache/fgro_pins/, private to the user Zap runs as): an entry there names the blake3 of a file by its device, inode, size, and modification and change times, and a file whose metadata matches an entry isn't hashed again. A write moves the change time, but only to the filesystem's timestamp granularity, so an entry is written only for a file whose times are a couple of seconds old, and a clock set back across that margin, or a network filesystem whose server's clock lags, defeats it. A write to the file itself between the check and the exec, by anyone who can write it, is caught only on a best-effort basis. A link at the binary's own name, a wrapper script, or a set-ID binary is refused.

Reads are the project's. A config reads nothing but the modules it imports, from its project and the packages the project links. What stays the operator's: the files in the project and the linked packages are trusted as they are, a package installed as a directory included. The ownership walk doesn't read ACLs, and the evaluator reads the disk again after Zap's walk: a project that changed in between is caught by its report, not prevented. With ZAP_EVAL_CACHE=skip, a cache hit is served without running the evaluator, so the project walk and the evaluator's report aren't checked on a hit; the fgro binary is still held to its pin (cli.md).

The config is first-party

Zap assumes the config and everything it imports are yours. If you ever evaluate a config you don't trust, the plan it emits is the attack surface: review it as you would a shell script, because its script resources are shell. A config can't pull code from the network or import dynamically, and its imports stay inside its project and the packages it links, so it can't take a project or a package from a directory every user can write. A linked package is otherwise trusted wherever it lives and whoever owns it.

What the gates reject before anything runs

Every command that reads a config, including config validate, runs two machine-free gates on the declaration:

• the secret gate: a secret written literally into the config is rejected when Zap can tell (the same value is both referenced and resolvable in the current environment);
• the structural gate: a malformed or contradictory declaration, such as a NUL byte in a string a shell would see, a duplicate id, or a dangling or cyclic dependency. The full list is in configs.md.

A wetrun adds an env gate: any referenced variable that is unset or empty fails the run before any side effect, so an empty secret never gets written into a .env file.

Zap changes nothing without a wetrun

No command changes the target unless you pass --wetrun, and no flag approves a plan for you. A dry run connects, reads, and renders. Reading runs Zap's own read-only probes and the commands the config declares as checks (a script's check, a verify's assertions, a package's command check, an apt source line's expansion), before any review. Zap runs them as written: a check that writes, writes. Its only other network traffic is fetching a missing content pin into the cache on your machine. This holds with no terminal, in CI, and in an agent loop. zap lock and zap update write zap.lock on your machine, which is their job.

A wetrun executes only the plan you reviewed

A wetrun's fresh plan must match a reviewed one hash for hash, or it refuses before any side effect; on an interactive terminal it asks you to type the start of the hash instead, a question nothing typed earlier can answer. The rule, and what plan_hash binds (the host, the connecting user, a local HOME, every plain reference's value), is in concepts.md; zap deploy binds its own plan the same way (deploy.md). So an agent given --expect-plan with the hash you approved, or a pipeline given the hash approved in a pull request, can execute only that plan. A plan whose host, connecting user, or deploy health domain resolves through a masked reference gets no hash, and its wetrun is an error (env.md).

The host a hash binds is the name the config resolves it to, not where ssh takes that name: an ssh config whose HostName, User, or Port for it changes between the review and the wetrun sends the reviewed plan to the machine it now names, if that machine's key is a known one. What ssh -G prints is configuration, not the machine, so the hash doesn't bind it; the machine itself is held by host-key checking. Binding the machine to a plan would take its host key's fingerprint, which the hash doesn't hold.

What the hash covers that a preview doesn't print

A preview prints the target and, under each change, what it declares and every step, with a file's content as a descriptor: its kind, length, and the start of its SHA-512 (for a template, of the template text as written). plan_hash also covers:

• a file's content bytes, and any literal credential;
• a resource's depends_on, and trigger sources;
• package names for managers the target doesn't use;
• the text of the scripts Zap's own operations run (the put, link, directory, extract, snapshot, pg_hba.conf, and swap-path scripts, and an installer's fetch) and the command each runs in, with its arguments, privilege, and limits, so a zap build whose scripts, or the way it calls them, differ from the one that previewed computes a different hash.

The hash is not a fingerprint of the zap binary: what it does natively on a local target, and the few commands it composes directly around a path (the rm -f that clears a pending marker or removes what a failed validated write created), are its own.

What an approved hash doesn't fix

What Zap can't know when it plans:

• a secret's value (the plan says only that the reference is one);
• the state of the target between the read and the change;
• what the target's shell expands inside a command ($HOME, a variable in an apt source line), which on a local target is Zap's own environment, whose HOME an --env-file doesn't set;
• the bytes of a source file already on the target;
• what an installer URL serves that day;
• the path PostgreSQL reports for its pg_hba.conf;
• in a deploy, the artifact bytes and the environment your build and prepare commands run in.

Some commands also run before any review, as the connecting user, on every pass that reads the machine (plan, detect, apply dry or wet, the deploy preflight): a script's check, a verify's command assertions, a package's check when it is a command, and an apt source line, which the target's shell expands to compare with the list, so a $(…) in it runs at zap plan. This is one reason the config is first-party.

Escaped output

A review is only as good as the text it reads. Everything Zap prints as text writes what it takes from the config, the environment, the command line, zap.lock, a file under ~/.zap, or the target with control, bidirectional, and default-ignorable characters (every control character but tab, the line and paragraph separators, zero-width characters and the like) spelled out as <U+XXXX>, and a tab as spaces, so such text can't move the cursor, overwrite output, reorder what is shown, or sit in a line unseen. Text that is a block (a command, a script, what a failed command printed) keeps its lines, each indented under its first. The --json event stream writes the same characters as JSON \u escapes. The escape doesn't make look-alikes distinguishable: homoglyphs, wide or blank spaces, and combining marks print as they are, a long line still wraps, and text that spells <U+000D> or {env:NAME} prints the same as what Zap writes for one.

Secrets

• A config never reads the environment. Values are references (zap.env('NAME')), resolved by Zap when it acts. A reference holds a name, never a value. No value a reference resolves to, nothing a command prints, and no file's bytes can turn into one.
• Which references are secrets, and the forms masking looks for: env.md. A secret's value is masked out of every output: the text report, the JSON events, warnings, held reasons, drift observations, deploy step output, and errors. Masking is by value: a secret a tool prints in another form (the address ssh resolved a secret host name to) isn't found, and a secret under an ordinary name with an ordinary-looking value isn't known to be one until mask() lists it.
• Zap hands every command to its shell on stdin, detection and apply alike. No command text, env value, or working directory is on the argv of ssh, the login shell, or sh, on either machine, so none shows in ps. File content travels on stdin too. A program a command starts still shows its own arguments while it runs, and that includes the ones Zap starts (curl <url>, psql -c <sql>). Give a program a secret through an env value or a file it reads, not as an argument.
• A value is substituted into a command as text, into whatever quoting surrounds the reference. Zap refuses a value holding a single quote, a NUL, or a reference delimiter (U+FDD0 or U+FDD1) in a command, and a double quote in a database identifier, before anything runs: a wetrun checks every planned command first and exits 2 with nothing changed; zap plan and a dry run warn. That makes a reference safe inside single quotes, where a shell reads every other byte literally, and Zap and the shipped recipes put every value there, except the options documented as shell words (psql_args, command_args, a stop or reload command). A reference a config author writes outside single quotes, bare or inside double quotes, is read by the shell like the text around it, and keeping it safe there is the author's job. An env value is quoted after it resolves and carries anything but a NUL and the reference delimiters U+FDD0 and U+FDD1.
• The last-run report and zap.lock hash a secret reference as a fixed token, and the report masks every registered secret out of any other value, so neither can be used to test a guess at a secret. A secret the rule doesn't recognize is hashed by value until mask() lists it (lock.md).
• A fetch error names the URL as the config declares it, its references unresolved, and the content cache names a file from the declared URL, so a token in a URL reaches neither a message nor a path.
• remote and build sources can carry a bearer auth token; it attaches as a request header to the source's own origin (scheme, host, and port) only: a signature_url on another origin is fetched without it, and a redirect to another origin drops it. Its resolved value is never hashed and never reaches the lock.
• There is no --show-secrets.

Content Zap fetches

Every URL in a config is https://: a plain http://, file://, or any other scheme doesn't validate, and neither does a URL carrying user:password@. The one allowance is http:// to a loopback host for the fetches Zap makes itself, for a local mirror. Zap follows a redirect only to another https:// URL (a fetch that has stayed on loopback may be redirected on loopback), so a remote server can't send a fetch to a plain-http port of the machine Zap runs on, and a bearer auth goes only to the origin the config names.

Fetched bytes are pinned by blake3, verified against the pin before placement, and cached by content address. A vendored pin is your own statement of which bytes to trust. A tracked pin is trust on first fetch: zap lock, zap update, or the first zap apply --wetrun records the hash of what the URL served then, and every later fetch must match it. What authenticates that first fetch is TLS, plus a minisign signature when a build source declares verify, checked before the bytes are cached or pinned. A signature doesn't fix the version: an older release the same key signed is caught only by the pin (resources.md). The recorded pin is in zap.lock and in the plan hash, so it is reviewed like any other change. minisign's exit status is that verdict, so the binary is found once (the absolute path ZAP_MINISIGN names, else PATH) and run by that path, and one inside a node_modules directory, or where it or any directory on the way to it (every one up to /, links followed) is in reach of a group, another account, or anyone but root and you, is refused; a refusal or a failed check names its path. With those directories trusted, the gap between the check and the run is only root's and yours.

zap.lock is reviewed input, like the config: its config_hash detects staleness, not forgery, so review the lock's diff before committing it (lock.md).

One thing reaches the target with no pin. An installer is a script fetched whole over https and then run: whatever its URL serves today, gated only by a check path. A fetch that fails fails the step, and so does one that serves an empty script; nothing runs. Prefer a build or a pinned remote file when the upstream offers one. An apt_repo's signing key is pinned like remote content: Zap installs only bytes whose blake3 is the pin, and detection compares the installed key with it (resources.md).

Writes on the host

Zap installs a file by staging it under a new name in the file's own directory, setting owner and mode on the open file, and renaming it into place; it never follows a link at the file's name or at the staged name, and a file's or directory's mode and owner are never set by name. The bytes are checked against their SHA-512 before the rename, so a transfer cut short installs nothing. A directory's owner and mode are set on the directory itself; a link at its name is refused. A file keeps the owner, group, and mode it leaves unset from the regular file it replaces, read from the name without following a link, never with a set-id or sticky bit; a new one takes its directory's owner and group. A file with a second name (a hard link) keeps nothing, and neither does anything below a directory with its sticky bit set or that every account may write (/tmp, /var/tmp, /dev/shm), however deep — Zap walks up from the file's directory by .. to the root, and checks every directory on the path as written, a link read as what it leads to: there a file takes what Zap's own write gives, as root over SSH or as you locally. A mode is never kept from a file with an extended POSIX access list (ACL), whose mode bits show the list's mask: the write is refused until the config declares mode. Zap sees a list through getfacl, else through GNU ls's +; a target with neither (stock Alpine) can't show one, and keeps the mode. Elsewhere, whoever can write the directory can choose what is kept, as they could replace the file; the files Zap's steps install never keep a planted owner. So a file with a mode but no owner, written into a directory another account can write, can end up readable by that account: it inherits that account's directory, or the account plants a file there of its own for Zap to keep. Declare mode, owner, and group on any file whose content the directory's owner or group must not read: a planted file's mode is kept even when the owner and group are declared, so without a mode the content can land readable by everyone. A user's authorized_keys is written as that user, and a sudoers file is installed only after visudo -c accepts it.

A file with a validate command is read before its write, so a failed check can put it back. One script holds the file open and reads its bytes, mode, and owner through that descriptor: as root over SSH, and locally as you, escalating when refused. The change fails with nothing written when the name holds a link, anything but a regular file (a fifo is refused without waiting on it), or a file over 16 MiB. A rollback restores the bytes with the owner and group they had, and their mode without any set-id or sticky bit the declared mode doesn't carry, so root never makes a file set-id that the config didn't.

One window stays open: between the read's checks and its open, a link swapped in is opened (not read) and the read refused, unless it leads to a fifo, which holds the open until the read's five-minute timeout fails the change. A directory's owner and mode change has the same window and timeout.

Missing directories are made one at a time, each inside the one before it held open, and given, through its descriptor, the owner and group of the directory it was made in, so it belongs to someone who could have made it; a link swapped in for one is refused, with nothing made through it. The owner is given only to the empty directory Zap just made: a directory renamed over it before it was opened, by the owner of the directory it was made in, is refused and given nothing. Anywhere below a directory with its sticky bit set or that every account may write (/tmp), however deep, on the path as written or where its links lead, what Zap makes stays its own, as root over SSH or as you locally: an account that made /tmp/cache, as a directory or as a link to one of its own, can't have the directories Zap makes there given to it.

Reads of a file's bytes, as root over SSH, read only a regular file of its own: a name that is a symbolic link, a directory, a device, or a fifo is refused before it is opened, and what was opened is read only when it is a regular file and still the file at the name, so no byte comes through a symbolic link. The checks can't close the instant before the open: an account that can write where a managed file lives and swaps the name for a symbolic link in that instant has Zap open what the link names, though not read it, and opening some devices acts on the machine (a watchdog's), while a fifo holds the read until its timeout. A regular file with more than one hard link is not read either, whoever owns it: a hard link is the same file under another name, which an account can make in a directory it writes, so a root read of the name could read a file that account linked there. The link count is read from what was opened, and such a file holds its resource, with the fix: replace it with a copy of its own (a single link). Keep managed files in directories only root can write all the same. A file's source is read the same way, and a user's own authorized_keys is read as that user.

Zap does follow a link in a directory component of the path, so a managed path under a directory someone else can write can be redirected to another directory: keep root-managed files in directories only root can write. One such redirection also slips past the shared-directory checks above: a link on the path that leads through a second link sitting in a directory every account may write, off both the path as written and the directories it resolves to (/srv/app a link to /var/shared/app, itself a link the account that can write /var/shared points at a directory of its own). Neither check passes through /var/shared, so what is kept there, or given to directories made there, is that account's choice. Keep the links on a managed path out of directories others can write. The staged file is made by mktemp, mode 600 whatever the umask or a default access list on the directory would give, and held open; before a byte is written it must be a regular file of the writer's, empty, with one name, and still the file at the staged name. A local user who can write the directory could make the write fail, or stall it by swapping the staged name for a fifo; they could not send the content, mode, or owner anywhere, nor have root create a file where a link of theirs points. A run killed outright, or one refused at its stage check, can leave a .zap.* file beside its target. A target needs /proc.

The same holds for the files Zap's steps install: an apt sources list, the nftables ruleset, and /etc/fstab are each installed whole by rename, never edited in place, and so is an apt_repo's signing key. pg_hba.conf is too, but as the postgres account, not root: PostgreSQL names the file and postgres owns its directory, so a rewrite as root would write wherever that account pointed it. The rewrite keeps the file's group and mode, and refuses a file that doesn't belong to postgres or a directory it can't write; detection reads the file as postgres as well.

A remote file's or build source's archive is extracted only into a directory at its own name: a link there is refused. tar runs in a new directory inside a private staging directory (mode 0700, the extracting user's) beside the destination. The staging directory is held open from the moment it is checked: a fresh, empty directory of the extracting user's, mode 0700, at its name, and not a link. Everything inside it is then reached through the descriptor, so an account that can write the destination's parent may rename the staging directory, or put a link at its name, but can't steer where tar writes or what is removed. What tar extracts belongs to the extracting user, with no set-id bit on a file and nothing group- or world-writable, whatever the archive records. Before the rename, still inside the staging directory, the new tree is given the owner, group, and mode of the destination it replaces, read without following a link and set on the directory held open, never with a set-id or sticky bit; then it is renamed into place. Below a directory with its sticky bit set or that every account may write, checked as for a file (the parent's path as written and where it resolves), nothing is kept: the new tree stays the extracting user's, at the mode mkdir gives it. A destination that has an extended or default access list is refused, a declared mode or not; the list must be removed (setfacl -b). Such an account can still move the destination itself, or the tree once it is in place: a parent another account can write is trusted to that extent. The archive's contents are trusted as pinned: its author chooses the names inside it. Neither tar writes through a symbolic link the archive carries. BusyBox tar will make a hard link to a file outside the archive that a member names, so a new tree holding a file linked from outside it is refused, and removed before it is renamed into place; hard links among the archive's own files extract.

A remote or build archive is uploaded as the connecting user into a private staging directory of the run, then extracted as root. The extraction opens it once and goes on only when the file it holds is a regular file, not a link, owned by the account that ran sudo, with one link and writable by no one else. It then copies what it holds into its own staging directory, which only root reaches, and extracts that copy only when its SHA-512 is the digest of the pinned bytes Zap passed, so a process running as the connecting user can't swap or rewrite the archive between the upload and the extraction.

hardened_openrc_service never sources an env_file: its init script runs as root, so root never parses it: start_pre has the service user check every line (su, under a 10-second timeout), assigning nothing, and the daemon's own process, already dropped to that user, exports the values before it runs the command (recipes.md). A service user that can write its env file changes its own environment, as under systemd, and can make a start wait out the timeout or fail; the refusal start_pre prints is that user's process's words.

A release archive sits in no shared directory on either machine. On yours it is a file in a private directory of the run; on the target it is installed into the app path as the connecting user, and the release script extracts only the file it has open, after checking that it belongs to that user, is writable by no one else, and has the digest Zap sent. So another account on the host can't swap or alter it between the upload and the extraction. Nothing checks what your build put in it. A deploy trusts whoever can write the app path as much as it trusts the connecting user: they can re-point current. Deploying as root into a path another account can write lets that account redirect what root creates there, so deploy as the path's owner. A run killed outright, or a connection dropped between the upload and the script, can leave the archive at mode 600 in the app path or in your temporary directory.

Authority on the host

Zap's authority is SSH plus the host's sudo. There is no agent, server, API, or role system to compromise. Privileged commands carry an explicit sudo; on a local target file operations escalate only when denied, and over SSH they run under sudo (targets.md). Host keys are trusted on first use and refused when changed, which holds only while ssh records them: Zap reads your effective ssh config once per target (ssh -G) and refuses to connect when every UserKnownHostsFile is /dev/null. Every session has agent, X11, and port forwarding, a tunnel device, a terminal, and LocalCommand turned off, whatever your config says. The host's own sudo I/O log (Defaults log_input, replayed with sudoreplay) is the audit trail of what ran as root: the plain sudo log records one constant wrapper per detection batch, and the I/O log captures the script, resolved reference values included. It never sees the unprivileged login lane, where operator commands run. A file write appears in the sudo log as one sh -c command carrying Zap's constant install script, with the path as its argument; the mode and owner are arguments too, and the content and its digest arrive on stdin, so a host that logs sudo's input records them.

Fail closed

• A resource Zap can't read is held, not guessed. The run exits 1, and deploy's preflight refuses to ship (exit 2). A "converged" that wasn't established is never reported.
• A pin that isn't current is withheld, so a stale lock can't make a changed resource read converged.
• A reference the comparison needs but can't resolve makes the whole pass unverifiable, exit 1: an empty string can both hide drift and invent it.
• A file write with validate is rolled back when the check fails, so a service is never reloaded onto a rejected config.
• A failed reload is remembered on the target and re-fired on the next plan.

Security controls are read live, every time

firewall, user, and database guard the host's access surface and are exactly what gets changed by hand: a ufw default allow incoming at the console, or a key appended to authorized_keys. Zap keeps no detection cache, so such a change shows on the next plan rather than hiding behind a stored verdict. The same holds for security-relevant files: an sshd drop-in, a fail2ban jail, an nginx site carrying a CSP. The exception is the lists Zap treats as additive (below): a declared entry that went missing drifts, but an extra one, such as an injected pg_hba trust line, isn't read.

Limits and defaults to know

• Firewall allow rules, a database's pg_hba rules, and a user's groups are additive. Zap asserts that each declared entry is present (and, for a firewall, that the default policies match); an entry added out of band is neither detected nor removed.
• A database resource writes no pg_hba rule unless it declares auth.hosts, and never a trust one: the role is reached over the Unix socket by the OS account of the same name. A trust rule already in the file (one an older config added) stays until it is removed by hand; on Alpine, alpine_postgres_setup rewrites initdb's, and any other trust line, to peer / scram-sha-256.
• A link whose path is a regular file reads as absent and is replaced.
• A file with no managed mode, owner, or group whose path is a symlink to matching content reads converged; the link is left as it is.
• Zap follows a symlink in a directory component of a managed path (see Writes on the host).
• A swap's size is not compared after creation.

Reporting a vulnerability

See the repository's security policy for how to report an issue privately.

Zap converges the inside of Linux machines you own and ships your services to them. It is a TypeScript declaration and a Rust engine over SSH, with dry run by default, no agent, and no server. This page puts it next to the tools you might otherwise reach for. It is written for someone with a few servers and a laptop, not a fleet, and it covers when not to use Zap as much as when to.

Facts about other tools name versions where they matter. If something here is out of date, please file an issue.

What Zap is: introduction.md, including the things it does differently. The verdict comes first; the side-by-side tables are at the end.

Use Zap when

• You run a handful of Debian/Ubuntu or Alpine hosts you reach by SSH, and want their packages, users, SSH hardening, firewall, nginx, services, and an on-box PostgreSQL declared in one file.
• You want nothing on the target beyond sshd, sudo, and a stock shell and core tools: no agent, no Python, no server, no state bucket.
• An AI agent or a non-ops teammate will drive the tool, and you want the default command to be harmless, a plan they can show you with a hash, exit codes that separate "converged" from "drifted" from "couldn't tell", and typed events rather than log scraping.
• You'd rather be told "I couldn't read this" than have a tool guess.
• You deploy your own service as release directories with a health gate and rollback, and want the deploy to refuse when the host has drifted.
• You prefer TypeScript with completion over YAML with a template language.

Don't use Zap when

• You need many hosts in parallel or fleet orchestration. One config, one host, resources in order. Ansible, pyinfra, Salt.
• You need cloud resources. VPCs, DNS, load balancers, managed databases. OpenTofu, Terraform, Pulumi; they pair with Zap.
• You need removing a declaration to remove the thing. Zap only reports orphans. NixOS, or Terraform for cloud resources.
• You need macOS, Windows, RHEL, Arch, or network devices. Ansible, chezmoi, mise.
• You want whole-system rollback or reproducibility. NixOS, image-based systems.
• You're container-native. Kamal, Compose, Dokku, Coolify; Zap can still converge the host underneath.
• You need branching on mid-run results. Ansible, or a script.
• Your machine can't run fgro. It needs x86_64 Linux with Landlock ABI 6 (kernel 6.12 or later).
• You need a module ecosystem and community support. Zap is pre-alpha with one maintainer. Ansible.

Head to head

Ordered by how often a reader is choosing between the two.

Versus Ansible

The closest in operational shape: agentless, SSH, no server. The furthest in control model. An Ansible playbook is an ordered list of tasks; most modules converge within one task (state: present), but the playbook is a procedure, and decisions are made at run time against gathered facts, including facts an earlier task in the same run changed. Zap has no task order you author: you declare resources and dependencies, and the engine decides create, update, or skip from detection.

Ansible's --check mode is opt-in and its fidelity depends on each module: command and shell are simulated only when given creates or removes. Handlers notified by a task are lost if a later task fails, unless you set --force-handlers; Zap remembers an owed reload on the host. Ansible needs Python on the managed node for nearly every module; Zap needs a shell. Ansible's validate: on copy and template matches Zap's validate on a file.

Reach for Ansible for its enormous module ecosystem, for fleets and inventories, for Windows and network devices, or for run-time procedural flexibility. Zap is narrower and younger by orders of magnitude.

Versus pyinfra

The closest living tool to Zap's shape: agentless, SSH, generates shell so the target needs no Python, written in a real language, two-phase (facts first, then operations). The differences are where the two draw their lines. pyinfra lets deploy code read facts while deciding what to do, so the declaration can depend on the host; Zap seals the declaration before contact and doesn't read the host while deciding. pyinfra shows its changes and prompts before acting, and warns the list may be incomplete; Zap's dry run is the default and executes nothing. pyinfra has no lock file pinning fetched content, no held verdict, and no re-read after acting. pyinfra runs many hosts in parallel; Zap runs one.

Reach for pyinfra for Python, for parallel multi-host runs, or when you want the host's facts to shape the deploy.

Versus Docker Compose, Kamal, and self-hosted PaaS

For a solo developer with a VPS, this is the realistic alternative. Compose, and platforms like Dokku, Coolify, and CapRover, assume a prepared Docker host and own the application layer: images, containers, routing, often TLS. They don't converge the host: SSH hardening, the firewall, users, an on-box PostgreSQL, unattended upgrades. CapRover and a self-hosted Coolify run a control plane on your server that you have to keep; Coolify's hosted cloud keeps it for you, over servers that are still yours to converge. Dokku is git push to one box.

Kamal 2 ships Docker images and does rolling restarts behind kamal-proxy, which health-checks the new container before switching traffic, a gate that is stronger than Zap's post-swap health check plus rollback. Kamal has no dry run. kamal setup installs Docker but doesn't otherwise manage the host.

Zap deploys release directories, not containers, and its isolation comes from converging the host (a hardened systemd unit, a dedicated user) rather than from an image. The two are complementary: Zap can converge the box these tools run on.

Reach for Kamal or Compose when you're container-native or want multi-host deploys; for Coolify or Dokku when a UI or git push is the experience you want and you're happy to run their control plane.

Versus OpenTofu, Terraform, and Pulumi

The closest in discipline: declarative, converge, review a plan before acting. Terraform's plan is computed by refreshing a state file that is the authoritative record of what Terraform owns, and data sources read live infrastructure during planning, so the desired state is a function of config, state, and the world. Zap's declaration is a function of the config alone; detection decides only which declared changes run. There is no state file: the machine is read every run, and zap.lock pins content, not resources.

Credit where due: Terraform's saved plan (plan -out, then apply <planfile>) is the most operationally binding plan artifact in the field, and it refuses a plan whose state has moved since. Zap's wetrun binding does the same job for a machine, by hash. Terraform also destroys a resource you stop declaring; Zap only reports it as orphaned.

Pulumi takes "a real language" the other way across the boundary: the program runs against the live engine, resources register over RPC, and apply() callbacks run mid-deploy. Zap's TypeScript emits data and stops.

Scope differs more than model: both are cloud-resource tools with provider ecosystems. Zap converges the inside of a machine and has no providers. Pair them: OpenTofu for the droplet and DNS, Zap for what's on the droplet.

Reach for OpenTofu, Terraform, or Pulumi for cloud infrastructure, for a removed-means-destroyed model, or for mature team workflows around state.

Versus NixOS

The nearest philosophical kin: both make the declaration deterministic. Nix makes purity a precondition: builds are sandboxed, the whole system is a function of a pinned expression, and you adopt the store and the language wholesale to get reproducibility and atomic rollback. The system closure is a more complete inert artifact than Zap's declaration, and nixos-rebuild build, dry-activate, and nix store diff-closures let you inspect it before switching. deploy-rs adds a magic rollback over SSH; nixos-anywhere installs a machine from nothing.

The difference is prevention versus measurement. Nix prevents drift in what it owns and is silent about the rest (/var, database contents, mutable users); activation reasserts without reporting. Zap reads and reports drift on every run, including the security controls, and repairs it. You keep your distro and your package manager; you give up atomic generations and whole-system rollback. Guix System is the same model in Scheme; image-based systems (bootc, Fedora CoreOS, systemd-sysext) are the other prevention answer: don't converge, replace.

Reach for NixOS for whole-system reproducibility and atomic rollback, if you're willing to adopt the model end to end.

Versus Puppet, Chef, and Salt

The same convergence model, a different operational one: agents that pull and converge continuously, usually against a server, with mature resource models and fleet tooling. All three run masterless too.

Puppet deserves specific credit: it compiles a catalog, an inert JSON resource graph, before applying, and the catalog can be compiled without applying and diffed. The contrast with Zap is that the catalog's inputs include facts gathered from the node, which is exactly the host-reactivity Zap declines to model (below). Chef's why-run is best-effort by its own documentation. Salt's test=True and state.show_highstate give an inspectable compiled state; salt-ssh is agentless but needs Python on the target unless it ships Salt's bundled runtime (--relenv).

Puppet and Chef have both moved their official builds behind commercial terms, with community forks (OpenVox, Cinc) carrying the free builds. Salt is actively released under Broadcom, with many modules moving to community extensions.

Reach for one of these for a large fleet that wants continuous, pull-based convergence and a deep existing ecosystem.

Versus Capistrano, Deployer, and Mina

On the deploy axis the comparison shifts: this is release push, not convergence. Capistrano and its kin ship a versioned release into releases/ and swap an atomic current symlink, the same model Zap's deploy uses, with keep_releases (default 5) and a manual deploy:rollback. None has a built-in health gate or automatic rollback; Capistrano usually clones git on the server, where Zap builds locally and uploads a tarball. Mina generates one bash script per deploy and prints it with --simulate, as Zap's dry run prints its remote script. Mina is dormant: no release since 1.2.5.

Zap's additions are the drift preflight (the deploy refuses to ship onto a host whose convergence config has drifted), the automatic rollback on a failed health gate, and that deploy rides the same engine as convergence.

Reach for Capistrano or Deployer for a mature multi-host release tool with a plugin ecosystem in the Ruby or PHP world.

Versus plain shell and cloud-init

The honest baseline: a setup.sh, a Makefile, a cloud-init file. These are imperative bootstrap: top to bottom, no idempotency guarantee, no notion of current state, no dry run, and cloud-init runs most modules once per instance rather than as a loop. Zap's value over this baseline is exactly what convergence buys: skip what's done, re-run safely, preview by default, report after.

Reach for plain shell when the task is one-shot, tiny, or so bespoke that a resource model is more ceremony than it saves.

Personal machines: mise, chezmoi, home-manager, Brewfile

Zap also sets up a developer's own machine: build tools, a terminal, dotfiles, packages. The dedicated tools are better at their one job: mise pins tool versions with a lockfile, chezmoi diffs and templates dotfiles across machines and supports macOS and Windows, home-manager brings the Nix model to a user's environment, brew bundle declares macOS packages. Zap's case is one model for the laptop and the servers, with the same file, pkg, build, and script resources, and the same dry run. It doesn't run on macOS.

How each tool reacts to the host

Zap's declaration is sealed before the machine is touched: the config runs with no network and no environment, and detection then decides only which declared changes run. That is why there's no state file, why the plan has a stable hash a wetrun can be bound to, and why secrets stay inert until use. It splits "reacting to what's on the host" into three cases:

1. Detection: gating a declared action on observed state ("install only if missing", "restart only if the config changed"). This is the convergence loop itself, plus a script's check, verify assertions, and triggers. Under convergence you don't write "if X, do Y" when Y is idempotent; you declare Y and detection skips it.
2. Derivation: desired state computed from host facts ("swap is twice the detected RAM", "apt on Debian, apk on Alpine"). Terraform does this with data sources, Puppet and pyinfra with facts, cdist with explorers. Zap doesn't read the target during eval; a script that computes on the target covers these cases.
3. Mid-run reactivity: decisions from results a prior step produced. That is orchestration (Ansible's when: over run-updated facts, a shell script), and Zap doesn't do it. Put that logic inside one script, or compose Zap with a tool built for it.

A script's run is arbitrary shell, so the cost is legibility, never capability. Two caveats: on a local target the config runs on the machine it describes, so it could read host state at eval time (outside the model, not prevented); and determinism is by construction for the common sources (the clock and randomness throw, the time zone and locale are fixed) rather than proven, where Nix's sandboxed evaluation is the stronger claim.

Also in the space

cdist: agentless SSH push, type-based, generates shell from explorers run on the target; the closest historical kin, now low-activity. mgmt: a declarative, event-driven engine with a real-time graph that converges continuously, Zap's polar opposite on timing. Fabric, Rex, Puppet Bolt / OpenBolt: imperative remote task runners. Kubernetes: the purest convergence model there is, continuous reconcilers over etcd, and for a handful of VPSes the cost is the cluster itself. Dagger: a CI/CD pipeline engine, not a host tool; Zap isn't a CI engine.

At a glance

One table per axis. Zap's cells are exact; the others are our best understanding and are kept general on purpose.

Model: how each tool decides what to do

Operations: what you run and where

Safety: what protects you from a bad run

Scope and maturity

The config

Why TypeScript for the config? Because the config needs loops, constants, functions, and types, and inventing a DSL for those is how YAML grows a template language. TypeScript has them, editors understand it, and the shipped recipes are ordinary functions. The config only describes: it runs in a sandbox and emits JSON. Zap evaluates it once, before it reads the machine; what executes is the plan built from that JSON, and none of your TypeScript runs on the target.

What runs the config? Can I use Node, Deno, or Bun? fgro eval, Gro's runtime. Zap is a compiled Rust binary and can't run TypeScript itself, so fgro evaluates the config in a kernel sandbox that reads only the config's project and the packages it links (the sandbox). Each project pins one fgro build by hash in zap.lock. Node, Deno, and Bun have no such sandbox, so Zap doesn't support them. Nothing runs on the target but shell.

Where are secrets stored? Nowhere Zap owns. They live in your environment or an env file you keep out of version control, referenced with zap.env('NAME'), and resolved when Zap acts. Resolved values are masked in every output, and the lock file and last-run report hold a fixed token for each recognized secret (env.md; list others with zap.mask()).

What is zap.lock and should I commit it? It pins the fgro build that evaluates the config, and fetched content (a remote file, a build source) to the hash of the bytes you approved. Commit it with zap.ts. It changes only when you run zap update, zap lock, or an apply --wetrun that has a tracked source to pin. lock.md.

Running it

Why is the dry run the default? So the safe thing is the zero-effort thing, and so a script, a CI job, or an assistant can't act by accident. Tools that default to acting rely on an interactive prompt, which is exactly what gets auto-approved. Here --wetrun is the act, and a wetrun with nothing reviewed asks for the first characters of the plan's hash, which nothing can type before the plan is on the screen.

What does --wetrun refusing mean? A wetrun executes only the plan you reviewed. If its fresh plan doesn't match the most recent preview on that host, or the hash given to --expect-plan, it shows the plan, changes nothing, and exits 2; running it again executes if nothing moved. On an interactive terminal without --expect-plan, it asks instead: type the start of the plan's hash to run it. concepts.md.

Why did zap plan exit 0 when there are changes, but zap apply exit 2? plan reports; it doesn't judge. apply judges: 0 converged, 2 changes pending, 1 something couldn't be established. Use apply in a script that needs the verdict. cli.md.

What is undetermined? Zap couldn't read the resource and refuses to guess. It is held out of the plan, reported with its reason, and the run exits 1. The usual causes: a remote path using ~ with no home declared, a tracked remote file with no lock entry, a probe that failed or timed out, sudo that wouldn't authenticate. Fix the cause and plan again; nothing carries over. concepts.md.

Why does a script run on every apply? Its check fails on a converged host. The check is the whole idempotency contract: make it exit 0 exactly when the work is done. After a wetrun Zap runs the check again and reports RESIDUAL if it still fails.

Why does apply write to /var/lib/zap/pending/ on my host? Each marker there is a restart or reload a service still owes, written before the change that triggers it and cleared after. It is how a reload a failed run owed survives to the next plan (concepts.md). The rest of what Zap leaves on a target, beside what you declared, is listed in install.md.

Scope

Does Zap need anything installed on the target? sshd, a POSIX shell with coreutils or BusyBox, and sudo. No agent, no Python, no runtime. targets.md has the per-distro list.

I removed a resource from the config. Why is it still on the machine? Zap never removes what you stop declaring; it reports it as orphaned in zap status. To remove something, declare the removal (a script whose check confirms it is gone, or sudo: false on a user). This is the same posture as Ansible and Puppet, and the opposite of Terraform and NixOS.

Can one config manage several hosts? One target per config. For a few hosts, one config per host (sharing modules), one env file per host, a shell loop. For a fleet with parallel execution, Zap is the wrong tool; see comparison.md.

Does Zap work on macOS, Arch, Fedora, Windows? No. Debian/Ubuntu and Alpine. pacman, brew, and launchd parse in the schema but have no backend, so their resources read undetermined. Running Zap from macOS against a Linux host is unsupported: fgro's sandbox needs Linux, so your side does too.

Is Zap stable? No: pre-alpha, one maintainer, and the schema and CLI change without compatibility layers. stability.md names the surfaces whose breaks a release calls out. Read security.md before pointing Zap at a machine you care about.

Agents and alternatives

Can an AI agent run Zap? Yes, and it is designed for that: the default command is read-only, the plan is a hash-named fact the agent can show you, the wetrun executes only that plan, and --json streams typed events. Give the agent zap plan and zap apply freely and keep --wetrun for the human, or let it wetrun with --expect-plan set to the hash you approved.

How is this different from a shell script with if guards? That script is reaching toward what Zap declares: detection (skip what's done), idempotent re-runs, a preview before acting, and a report after. Zap adds the parts a script never grows: a refusal to guess when a read fails, a re-read after acting, secrets masked everywhere, and a review bound to the act. script resources let you keep the shell where it is the right tool.

How is this different from Ansible / Terraform / NixOS / Kamal? comparison.md, with tables.

Zap is pre-1.0. Anything can change between minor versions, and nothing is kept for compatibility: no deprecation period, no aliases for renamed things. What this page promises is narrower: which surfaces count as Zap's interface, so a change to one is named in the release notes, and what an upgrade throws away on purpose.

The interface

A change to any of these is a breaking change, and the release notes name it.

zap.lock is the one file Zap writes that you commit, so it carries the one migration promise: if its format version ever moves, Zap will read the old version and rewrite it in the new one, so you won't re-mint it by hand.

Discarded on upgrade, by design

These are derived by the binary that made them. A new version may compute them differently, and when it does the old ones stop matching. None of them breaks silently: Zap plans again, and the review gate asks for a new review.

• Plan hashes. A plan_hash from one Zap version may not bind a wetrun on another. After an upgrade, a recorded preview or an --expect-plan <hash> can refuse; preview again and review the new plan.
• The last-run report and the deploy preview under ~/.zap. A record in another format is ignored, the same as having none.
• Each lock entry's config_hash. When the way a declaration is hashed moves, every tracked entry reads stale: zap apply stops with an error naming zap update <id>, and the read-only commands hold those resources until it runs. zap update fetches again and re-mints. Because it fetches, a source whose bytes changed upstream comes back with a new pin, so read the lock's diff before you commit it.
• Provenance sidecars and extract sentinels on the target. When what they record moves, each build rebuilds and each extracted remote file re-extracts once, on the next wetrun.
• The evaluation cache. Internal, and rebuilt as needed.

Not part of the interface

• The human-readable output: plan rendering, wording, banners, layout. A script should read exit codes and --json events, not text.
• The Rust crates. They aren't published; the zap binary is the interface.
• Anything the docs describe as internal or as a current limitation.

Every zap command, its flags, what it reads and writes, and its exit codes. For what the commands mean, see concepts.md; for a first run, see getting-started.md.

Every command that takes a config defaults it to ./zap.ts. zap with no command prints the loop and exits 0; zap --help prints the command list, and --help on any command prints its flags.

Commands at a glance

All of them but version evaluate the config first, with the fgro build zap.lock pins (zap lock pins the one it is given), and run the two machine-free gates: a hardcoded secret literal or a structural error (a duplicate id, a dangling depends_on, a cycle, service intent on a target with no service_manager, …) fails every command with the same message. See configs.md.

Shared flags

zap plan

Detects every declared resource live and renders the changeset: one [+] (create) or [~] (update) line per resource, its steps under it, and the plan_hash at the end. --diff adds per-resource current → desired attribute lines above a drifted resource's steps; every change still shows its steps, so the view prints everything the plan_hash covers, as zap plan does.

Under the header come the lines naming the machine and environment the plan is for. They are part of the plan and its hash, so a preview made as one user or under one HOME doesn't bind a wetrun as another: sudo zap apply --wetrun runs as root and refuses a review made without it.

Under each change come the lines that say what it declares (its name: when it has one, a file's path:, mode:, and content: descriptor, a link's to:, a script's check:, cwd:, and env:, an apt_repo's key: URL and the pin: its bytes must have, a swap's size:, a pipeline's max_concurrency: and its step: ids and step name: labels), then its steps. A content: descriptor's SHA-512 is of the text as written: for a template, the template before its variables are filled, followed on the same line by its vars and their kinds, each as JSON. Multi-line text prints indented under its first line, and control and invisible characters print as <U+XXXX> (security.md).

A step line starts with >, #, or =. > is a command Zap runs as written. # is never run as written: it is a verify assertion Zap checks itself, or a step the target's manager has no command for. = is one of Zap's own operations, named with what it acts on and never printed as the script that performs it:

• = put <path> installs a file (security.md). The parentheses give its mode, the account the write runs as, and a check the staged file must pass. Text Zap holds prints whole under text:, less its final newline, with its length and the start of its SHA-512; a text with no final newline says so in the parentheses. Text the target produces has a from: line saying where it comes from and what skips the put. Text the config supplies for it prints under line:: an apt source line (which the target's shell expands, at every plan as well as on apply, so a $VERSION_CODENAME in it is read there and a $(…) in it runs), an /etc/fstab entry.
• = run the script fetched from <url> (piped to <shell>) is an installer: the URL and the shell as the config declares them.
• = dir <path> creates a directory if it is missing and sets its mode and owner.
• = check <path> (not a link, below directories only root writes, as root) comes first in a swap file's creation, and refuses a link at the path or a directory on the way to it that another account can write (resources.md).
• = pg_hba rule: <line> adds the line to the server's pg_hba.conf, as the postgres account, unless it is already there. A line it adds is put in force by reloading the server's configuration; a line already there reloads nothing. A file that doesn't belong to postgres is left unchanged and the step fails, and so does a file the server can't parse (pg_hba_file_rules lists an error, checked before the reload), a reload it doesn't confirm, or a reload it doesn't load within 30 seconds.

A = step that fails is reported by the same words, in the run's report and in the change_failed event's error: put /etc/sudoers.d/deploy (mode 440, as root, checked by visudo) exited 93: ….

A pass that can't establish a verdict says so before the plan, under an UNDETERMINED, UNVERIFIABLE, or LOCK banner.

Exit codes:

The pass is recorded as a preview, so a following zap apply --wetrun binds to its plan (concepts.md). A plan whose host or connecting user resolves through a masked reference names no one machine: it is shown under an UNBINDABLE note with no plan_hash, and is not a preview. When it is the host, the pass also keeps no last-run report and says so under an UNRECORDED note.

zap apply

Without --wetrun, the same pass as plan, rendered as what apply would do, and exit codes that judge the result (below). It also resolves any missing tracked pin over the network and reports it as resolved, not yet written to zap.lock; the write waits for a wetrun.

--no-lock leaves the lock's entries alone: no tracked pin is read, nothing is fetched to pin a tracked source, and nothing is written. A tracked source then has no pin, so its resource holds; a config with none runs as usual, offline. The toolchain pin is still read, and without one the command refuses as any other does.

With --wetrun, apply:

1. rejects the run if any variable the config references is unset or empty, or if the target's host or connecting user resolves through a masked reference;
2. detects and plans;
3. checks the plan against the review (next section) and refuses if it doesn't match, or on an interactive terminal shows the plan and asks;
4. refuses if any planned command can't take a value its reference resolves to (a single quote in a command, for one), naming the resource and the variable; zap plan and a dry run warn about the same thing ahead of time;
5. claims the preview it bound to, so one preview covers one wetrun: of two wetruns started on one preview, the one that claims it first goes on and the other stops with nothing changed (exit 2);
6. re-checks that every reference the plan recorded still resolves to the recorded value, refusing (exit 2) if one moved while the run was in progress;
7. writes zap.lock when the config has tracked pins;
8. executes the changes in dependency order, stopping at the first failure, writing a pending-trigger marker on the target before the first source of a triggered service and clearing it after the service's change;
9. re-detects every resource and reports any that still isn't converged as RESIDUAL.

Binding to the review

A wetrun executes only the plan you reviewed: the plan it computes must equal, hash for hash, the one named by --expect-plan <hash> or the one in the most recent preview on this host. Otherwise it refuses, changes nothing, and exits 2. The rules are in concepts.md.

On an interactive terminal, a wetrun whose plan has no review (no preview, or a preview of a different plan) and no --expect-plan shows the plan and asks instead:

The plan and the question go to standard error; the report goes where it always does. The answer is the first eight characters of the plan's plan_hash, in either case. Input typed before the question appears is discarded, so neither a y nor an earlier run's answer typed ahead while Zap reads the machine runs anything. Those characters execute the plan shown and nothing else; any other answer (a y, the whole hash, an empty line, the end of the input) declines: the plan is rendered again under a DECLINED banner, recorded as the preview, and the exit is 2, as for a refusal. There is no flag that answers for you. Interrupting at the question (Ctrl-C) ends the run with nothing executed and nothing recorded as a preview, so the next wetrun asks again. It never asks under --json, for a mismatched --expect-plan, for a plan with no hash, or for a plan a command can't run.

Scripting. The question appears only on an interactive terminal, for a plan with no review. A script stays non-interactive by previewing first (a dry run, then the wetrun), by passing --expect-plan <hash>, or by running with standard input that isn't a terminal (< /dev/null). A non-interactive wetrun with no review of its plan refuses, and --json never asks.

--expect-plan makes the binding explicit: the hash from the plan you reviewed, perhaps in a pull request or an agent's transcript. The match is exact. A dry run rejects the flag. zap deploy follows the same rule against its own preview (below).

Exit codes:

zap deploy

Ships a release to a remote target: build locally, tarball the artifacts, upload, extract into releases/<version>, swap the current symlink, restart the service, poll health. Full mechanism: deploy.md.

A dry run reads zap.lock, connects over SSH to read the live current symlink, prints the plan (the resolved host, the declared target, the tree and preflight state, and every step with its command, script, paths, or URL), ends with the plan_hash, records the plan as this host's deploy preview, and exits 0. If the live release is already this version it reports server already at this version, prints no hash, records nothing, and exits 0, on a dry run too; --force deploys anyway.

A dry run prints no plan_hash and records no preview when:

• the host, connecting user, or health domain resolves through a masked reference;
• the checkout has uncommitted changes or untracked files and no --force (never reported as already at this version, since the tree isn't what the live release holds).

A wetrun of either is refused.

A wetrun executes only the reviewed plan, as zap apply's does, but against the deploy preview: its plan's hash must equal --expect-plan or the recorded preview's, or it refuses before the preflight and any step, becomes the new preview, and exits 2 (on an interactive terminal with no --expect-plan it asks for the start of the plan_hash instead). A wetrun that passes withdraws the preview before its first step, so one recorded preview covers one execution. zap status doesn't show the deploy preview. The rules are in deploy.md.

Flags:

--skip-build, --skip-preflight, --force on a dirty tree, and --bootstrap each change the plan, and so its hash: a wetrun binds to a preview made with the same flags.

Exit codes:

zap detect

The detection half of plan, rendered raw: one line per resource with its mark (ok, drift, absent, or ? for undetermined), its id and kind, and, for drift, what was observed. For validating that a probe reads a real target correctly. Over a host that resolves through a masked reference it keeps no last-run report and ends with an UNRECORDED note.

zap status

Offline: evaluates the config, reads the last-run report for the host the target resolves to (detection.md) and the on-disk zap.lock, and never touches the target. It says what the last run saw, never what the target is now; the live signal is zap plan. A referenced host needs its env (--env-file), as for a run. For an exact answer it needs the same env as the run that wrote the report, secrets included: a secret it can't mask reads as "config changed since", never as a false "unchanged".

Each line is a resource's verdict in that run, with a note when:

A preview's plan_hash is printed as the plan zap apply --wetrun binds to. The lock standing and an UNVERIFIABLE banner, for the last run or for now, lead the render. With no last run every resource is not read, so status exits 1 unless nothing is declared.

zap config validate

Evaluates the config and runs the two gates, nothing else. Prints ok: N resource(s) and exits 0, or the gate's message and exits 2. The fast check for CI and editors: no target, no network, no secrets needed, but a copy of the pinned fgro build (lock.md).

zap lock

The verbs over zap.lock, the ledger for the toolchain pin and the tracked remote files and build sources (lock.md).

zap lock pins the toolchain, the blake3 of the fgro binary it evaluates the config with, re-fetches every tracked source, re-mints every entry, drops orphans, and rewrites the file. All or nothing. It is the only command that evaluates with a binary the lock doesn't pin, and the only one that moves the toolchain pin (lock.md).

zap lock --check first holds the fgro binary to the toolchain pin: with a binary that hashes to something else it reports the pin stale without evaluating the config, so the entries go unchecked. Otherwise it classifies each entry offline as current, missing, stale (the resource changed since the pin), unverifiable (a variable the hash takes by value is unset), or orphaned. Its 1 is a read-only verdict, like plan's held resources; apply, which refuses to act on a stale or unverifiable entry, treats the same finding as an error and exits 2, as does a deploy wetrun's preflight.

Both print a note: for each reference the lock addresses by name only, because its name or the form of its value reads as a secret (lock.md).

zap update

Re-fetches the named resources, or every tracked one, and rewrites each entry whose pin advanced or whose recorded config hash is stale. Each advance is written as it happens, so a later failure keeps the earlier ones. A tracked URL that references an unset or empty variable is never fetched, and that entry fails. The config is --config <path> here, since the positional arguments are ids. A failed entry keeps the code its error has everywhere else: exit 1 if any failure is operational (a fetch, a write), else 2 if any entry failed on an input to fix (an unset reference in its URL or credential, a signature that doesn't verify). It prints the same note: lines as zap lock.

zap version

Prints zap <version>.

Banners

What a pass couldn't establish, or why it didn't act, leads its report:

Exit codes, all commands

The pattern across commands. The tables list 2 before 1 because 2 is still an established answer and 1 is not:

plan, detect, and a deploy dry run report rather than judge: pending changes exit 0 there.

An error prints as error: and its message; a message of several lines is indented under it, and any advice Zap adds follows at the left margin.

Errors raised before a report exists follow the same split.

Exit 2, a problem in your inputs:

• fgro: none named; a path that isn't absolute; one that is missing, a link, a script or set-ID file, or doesn't hash to the toolchain pin; one that answers in an eval protocol or graph version this zap doesn't read; no toolchain pin; an fgro pin cache under ~/.zap that isn't yours.
• zap.lock: one that doesn't parse or is newer than this zap reads; a lock stale or unverifiable; a content-hash or signature mismatch.
• The config: not found; named as its own lock would be (*.lock); it or its directory writable by every user; no project; a package.json on the way up that can't be read or isn't valid; no user the evaluation may run as (a project root owns, a project that is or holds that user's home, a directory on the way it can't search, a group or passwd entry it can't use); eval failure; a schema error.
• The environment: an env-file error; a ZAP_HOME or HOME unset where needed or not absolute; a state directory that isn't Zap's own; an unresolved reference on a wetrun.
• A wetrun refused before its first change: a plan that names no one machine, a command that can't take a value its reference resolves to, or a reference that moved while the run was in progress.
• A deploy wetrun from a checkout with uncommitted changes or untracked files and no --force.
• A usage error: an unknown flag, or --expect-plan without --wetrun.

Exit 1, a problem in the world: connectivity, a command that can't spawn, a file operation, a fetch, a git error; an fgro that crashed, wrote output that isn't its protocol, or couldn't be spawned; an fgro binary written while Zap hashed it or before it ran, which a retry clears once nothing writes it.

JSON events

--json on a wetrun of apply or deploy streams one JSON object per line to stdout, instead of the text report. A wetrun that ends before its first event (a refusal, a preflight bail, an already-deployed release) leaves stdout empty and prints its text report to stderr. Control and invisible characters in a value are written as JSON \u escapes, so the stream decodes to the same values and is safe to watch. Each event carries an event tag:

A step skipped after an earlier failure has no step_started, but a started step's outcome can be step_skipped too: a readiness check the target doesn't serve, or a rollback whose swap back finds nothing to do (another deploy holds the app's lock, current no longer names the failed release, or names nothing, or the previous release is gone). A rollback with nothing to return to is skipped without starting.

code on a failure is a triage category: transient, permission, not_found, conflict, permanent, or execution_failed (permission includes sudo's own refusals). A file operation Zap makes itself is classified by the error the system returned (a symbolic link or anything else in the way, or a full disk, is conflict; a timeout is transient); a command, or ssh, by its exit code and what it printed. Every value is masked: a resolved secret never appears in an event.

A run that streamed events doesn't print its text report, and the report's warning: lines go with it: the stream carries a warning only where an event holds it. A deploy's rollback is always one: rolled back, failed, or skipped, with nothing to return to (a broken release left live) among the skips. The others, such as a deploy's repairs of an unfinished one or a failed prune, aren't in the stream.

Environment variables Zap reads

Nothing that shapes a plan comes from Zap's own environment. Values a config needs come from references resolved from the operator environment or --env-file.

A Zap config (zap.ts) declares resources: typed descriptions of desired machine state. Zap detects the live state, compares it to the declared resources, and applies the smallest set of changes that converges them. Each resource has a stable id, an optional name, an optional depends_on list, and a kind, set by the builder method you call (it becomes the type in the JSON the config evaluates to).

Resource types

Each section below gives the resource's purpose, its fields, and any structure specific to the type. In path fields, references resolve against the operator environment, and ~ and $HOME resolve against the target's home. Both happen when Zap reads or changes the machine, and the plan holds both as written (env.md).

One resource per thing

Two resources that manage one thing would undo each other on every apply, so a config that declares them doesn't validate; the message names both ids and the thing. What a resource manages:

A package, a script, an installer, a pipeline, and a verify manage nothing exclusive, so the same package may be declared twice. Two resources at one path conflict even when they declare the same thing, so a directory two recipes both need is declared once. Paths are compared as written, after //, /./, and a trailing / are dropped and $HOME is read as ~; two spellings that only meet on the machine (~/x and /home/ops/x, a .. component, nginx and nginx.service) aren't caught.

URLs

A URL in a config is https:// with a host, and holds no user:password@ (a credential goes in auth, where it is a reference). Any other scheme is refused, http:// and file:// included, when the config is read and again on the resolved value when the URL holds a reference. For the URLs Zap itself fetches (a remote file's, a build source's and its signature's, an apt_repo's key_url), http:// is accepted for a loopback host (localhost, 127.0.0.0/8, [::1]), which is what a local mirror or a test uses. A redirect is followed only to another https:// URL; a fetch that has stayed on loopback may be redirected on loopback. The URL the target fetches (installer.url) is https:// only.

Account names

username, groups, and every owner and group field take an account name, such as 'deploy', not a numeric uid or gid. Zap compares ownership against the name from stat, so a numeric value is rejected when the config is read.

The name must be a portable Unix account name: a lowercase letter or _, then lowercase letters, digits, _, or -, optionally ending in $. That is the useradd default on Debian and Alpine. Anything else (an uppercase letter, a space, /, a comma, a backslash) is rejected there too. The name is interpolated into awk, usermod -aG, a sudoers drop-in, and /home/<name> paths, where a stray character would break out of the form.

package

An OS package, installed through the target's package manager: apt (Debian/Ubuntu) or apk (Alpine). The other managers (pacman, brew) parse but have no backend, so their packages detect as undetermined.

• from (required): a map from package manager to package name, such as {apt: 'ripgrep'}. The target's package_manager selects the entry. A name takes no reference; see Package names.
• check (optional): a custom check, either a path (tested for existence) or a command (exit 0). It defaults to the manager's own query. A check beginning /, ~, or $HOME is a path, and its references resolve; anything else is a command, run as written, and takes no reference. With no check, a package with no entry for the target's package_manager, or a target that declares none, holds (undetermined).

Installs are batched, after an automatic cache-update step. A package that waits on another resource that waits on a package installs in a later batch (batch-install-<manager>-2, …), after that resource. Detection is by existence through the manager's query: a package held back, or installed for any architecture, is installed. A query that fails (the database unreadable, the tool missing) holds the package as undetermined rather than reading it missing.

Package names

A name is one word in the manager's syntax: a letter or a digit, then letters, digits, and + . _ - = ~ : / @, not ending in -. Zap writes it into the manager's command line unquoted, so a space or a shell character is refused. The form decides what reads as installed:

A version and a suite together name no package apt knows. Refused, because the query would never find the package installed or the form isn't one word:

• apt: an empty version (name=) or architecture (name:); name:any and name:native, which apt resolves to an architecture and dpkg records no package under; name:all, which apt reads as the native architecture while dpkg records all only for a package built for every one (name the architecture, or none); an architecture that isn't one word of lowercase letters, digits, and -.
• apk: name>=1.2, !name, .name; a version operator with nothing after it (name=, name~, name==, name@tag=), which apk's query reads installed whether or not it is and apk add refuses.

A trailing + is part of the name, since Debian has packages named so (memtest86+). apt's own name+ install marker on a package with no + installs it but never reads installed, so write the name without it.

apt_repo

An apt repository: a GPG signing key plus a sources-list entry. Zap installs the key, writes the .list file, and injects signed-by=<key_path> into the source line automatically, so the key and the repo can't drift apart.

• key_url (required): the URL Zap fetches the GPG signing key from (URLs). It may carry a reference.
• key_blake3 (optional): the key's pin, the blake3 of its bytes, 64 lowercase hex. Without it the pin is tracked in zap.lock (lock.md).
• source (required): the deb or deb-src source line. signed-by= is injected from key_path.
• key_path (optional): where the key is stored. It defaults to /usr/share/keyrings/<id>.asc.
• list_file (optional): the .list file path. It defaults to /etc/apt/sources.list.d/<id>.list. The list is installed whole, mode 644.

key_path and list_file take no reference; key_url may carry one. Each of the two paths is absolute and holds no whitespace and none of ", $, a backtick, or \.

source is written through a shell with /etc/os-release sourced, so it can reference the distro's variables for portability. For example, deb … $VERSION_CODENAME main resolves to bookworm, noble, and so on, on the target. key_path is written into that line, so the shell reads it too. list_file is passed literally; key_url is fetched by Zap on the operator's machine and never reaches the target. The detector resolves source the same way, so a templated line still converges. Because the shell reads the line, source takes no reference.

The key is pinned content, like a remote file's. Zap fetches it on the operator's machine, checks the bytes against the pin, and installs those bytes whole at key_path, mode 644, owned by root:root: staged beside the key, checked against their SHA-512, and renamed over it, so the live key is only ever replaced by the pinned bytes. A fetch whose bytes aren't the pin's fails the change before anything on the target is touched, naming both digests:

Detection reads the key and compares its blake3 with the pin: a key that isn't the pinned bytes drifts (signing key differs from its pin), and the apply installs the pinned one. A rotated upstream key is not drift until the pin moves: zap update <id> fetches the key again and advances the pin, which shows in the lock's diff. A key with no pin yet is held (undetermined) by the read-only commands, a dry apply mints its pin, and a wetrun records it in zap.lock before it runs, as for any tracked content. A key_path that is a symbolic link, a hard link, or not a regular file, or a key over 1 MiB, is held too: its bytes aren't compared.

script

An imperative command guarded by an idempotency check. Zap runs check first. An exit code of 0 means the script is already applied and run is skipped. Otherwise run executes.

• check (required): a command whose exit 0 means "already applied", which skips run.
• run (required): the command run when check fails.
• cwd (optional): the working directory for check and run. An absolute path, taken as written: a reference is rejected when the config is read, and a ~ or a relative path by the structural gate.
• env (optional): extra environment for the whole of check and run. Values resolve references and can hold any byte but NUL (and the two characters Zap marks a reference with, U+FDD0 and U+FDD1), so env is how a script takes a value with a ' in it, or a secret. A name can't begin with __zap_.

The check carries the whole idempotency contract. Make it precise, or the script runs on every apply.

cwd and env apply to both commands, the same way on a local target and over SSH: Zap enters cwd, exports env for the whole command (every command of a compound sees it), then runs your text on a line of its own. The plan shows them, and the check, above the command:

A check that can't enter cwd reads as not applied, like any failing check, so a script whose cwd another resource creates converges in one apply. A run that can't enter it fails the change with nothing run. A sudo inside either command resets the environment by default, so env doesn't cross it.

installer

Software installed by running a downloaded script, the curl … | sh pattern, gated by a check so it runs only once. Zap fetches the script whole first and hands it to the shell only if the fetch succeeded and the script isn't empty, so a failed download fails the step and nothing runs.

• url (required): the install script's https:// URL (URLs), piped into shell.
• check (required): a path, absolute or beginning with ~ or $HOME, tested for existence to confirm installation.
• shell (optional): the command the script is piped into (default sh). It is one line, shown in the step as written and read by the target's shell like a script's run, so bash -s -- --yes passes arguments.

An installer executes remote code on the target, so prefer a pinned, trusted URL. For content that should be verified and pinned, a build or a file with remote content is the stronger choice.

user

A Unix user account. Zap creates the account if it doesn't exist, with useradd -m -d /home/<username>, so the home is /home/<username> whatever the distro's default. Zap then detects and reconciles each managed attribute independently. An attribute left unset is unmanaged: Zap neither sets nor reverts it.

Zap manages a user's home as /home/<username>: the paths home_mode and ssh_keys act on are derived from the name, not read from the machine. The cases where that would be wrong fail loudly instead:

• A user with username: 'root', whose home is /root, is rejected by the structural gate before any run, whatever it declares. Manage root's files with file and directory resources.
• An existing account whose home in /etc/passwd is anything else, or that has none there, is held (undetermined) when the user declares home_mode or ssh_keys, and the reason names the home it found:deploy's home in /etc/passwd is /srv/deploy, not /home/deploy: zap manages a user's home as /home/<name>, so its `home_mode` and `ssh_keys` would miss the account's own

  An account that doesn't exist yet has no /etc/passwd home to hold it: Zap creates it.

• What is at /home/<username> is read too, without following a link, whether the account exists or not. useradd leaves a directory already there as it was, owned by root typically, and copies no skeleton files into it:
  • when Zap creates the account, the creation gives the directory itself, not what it holds, to the user and its login group after useradd: sudo chown -h -- 'deploy:' '/home/deploy', a no-op when useradd made the directory;
  • for an existing account, a directory the user owns or root owns is as declared and keeps its owner, so a home sshd's ChrootDirectory needs root to own stays root's;
  • a directory owned by any other uid, a live account's or one no account has, holds the user, existing or not;
  • a symbolic link at /home/<username> holds the user and is not followed: Zap acts through no link it didn't make, so a layout that links the home elsewhere declares neither home_mode nor ssh_keys; anything else that isn't a directory holds too;
  • a /home that is missing, or that the connecting user can't search, holds the user, naming /home, rather than reading as nothing there.
  /home/deploy is owned by uid 1002 (deploy's uid is 1001); chown it to deploy, or remove it: zap manages a user's home as the directory /home/deploy, the user's own or root's

  A user that declares neither home_mode nor ssh_keys isn't read for its home.

• username (required): the Unix username to manage. It must be a portable account name; see Account names. groups entries follow the same rule.
• shell (optional): the login shell, such as /bin/bash. The system default applies when unset. It takes no reference.
• home_mode (optional): the octal mode for the home directory, such as 711.
• ssh_keys (optional): the SSH authorized_keys, as either {copy_from: '<user>'} or {keys: ['ssh-ed25519 …', …]}, never both: an object with both is rejected before any run. A keys list needs at least one key, and no entry may be blank. See SSH keys.
• sudo (optional): the user's sudo grant. See Sudo.
• groups (optional): supplementary groups the user must belong to, such as ['docker', 'postgres']. It is additive: listed groups are added (usermod -aG) and groups not listed are left untouched. The primary and system groups are never stripped. Names only, like owner.

SSH keys

ssh_keys is authoritative. Zap writes authorized_keys to exactly the declared set and detects drift by comparing the file's content. A key added out of band is removed on the next apply, and a rotated or removed key is applied again.

A key is installed as written and takes no reference; one is rejected before any run. An entry is one key on one line: an entry that ends in a line break doesn't validate. A config reads no file but its imports, so for keys that differ per environment, have the config import them from a module in the project (export const OPS_KEYS = ['ssh-ed25519 AAAA… ops'];).

For copy_from, the source user's authorized_keys is the desired content. If it can't be read, the user is applied again and does not read converged.

Zap gives the account its ~/.ssh (mode 700, owned by the user; a symlink there is refused, not followed) and then writes authorized_keys as that user, mode 600, so nothing the user plants in its own .ssh can redirect the write anywhere the user couldn't already write. A copy_from source is read as the source user at apply. Other files in .ssh are left as they are.

Setting ssh_keys also normalizes the account's /etc/shadow password field to *, which means no password and not locked. This is authoritative too: any other value drifts and converges back to *. That covers:

• a ! lock. useradd leaves a passwordless account locked, and Alpine's sshd refuses pubkey login to a locked account ("account is locked").
• an empty field, which allows passwordless login and is a security hole;
• a set password.

Sudo

• 'nopasswd' or 'password' grants sudo for all commands.
• {mode: 'nopasswd' | 'password', commands: ['<sudoers spec>', …]} restricts the grant to the listed commands. A spec is written into the file as declared and takes no reference. The list can't be empty, and a spec can't be blank or hold a control character (a tab counts): each is rejected when the config is read. For a grant of every command, write the mode alone. A spec is sudoers text, so a , in one ends a command and begins another.
• false removes the user's sudoers file.
• true is rejected at parse. It grants nothing, and would otherwise read as a removal.

The sudoers file is installed at mode 440 only after visudo -c accepts it; a file visudo rejects is never installed, and the old one stays.

directory

A directory at path, with optional managed permissions.

• path (required): the directory path, absolute or under ~. It may carry a reference, and the value it resolves to is held to the same rule.
• mode (optional): the octal mode, such as '755', 7777 at most.
• owner (optional): the owner.
• group (optional): the group.

Zap makes the directory and any missing parents. Each one it makes, the directory itself included, takes the owner and group of the nearest directory that was already there, and the mode a plain mkdir gives; then the declared mode, owner, and group are set. So an owner or group left unset is inherited from above, and an existing directory keeps its own. Anywhere below a directory with its sticky bit set or that every account may write (/tmp, /var/tmp, /dev/shm), however deep, on the path as written or where its links lead, nothing is inherited: what Zap makes there is the writer's. On a local target, directories that take another account's owner, or a group you aren't in, are made through sudo.

With a managed mode, owner, or group, a symlink at path reads as drift and fails the change: Zap sets a directory's attributes on the directory itself and never through a link. Use link for a symlink.

file

A file with managed content and optional permissions. Content comes from one of these sources, selected by content.type: inline, template, source, or remote.

The file's parent directory is created automatically if missing, like mkdir -p: each directory made takes the owner and group of the nearest one that was already there (the writer's, below a directory anyone may write, as in directory), and the mode a plain mkdir gives; an existing one is left as it is. A separate directory resource is only needed when the directory itself wants a managed mode or owner.

A file is a regular file, written whole: Zap stages the content under a new name beside it (.zap.XXXXXX, mode 600 until a declared mode is set), checks over SSH or sudo that the bytes that arrived are the bytes it sent, sets the declared owner and mode on that staged file, and renames it into place. So the file never exists at its path with partial content or the wrong mode, a mode or owner drift rewrites it, and a symlink at the path is replaced by the file, not followed (a symlink to a directory fails the change on Alpine; with a managed mode, owner, or group, a symlink there reads as drift). Use link for a symlink.

A mode, owner, or group the file leaves unset is kept: a rewrite gives the new content the owner and group of the file it replaces, and its mode without any set-id or sticky bit. A new file takes its directory's owner and group, and the mode a plain create gives (0666 less the writer's umask). A symlink at the path, or a file with a second name (a hard link), keeps nothing; the file that replaces it is the writer's. Nothing is kept anywhere below a directory with its sticky bit set or that every account may write (/tmp, /var/tmp, /dev/shm), however deep, on the path as written or where its links lead: anyone could have put what is there, or made a directory or a link on the way, so the file is the writer's.

A mode is never kept from a file with an extended POSIX access list (ACL): its mode bits show the list's mask rather than its group's, and the rewrite carries no list, so a kept mode would hand the group what the list gave one account. A file that leaves mode unset over such a file fails the change, with the file as it was, asking for a declared mode. Zap reads the list with getfacl, else from the + GNU ls -l prints after the mode; a target with neither, such as stock Alpine (BusyBox ls, no acl package), can't show one, and there the mode is kept. On a local target, keeping an owner or group you can't give, such as another account's file or a new file in a directory root owns, goes through sudo.

Declare mode, owner, and group on any file whose content the directory's owner or group must not read. Without them, a file written into a directory another account can write can end up readable by that account: it takes that account's directory's owner and group, or the owner, group, and mode of the file that account planted at the path. A declared owner and group don't replace a planted file's mode, so without a mode the content can land readable by everyone (security.md).

• path (required): the target path. It may carry a reference and ~.
• content (required): the content source. See content.
• mode (optional): the octal mode, such as '644'.
• owner (optional): the owner, as a user name and not a numeric uid. See Account names.
• group (optional): the group, as a group name and not a numeric gid.
• triggers (optional): ids of service resources notified when this file changes; naming any other kind doesn't validate. This is the push side of the trigger model; see service.
• validate (optional): a command that must exit 0 after the write, such as sudo nginx -t (exported as NGINX_VALIDATE from recipe_nginx.ts). See Validated writes.

Validated writes

With validate set, apply snapshots the file (its bytes, mode, and owner, read through one open descriptor and held in memory: as root over SSH, and locally as you, escalating when refused), writes, then runs the command against the file in place. A symlink at the path, anything there that isn't a regular file, and a file over 16 MiB can't be snapshotted, so the change fails before the write. If the check fails, the snapshot goes back as a regular file with the owner and group the old content had, and its mode without any set-id or sticky bit the declared mode doesn't carry; a file that didn't exist is removed; and the change fails. So any service the file triggers is never reloaded onto the bad config. A write that fails before installing leaves the file as it was, and restores nothing.

Checking in place is what lets it cover a file some larger config includes: nginx -t can't check a site file on its own.

What it doesn't cover:

• One file at a time. Each file is checked against whatever else is on disk. An edit that has to land in two files at once (renaming a zone one file defines and another uses) fails the first file's check and rolls it back. Stage the edit across applies: add the new name, switch the user, drop the old.
• Not yet active. The check only sees what the parent config loads. An nginx site in sites-available/ isn't checked until its sites-enabled/ link exists, so on a fresh host the first real check is the reload.
• The write-to-restore window. The rejected content is on disk for one command's round trip. A run killed inside it leaves that content in place, and detection reads it as converged, since the bytes match what was declared.

The last two, plus hand edits on the host, are what a verify running the same command closes. It is checked again on every plan. A config the running service couldn't reload onto then shows up as a pending change and does not read as converged, and zap deploy's preflight refuses to ship over it:

validate is apply-time behavior, not desired state: detection doesn't read it, and changing it alone plans no change. It is still part of the declaration: the last-run report's hash covers it, and so does plan_hash whenever the file has a change in the plan. The lock's config_hash leaves it out. It is for text config (inline, template, source), and is rejected on remote content and when blank.

content

The content source is discriminated on type.

inline: literal content, written verbatim.

• type (required): 'inline'.
• content (required): the file's content, installed as declared. It takes no reference.

template: a {{key}} template with per-variable substitution.

• type (required): 'template'.
• template (required): the template body, with {{key}} placeholders. A placeholder is a variable's name between the braces and nothing else; braces around anything that isn't a name ({{ .Values.port }}) are text.
• vars (optional): the values substituted for each {{key}}, after a reference in a string value resolves. A value that isn't a string is substituted as its compact JSON text and takes no reference at any depth; pass the value as a string var of its own. A reference can't stand for the whole vars map. A value with no kind is substituted as text, so it has to be safe where it lands: in a file a shell or systemd's EnvironmentFile= reads, a value holding a ' ends its quoting.
• kinds (optional): the kind of value a variable must render to, by its name. Each key names a variable in vars. A variable not named here declares no kind: a reference in its value is still held to the text rule, and a value written out is substituted unchecked.

Placeholders and variables match one for one: a {{name}} whose name is letters, digits, and _ (not starting with a digit) and that has no variable of that name doesn't validate, and neither does a variable no placeholder names, so a misspelled name is caught in either direction. The body is substituted in one pass and a value is never read again, so a value may hold {{…}} as text; that is also how a literal {{name}} is written.

A reference's value can't hold a line break (CR or LF) or a NUL: the files a template makes are read a line at a time, and a line break in a value would add a line of its own (another variable in an environment file, another directive in a config). Detection holds the file and names the variable, and a wetrun is refused before anything changes.

Within its line, what a value may hold is the file's grammar: a ; or a } in an nginx server_name {{domain}} ends the directive or the block. A kind holds a variable's whole rendered value to a form whose alphabet has none of that:

A value written out is checked when the config is read. One carrying a reference is checked once it resolves: detection holds the file, and a wetrun is refused before anything changes, naming the variable and its kind, never the value. The nginx site and env recipes return their templates whole, with the kinds of the variables they place (recipes.md).

source: content copied from a file already on the target at apply time.

• type (required): 'source'.
• path (required): a path on the target, absolute or under ~. It may carry a reference.

The source is read as root over SSH, byte for byte, so a binary file copies whole. It must be a regular file of its own at that path: a symbolic link there is never read through, and neither is a directory, a device, or a fifo. Detection holds the resource on any of them, and apply refuses them with nothing written. The bytes are held in memory while they are written, so a source larger than 16 MiB is refused at apply.

remote: content fetched from a URL, content-addressed and verified the same way a build source is.

• type (required): 'remote'.
• url (required): the fetch location (URLs). It may carry a reference, resolved when Zap fetches; how the lock addresses it is in lock.md.
• extract (optional): how the bytes are materialized. {type: 'none'} is the default; {type: 'tar.xz' | 'tar.gz', strip_components?: N} extracts an archive. strip_components lives inside the tar form (beside none it is rejected), and strips leading path components: 1 flattens a tarball's single top directory.
• auth (optional): a bearer credential for a private byte host, resolved at the IO boundary and never hashed. See Remote auth.
• blake3 (optional): a vendored content pin. Present, the file pins itself; absent, it tracks through zap.lock. See lock.md.

How a remote file is detected. An unextracted file by digest against the pinned bytes, an extracted one through its .zap_remote_hash sentinel; detection never fetches. See detection.md.

Placement and ownership. Placement and extraction escalate as needed: a none placement or an archive extract into a root-owned destination (such as /opt/zig) runs under sudo. When extract produces a directory tree, a declared mode, owner, or group applies to the top-level destination only (a symlink there holds the resource, and nothing is extracted through it). The extracted contents below it belong to the extracting user, which is root when the extract escalated, whatever owners the archive records, and carry no set-id bit on a file and no group or world write bit. The archive is extracted into a private directory beside the destination, which then takes the destination's name; a failed extraction leaves the destination as it was. A new pin replaces the old tree whole, and the new one gets the owner, group, and mode the old one had (without a set-id or sticky bit) before it takes the name, so what the resource leaves unset there is kept, and a failure to set them leaves the old tree in place. Below a directory with its sticky bit set or that every account may write, nothing is kept, as for a file: the new tree is the extracting user's, at the mode mkdir gives it. A replaced tree that has a POSIX access list (ACL), a default one included, fails the change with the old tree in place, whatever mode declares; remove the list (setfacl -b) to let Zap replace it. The archive never sets the destination's mode, whatever it records for its top directory: a new destination keeps what mkdir gives it. Zap replaces only a tree it extracted (one holding its sentinel) or an empty directory; a destination holding anything else holds the resource (undetermined), and nothing is extracted into it. If the whole tree needs a specific owner, apply it with a script running a recursive chown.

The swap needs room for the old and the new tree at once, and the archive sits on the target three times while it extracts: the upload in a private directory under /tmp, the copy the extraction checks and reads, on the destination's parent filesystem, and the tree it extracts. A run that is killed can leave a mode 0700 .<name>.zap-XXXXXX directory of the extracting user's (root's, when it escalated) beside the destination; killed between the two renames, it holds the old tree. One is also left, empty, where an account that can write the parent renamed it. The staging name is 12 bytes longer than the destination's, so a destination name within 12 bytes of the filesystem's NAME_MAX can't be extracted.

Remote auth

For a private byte host, attach a bearer credential. Its token is typically a reference, resolved on the operator side at fetch time. It is never written to the content hash, and an empty resolution is an error, not a bogus request.

link

A symbolic link at path pointing to target.

• path (required): the symlink path. It may carry a reference and ~.
• target (required): what the link points to, resolved the same way.

A regular file sitting at path reads as absent and is replaced by the link. A directory there also reads absent, but the step fails rather than putting the link inside it: move the directory, or point the resource at another path.

service

A system service managed through the target's service manager (systemd or OpenRC). It controls whether the service is enabled at boot and whether it is running, and it can restart or reload in response to other resources changing. That is the pull side of the trigger model; file's triggers is the push side.

• service (required): the service name, as the target's service manager knows it. It takes no reference, and is one word: a letter or a digit, then letters, digits, and _ . @ : - (nginx, getty@tty1.service). Zap writes it into the manager's command line unquoted, so a systemd name escaped with a backslash isn't accepted.
• enabled (optional): whether the service is enabled at boot (default true).
• running (optional): whether it should be running now. Omit it to leave runtime state unmanaged. On OpenRC, starting a crashed service (its daemon died while it was marked started) first resets it with rc-service <svc> zap, since a plain start of a crashed service does nothing. OpenRC reads a service as crashed when the process its pidfile names isn't running, so a daemon still running under a stale pidfile gets a second copy beside it.
• restart_on (optional): resource ids whose change triggers a restart of this service: systemctl try-restart on systemd, rc-service --ifstarted <svc> restart on OpenRC.
• reload_on (optional): resource ids whose change triggers a reload of this service. That is try-reload-or-restart on systemd and rc-service --ifstarted <svc> reload on OpenRC, where a service that can't reload fails the step.

A trigger acts only on a running service. A service that isn't running is left as it is, and starts on the new state when something starts it, so a unit file written on a first deploy restarts nothing before its binary is there. A service converged but for its trigger runs the trigger alone (after systemd's daemon-reload), never its enable or start again. A trigger on a service declared running: false (its restart_on / reload_on, or a file's triggers naming it) is a structural error: it could never act.

The target must declare a service_manager. The structural gate rejects, in every command, a config with service intent on a target that declares none, and doesn't guess systemctl on a host that may run OpenRC. Service intent is any of:

• a service resource;
• a file with triggers;
• deploy.service.

A declared manager with no backend (launchd) parses. Its services detect as undetermined, and their verbs plan as notes, not commands.

Pending triggers

A trigger fires when one of its sources changes in the current plan. On its own, a failed reload would be lost: the next plan reads the source as converged (its bytes match) and the service as running (on the old config).

So Zap keeps a record on the target. Before the first source of a triggered service runs, apply writes a marker to /var/lib/zap/pending/<service> holding the owed action. It removes the marker only after the service's own change completes. If the reload fails, or the run dies anywhere in between, the marker stays, and the next plan fires the action again:

A pending restart outranks a reload fired this run. The markers are read live, as root, on every plan for a config that declares a trigger, and a marker for a service the config doesn't manage is reported as a warning. A marker directory that can't be read fails the plan rather than reading as owing nothing. Zap gives /var/lib/zap and pending/ mode 755 and each marker 644, whatever the umask. The service's change clears its marker whether or not the service was running: a stopped service owes nothing, since it starts on the new state.

Zap keeps its state in /var/lib/zap, and refuses the declarations that would manage it. A structural error is any resource whose path is at or under it as written (. and .. taken as written), a home-rooted path with a .. component, a link whose target is /var/lib/zap, under it, or a directory above it (/, /var, /var/lib, so no path below the link leads there), a link placed at one of those directories above it (which it would replace), and a deploy.path there. A path or link target that reaches it only once a reference or ~ resolves holds the resource in detection and is refused by the wetrun. What isn't a declared path isn't checked: the commands a script, pipeline, installer, or build runs can write anywhere, and a symbolic link already on the target that leads into /var/lib/zap is followed like any other directory link.

The record is written first, so the guarantee is at-least-once. A run that fails after the marker but before any source changed fires one reload or restart it didn't strictly need. It never drops one it did.

A held service, whether detection can't read it or it is held behind another, gets no marker, so each source whose change would trigger it is held too, with the reason "would restart (or reload) the service, which is held". Running the source alone would owe a restart nothing records. The next plan that can run the service plans both.

database

A PostgreSQL database and its owning role. Zap creates the role and database idempotently, sets the database's owner back to the role when it has drifted, and manages the declared pg_hba.conf auth rules. It never restarts PostgreSQL, so the target needs no service_manager for it.

• engine (required): 'postgresql'.
• database_name (required): the database to create.
• username (required): the role to create, which owns the database.
• auth (optional): the pg_hba.conf rules. See Database auth.

Both names, and each auth.hosts entry, are written into a pg_hba.conf line as they are, so none may hold whitespace, #, ", ,, or a control character. A name doesn't begin with +, @, /, or -, a database isn't named with a word pg_hba.conf reads as a keyword in that column (all, sameuser, samerole, samegroup, replication), and a role isn't named all. The rule holds for the value a reference resolves to as well: one that breaks it holds the resource.

Both identifiers are taken literally and never shell-expanded. They accept references, resolved on the operator's machine. A dev config that wants "the role matching the OS user" on every machine declares username: zap.env('USER'). A shell-style username: '$USER' would never resolve.

Database auth

• hosts (required in auth): the client addresses a rule admits, each an IP address with its prefix length ('127.0.0.1/32', '::1/128'), at least one. A keyword (all, samehost, samenet) or a host name is refused, as written and as a reference resolves. A database with no auth writes no rule.
• method (optional): the pg_hba auth method of those rules (default 'scram-sha-256'). A rule Zap writes is a plain TCP host line with no options, so a method that can't work on one is refused: 'trust', since a trusted TCP rule lets any account on the machine, any service among them, connect as the role with no credential; 'peer', which PostgreSQL accepts only on a Unix-socket (local) line, the route a database with no auth already takes; 'cert', accepted only on a hostssl line; 'ldap' and 'radius', which need options Zap doesn't write; and 'sspi' and 'bsd', which PostgreSQL doesn't build on Linux.

With no auth, the role is reached the way the stock pg_hba.conf allows a local account: over the Unix socket, by the OS account of the same name (local all all peer on Debian, and on Alpine once alpine_postgres_setup has initialized the cluster). A service running as that account connects with postgres://<role>@/<database>?host=/run/postgresql and needs no password.

Each rule is a host line in the pg_hba.conf the server reports. A missing rule is inserted once, above the first host-type record (indented ones included), or appended when the file has none, so it takes precedence over the rules already there. Detection only asks whether each rule's line is present, anywhere in the file: the rest of the file isn't judged. A rule already there below a broader one that matches first (a host all all 0.0.0.0/0 trust, say) reads present, though the earlier line decides those connections, and a trust line, a duplicate, or any other rule of the file's own is neither reported nor removed. Review a pg_hba.conf Zap didn't write. The rewrite runs as the postgres account, which must own the file and be able to write its directory, as a stock install has it; a pg_hba.conf owned by anyone else is left alone and the step fails saying so. The file is replaced by rename, keeping its group and mode; if the rewritten copy isn't the original plus that one line, Zap leaves the file alone and the step fails. A rule Zap added is put in force by reloading the server's configuration (SELECT pg_reload_conf(), as postgres); a rule already there reloads nothing. Before the reload the step reads pg_hba_file_rules (PostgreSQL 10 or later; on an older server the step fails), which parses the file on disk, and fails without reloading if any line of it has an error. The reload is only a signal, so after it the step waits, up to 30 seconds, for pg_conf_load_time() to move, read from a new connection each second; once it moves, every new connection, a dependent's included, sees the rule. A postgresql.conf the server can't parse keeps that time from moving, so the step fails then too, saying so. A reload the server doesn't confirm, a file it can't parse, or a load time that doesn't move fails the step with the rule in the file, and the next run's plan reads it present and reloads nothing: fix the file the server can't parse, then reload by hand (sudo -u postgres psql -c 'SELECT pg_reload_conf()') once the server can. Zap reads only that one file: a rule inside an included file isn't seen, and an include above the first host line still orders ahead of Zap's rule.

swap

A swap file, recorded in /etc/fstab.

• size (required): the swap size, such as '2G', used when the file is created. It is not compared afterwards: resizing means removing the file by hand first.
• path (optional): the swap file path (default /swapfile): absolute, with no whitespace, since it is a field of an /etc/fstab line. It is not ~-expanded and takes no reference.

A swap file that drifted is repaired part by part: an active one isn't allocated, formatted, or enabled again, and one already in /etc/fstab isn't listed again, so an active swap file missing from /etc/fstab is only listed. One that isn't active is allocated again before it is formatted, so a short file a full disk left behind is made whole.

Before the file is allocated, formatted, and enabled, as root, its path is checked: a symbolic link there is refused, since mkswap would format whatever it points at, and so is any directory on the way to it, up to /, as declared and as it resolves, that root doesn't own or that a group or other account can write, where someone else could put a link at the path, or re-point a directory above it, between the check and the format. The refusal names the path, the directory, and the reason, and nothing is made.

Adding the entry rewrites /etc/fstab whole: the table as it reads plus the entry, installed by rename with the table's mode kept and root as its owner. A table the connecting user can't read fails the step with nothing written, and so does one with a POSIX access list (ACL), whose mode can't be kept (file); remove the list (setfacl -b /etc/fstab) to let Zap add the entry. An edit someone else makes between the read and the rename is lost, and a symlinked /etc/fstab is replaced by a regular file.

firewall

Firewall configuration: default incoming and outgoing policies plus a list of allow rules. There are two backends, ufw (Debian/Ubuntu) and nftables (the native backend on Alpine).

Allow rules are additive. Zap asserts that each declared rule is present and that the default policies match. A rule added out of band is neither detected nor removed.

• backend (required): 'ufw' or 'nftables'.
• allow (required): the allow rules. See Allow rules.
• default_incoming (optional): the default incoming policy, 'allow', 'deny', or 'reject' (default 'deny').
• default_outgoing (optional): the default outgoing policy, same values (default 'allow').

Allow rules

Each entry in allow is either a named ufw profile (a string, such as 'OpenSSH', which takes no reference and can't begin with -) or a port and protocol object:

• port (required): the port number, 1 to 65535.
• proto (optional): 'tcp' (default), 'udp', or 'any'.

Backends

ufw applies ufw default … policies and a ufw allow per rule, then ufw --force enable. Named application profiles ('OpenSSH', 'Nginx Full') and port rules both work.

nftables installs a single declarative inet filter ruleset at /etc/nftables.nft (whole, mode 600) and loads it with nft -f.

• The ruleset accepts established connections and loopback before the default-drop policy, so applying it never severs the live SSH session.
• It is scoped to its own table. It does not flush ruleset, so other tables such as fail2ban's are untouched.
• nftables has no application profiles. Use port rules only; a named profile is a config error.
• Boot persistence is the separate nftables service. Declare a service resource (service: 'nftables', enabled: true) alongside the firewall, which loads the same /etc/nftables.nft at boot. This companion service is required: the structural gate rejects an nftables firewall with no enabled service: 'nftables' in the same config, because a firewall that silently vanishes on reboot is a security regression. The alpine_web_firewall recipe bundles both.

For both backends, a status probe that fails (exits nonzero), or an inactive ufw, detects as absent (needs setting up) rather than holding; a probe that times out, or whose batch fails, still holds. This is the fresh-host case, where the probe runs before the same config installs ufw or nftables. See detection.md.

verify

Assertions checked at detection and again on a wetrun. A verify resource executes nothing of its own. It checks that conditions hold and, if any assertion fails, becomes a pending change; on a wetrun its assertions run again at its place in the dependency order, and one still failing fails the run there: changes ordered before it have already run, and the rest are skipped. Use it as a guard rail, ordered with depends_on ("this token file must exist before we proceed"). Like every resource, it is checked again on every pass.

• assertions (required): the assertions to check. All must pass.

Assertions

Each assertion is discriminated on type.

path_exists: assert a path exists, optionally with a required type, mode, owner, or non-emptiness.

• type (required): 'path_exists'.
• path (required): the absolute path to check, as written: it takes no reference, and a ~ or relative path is rejected.
• file_type (optional): the required type, 'file' or 'directory'.
• mode (optional): the required octal mode; 0644 and 644 are the same.
• owner (optional): the required owner, as a user name and not a numeric uid. A link at path is followed: the type, mode and owner are its target's.
• not_empty (optional): whether the path's size must be above zero (test -s, default false). A directory's size depends on its filesystem, so this doesn't reliably check that a directory has entries.

command: assert a command exits 0, optionally with a substring in its stdout.

• type (required): 'command'.
• run (required): the command to run.
• expect (optional): a substring that must appear in stdout.

pipeline

An ordered, imperative workflow of steps run sequentially in declared order. Reach for it when a procedure really is multi-step and doesn't map onto a single declarative resource.

A pipeline has no state to converge to. So it runs on every wetrun, a dry run of a config that declares one always has a pending change (exit 2), and zap status always reads it absent.

• steps (required): the pipeline steps. See Steps.

Steps

• id (required): an id for the step, unique within the pipeline. Two steps with one id are rejected by the structural gate.
• run (required): the command this step runs.
• name (optional): a display name for the step. A plan lists each step by its id, then its name, above the steps' run commands.

Steps run in declared order. Concurrent execution and dependencies between steps aren't supported, so a pipeline-level env, a max_concurrency above 1, or a step's cwd, env, or depends_on is rejected by the structural gate and not silently ignored. Order steps by position, and inline any per-step environment or working directory into the step's run (cd … && FOO=bar cmd).

build

Builds a tool from a fetched source archive and installs it, for upstreams that ship source and no prebuilt binary (zig, ghostty). The source is content-addressed and provenance-pinned: Zap records which exact source produced the installed artifact, so a moved upstream is detected as drift and not silently accepted. It is unrelated to deploy.build, the local command zap deploy runs before packaging (deploy.md).

Fields

• source (required): where the source comes from and how its integrity is verified. See source.
• run (required): the build command, run in the extracted source directory, such as zig build -p $HOME/.local. It runs as the connecting user, unprivileged, so an output under a root-owned directory needs the command's own sudo.
• output (required): a path that exists if and only if the build is installed. It is the detection probe.
• cwd (optional): the working directory for run, taken as written (no reference, no ~ expansion): an absolute path, or a path relative to the extracted source directory, which is the default.
• env (optional): extra environment for the whole of run, on a remote target as on a local one. Values resolve references and can hold any byte but U+FDD0, U+FDD1, and NUL, so env is how a build takes a secret. A name can't begin with __zap_.

The build toolchain itself (zig, GTK dev packages, and so on) is not this resource's job. Declare it with sibling package or installer resources and order with depends_on.

source

The source is a remote archive:

• type (required): 'remote'.
• url (required): the fetch location (URLs). It may carry a reference, resolved when Zap fetches; how the lock addresses it is in lock.md.
• extract (optional): how the archive is unpacked. {type: 'none'} is the default; the other form is {type: 'tar.xz' | 'tar.gz', strip_components?: N}. strip_components lives inside the tar form (beside none it is rejected), and strips leading path components: 1 flattens a tarball's single top directory.
• auth (optional): a bearer credential for a private byte host, resolved at the IO boundary and never hashed.
• verify (optional): upstream-signature verification. See Verification.
• blake3 (optional): a vendored source pin. Present, the source pins itself; absent, it tracks through zap.lock, where zap update <id> advances it; a tracked source with no lock entry, or with an entry gone stale (the declaration changed since it was minted), holds the build (undetermined, exit 1) in the read-only commands. See lock.md.

Verification

When source.verify is set, the fetched archive is verified before it is cached or pinned, so a tampered fetch can never become a build. The supported scheme is minisign:

• scheme (required): 'minisign'.
• public_key (required): the pinned minisign public key, the 56 base64 characters beginning RW on the key line of a .pub file. Any other shape fails at config eval.
• signature_url (optional): an explicit signature URL, which may carry a reference. It defaults to the source URL with .minisig appended to its path, before any query or fragment. The source's auth goes with the signature request only when the signature URL has the source's origin (scheme, host, and port); a signature on another origin is fetched without it.

Verification shells out to the minisign binary: the one ZAP_MINISIGN names, an absolute path, else the first in an absolute directory on PATH. Its exit status is the verdict that lets the bytes be cached and pinned, so Zap refuses a minisign inside a node_modules directory (an npm script's PATH leads with node_modules/.bin, which any installed package can fill), and one where the binary, or any directory from where it resolves up to / (and the same for the directory it was found in and for each link on the way), is writable by a group or others, or owned by an account other than root and you. Once those directories are trusted, only root or you could swap the binary between the check and the run. A refusal or a failed verification names the binary's path. Zap adds no crypto dependency of its own and uses the upstream's trust mechanism.

A good signature says the key's holder signed these bytes, not that they are the version the URL names: any archive the same key signed verifies, an older release included. The pin is what fixes the version, and a tracked pin is minted from whatever verified archive the URL served at that fetch, so read the pin change in the lock diff as you would a version bump.

It runs once, at the fetch on a cache miss. A cache hit hashes the bytes against the pin again. Bytes that hash to the pin are the pinned bytes, however they reached the cache: a tracked pin is only ever minted from a verified fetch, and a vendored pin is your own statement of exactly which bytes to trust.

Detection

After a successful build Zap writes a provenance sidecar, <output>.zap-build: a blake3 over the source pin and the build's extract, run, cwd, and env as declared. Detection compares it with the desired provenance, so a moved upstream or a changed build rebuilds (detection.md).

See also

• concepts.md: the model and the verdicts.
• configs.md: writing a config; ordering, triggers, the gates.
• detection.md: how each resource type's current state is read.
• lock.md: pins, zap.lock, and the sentinel and sidecar files.
• env.md: references, the env file, secrets.
• deploy.md: the zap deploy release mechanism.
• recipes.md: the shipped config fragments.

Reusable config fragments shipped with Zap: the standard pieces of a hardened Linux server, so a config imports them instead of pasting an nginx block or a systemd unit that drifts from the next one. Each is a pure function or a constant (no I/O; it runs inside the config sandbox) that gives a string to put in a file, or a payload to spread into a resource.

Import each by its full module path. Resolving the imports: install.md. The generated API reference on the site documents every option; this page is the map.

Host families

Recipes that differ by distro come in symmetric debian_* / alpine_* pairs over a shared neutral core, so a config imports one family per machine: a Debian config can't pick up an OpenRC service by accident, because the names differ. The neutral recipes, identical on every distro, keep bare names. A few carry the family in the artifact's own name (hardened_systemd_unit, hardened_openrc_service, postgres_apt_repo) rather than a prefix.

Neutral

Debian and Ubuntu (apt, systemd, ufw)

Alpine (apk, OpenRC, nftables)

Writing your own

A recipe is an ordinary pure function, so a config can define its own. One that needs a reference of its own (a default domain, say) makes it with env_ref('NAME') from @fuzdev/zap/env_ref.ts, which returns what zap.env('NAME') does. A value a caller passes in may be a reference too, so a recipe splices values into strings and never inspects them beyond whether one carries a reference: one that validates or slices an option fails on a reference. A value that ends up in a file's inline content can't be a reference; a recipe that takes a per-environment value emits a {{placeholder}} for it and returns the whole template content, the value in vars and its kind in kinds.

Design rules

The shipped recipes follow these, and they keep your own composable too.

• One value, one home. Anything two recipes must agree on (a rate-limit zone name, a token path, the ACME webroot) is one constant or flows through one recipe's option. The nginx rate-limit zone is the precedent: rate_limit_zone defines it and nginx_site_core references it through one exported constant, RATE_LIMIT_ZONE, so the two can't drift.
• A neutral recipe never defaults a distro-divergent value. A default that differs by family either forces the debian_* / alpine_* split or becomes a required option. The neutral recipes that still carry a Debian default are flagged in the catalog: fail2ban_jail's sshd_logpath and banaction, and deno_install's target.
• Big divergence, two functions. A one-verb or one-path difference shares a *_core with thin wrappers (the nginx catch-all, the sshd service). A whole-artifact difference (a systemd unit versus an OpenRC script) is two functions sharing only an options shape.
• Pure. No fetch, no file reads beyond imports, no clock. A recipe's output depends on its arguments alone, so the plan does too.
• Every value a shell reads is one single-quoted word. A recipe that splices a value into a command or a script quotes it with single_quote (@fuzdev/zap/shell.ts), whether the value is a reference or a literal, so no value can change what the command runs. An option that is shell words by design (psql_args, command_args, a stop or reload command) says so in its doc. A value a second shell reads again, as OpenRC's start line does, is held to a plain-word pattern and refused otherwise. An env file has two readers, systemd's EnvironmentFile= and, on Alpine, the init script's reader, so fuz_app_env_base and fuz_app_trusted_proxies single-quote their values, and refuse one holding a ' or a line break, which systemd reads differently.
• A recipe that owns a template owns its kinds. A placeholder's value is substituted as text at apply time, so a ' in '{{cookie_keys}}' would end the quoting (systemd would read another value, the OpenRC service would refuse to start), and a ; or a } in a value placed in an nginx directive would end the directive. The site and env recipes return the whole template content, each variable with the kind of the place it lands (resources.md), so a caller passes values; used whole, the content carries its kinds, and overriding kinds or rebuilding the content drops them. fuz_app_env_base's extra adds the caller's own lines, variables, and kinds, and can't name the base's; the site recipes take no variables but domain and port, and add a redirect_domain_<i> of their own for each redirect_domains reference.
• A user that sudo -u runs a command as is written out. sudo -u reads a name starting with # as a uid (#0 is root), so a recipe that runs a command as a declared user refuses an empty one, one starting with #, and a reference, whose value it can't see (sudo_as_user in @fuzdev/zap/shell.ts).
• A binary a service user owns runs as that user. deno_install into a user's home runs its check and its closing --version as that user, never as the connecting user: the account could replace the binary, and the connecting user has sudo.

The certbot DNS preflight

Let's Encrypt limits failed validations, and a fresh host whose DNS isn't pointed at it yet fails every one. So each certbot script that leads to a CA request — the --standalone issuance and the webroot switch (a re-issue, and a new name on the cert is a request for it) — first checks, on the target, that every name the certificate covers (domain and each of extra_domains) resolves only to expected_addresses. The checks are unchanged.

• Each name is resolved with getent ahosts and getent hosts, which both families have (glibc's on Debian, musl-utils on Alpine). A name ahosts can't resolve refuses, and so do lookups that print no address and any address either prints outside the expected set: the CA validates whichever A or AAAA it picks, so an undeclared AAAA refuses too.
• Both lookups, because ahosts asks with AI_ADDRCONFIG: on a host with IPv6 disabled, glibc and musl both leave the AAAA records out of it, and getent hosts still prints them. glibc prints every one, musl only the first, so on a musl host with IPv6 disabled a name with several AAAA, the first of them declared, passes with the others unseen.
• expected_addresses defaults to a reference to DEPLOY_HOST, the target's host. Each value is an IP literal or a reference resolving to one; the target checks it when the script runs and refuses anything else, asking for expected_addresses. A DEPLOY_HOST holding a host name rather than an IP literal refuses until expected_addresses is declared; declare the set too when the names carry an AAAA. An IPv6 address is compared as lowercase text: write it as getent prints it, compressed.
• The issuance stops nginx to free port 80 inside the same run, after the preflight passes and before certbot runs, so the stop runs only once every name the request covers has passed, and a refusal leaves nginx running. If certbot then fails, nginx stays stopped; the resources after the certificate, nginx's own service among them, are skipped until a later apply's request succeeds.
• A refusal exits nonzero before nginx is stopped or certbot runs, with each reason on stderr:

The preflight reads the target's resolver, not Let's Encrypt's, so it can be wrong in both directions. An /etc/hosts line, a split-horizon answer, or a cached one can pass while public DNS doesn't point at the host yet, and the request then fails validation as it would have without the preflight; the same sources can refuse while public DNS is right. getent reads /etc/hosts first, so a name the host maps to a loopback address there refuses, among them the 127.0.1.1 <name> line a Debian install writes for the host's own name when that name is the domain. Remove the line, or give the host a name that isn't the domain; a tool that manages /etc/hosts may write the line back.

A script has no lock entry and is done once its check passes, so changing its run re-runs nothing: a host whose certificate is issued and pinned to webroot never runs the preflight, and one whose check fails, for a name newly added to the cert, runs it before the re-issue.

Env files under OpenRC

OpenRC has no EnvironmentFile=, and the init script runs as root, so hardened_openrc_service never sources env_file. The script carries a reader that takes each line as data. start_pre runs it as the service user (su -s /bin/sh), under a 10-second timeout, to check every line and assign nothing. The check writes to a file in a private directory of root's under /run (mktemp -d), never to a pipe, so a process of the service user's that outlives the timeout can't hold the start open, and the service user can't fill the directory beforehand to stop the start, as it could /tmp. Root reads only the first 4 KiB, which bounds what it reads, not what a lingering writer can grow the file to; and the daemon's own process, already dropped to the service user, runs it again to export the values before it execs the command. Nothing in the file is run or expanded, root never parses it, and nothing in it reaches root's environment. The file must be readable by the service user: one it can't read (a root-owned 600 file), a line outside the format, or a file that isn't read in time (a FIFO) refuses the start, naming the user or the line. The check needs su and timeout on the target, which BusyBox gives Alpine.

The format is a subset of what systemd reads, so a file in it gives the daemon the same environment under both:

• a blank line, or one whose first non-blank character is # or ;, is skipped;
• every other line is NAME=VALUE, the name [A-Za-z_][A-Za-z0-9_]* with nothing before it, and not beginning _zap_;
• a value that starts with ' ends the line with its closing ' and holds no other; everything between is literal;
• any other value is literal as written, $, # and inner blanks included, and may not start or end with a blank, start with ", or hold a \;
• NAME= sets the empty string, and a later line for a name wins.

Any other line refuses the start, naming its line number, where systemd would skip it (no =, an invalid name), strip blanks around the name or value, read double quotes, backslash escapes or a continued line, or let a quoted value span lines. A carriage return anywhere refuses its line.

Recipes for fuz_app servers

fuz_app_env_base, fuz_app_trusted_proxies, and fuz_app_bootstrap_token are specific to servers built on fuz_app: its environment layout and its first-admin bootstrap. Everything else on this page is generic: an nginx site serving a static build with an /api proxy, a hardened service, a firewall that allows 22, 80, and 443.

Where a config acts, how Zap gets there, and what the target needs. What your own machine needs is in install.md.

The target

A config declares exactly one target with zap.target({…}): your own machine, or a host over SSH.

A local target with any remote field is rejected at parse. A remote path that uses ~ or $HOME with no home declared is undetermined: Zap never guesses a remote home.

host, user, and bootstrap_user are connection context, not desired state: they are left out of every resource's hash, so changing the connecting user never reads as a config change. The plan does name them: plan_hash covers the host and the connecting user the target resolves to, and on a local target the user Zap runs as and its HOME. A target that declares no user leaves the choice to ssh, and the plan prints user: (none — ssh chooses) instead of a name.

How Zap reaches a remote host

Your authority to act on a host is SSH. Zap shells out to the ssh and scp on your machine with your keys and your ~/.ssh/config, so anything that works for ssh user@host works for Zap: agents, jump hosts, per-host keys. The options Zap sets:

ssh keeps the first value it reads for an option, and the command line comes before every config file, so these hold over your ~/.ssh/config. A changed key is refused only when the first one was recorded, so before it connects to a host Zap reads your effective config once (ssh -G, with the same options) and refuses, naming the setting, when every UserKnownHostsFile is /dev/null.

There is no agent on the host, no daemon, no server, and no shared secret. A pass authenticates once: detection runs as one or two batched shell scripts, and the login batch waits for the root batch's connection to be up rather than opening a second one.

The bootstrap user

A config that hardens SSH often changes the connecting user partway through bring-up: the host's stock account creates a dedicated service user, then SSH hardening locks the stock account out. Declare both:

Pass --bootstrap on the first run to connect as bootstrap_user, and omit it afterward. It never engages on its own, so a connectivity failure can't silently switch identity. The first bring-up is zap apply --bootstrap, then zap apply --bootstrap --wetrun: it provisions and hardens as the stock account, which the hardening then locks out, and every later command connects as the service user. A --bootstrap run is its own plan, so preview it with zap apply --bootstrap; a preview made as the service user doesn't bind it.

Keep both variables in one env file, set from the start and kept set: a host or connecting user that resolves to nothing stops every command before it connects, and an unset reference in the other user makes a dry run unverifiable and stops a wetrun.

What the target needs

Zap needs sudo on the target even when you connect as root: privileged commands carry an explicit sudo so one plan runs under either user. A fresh Debian cloud image usually has it; a minimal Alpine needs apk add sudo by hand or through a bootstrap user that already has it.

Two-tier privilege escalation

Which commands run as root is decided by what they are, not by who you are.

1. Intrinsically privileged commands carry sudo. apt-get install, systemctl, rc-service, ufw, nft, useradd, and the like are baked into the plan with an explicit sudo prefix. The plan reads the same for a root login and a sudoer.
2. Filesystem operations run under sudo over SSH, and escalate per operation locally. Over SSH the connecting user isn't assumed to own what Zap manages, so writing a file, making a directory, placing a fetched file, or creating a symlink goes through sudo directly. On a local target each is tried natively first and falls back to a sudo shell op only when denied, so a config that touches only your own files never invokes sudo. A file's mode and owner are part of its write, and a directory's are set the same way: natively, else by one elevated command that refuses a symlink at the path. A file keeps the owner and group it leaves unset, so locally a file another account owns, or a new one in a directory another account owns, is written under sudo; so are directories made under another account's, which take its owner. Anywhere below a directory with its sticky bit set or that every account may write, such as /tmp, nothing is kept or taken and your own write stands. Local reads and existence checks follow the same rule: a root-owned file is read under sudo rather than misread as absent.

A user's authorized_keys is written as that user (sudo -u <user>), a copy_from source is read as the source user, and a database's SQL runs as postgres (sudo -u postgres), so the connecting user's sudo rule has to allow running as them. root and an unrestricted sudoer do. What ran as root is in the host's sudo I/O log (security.md).

The exception is a build: its source is extracted into a private temporary directory and the build command runs unprivileged, as the connecting user. A root-owned scratch dir would be unrepairable, and a build shouldn't need root.

Local sudo

On a local target, before a root batch runs, Zap checks that sudo will work without a prompt (sudo -n). If it won't, Zap runs sudo -v on your terminal, with no deadline, so you can enter a password before anything is timed. The batch itself then runs under sudo -n. If sudo won't authenticate, every resource that needed root is held with the reason sudo authentication failed.

An operator command (a script's check, a verify assertion) runs without a terminal, locally as over SSH. A sudo inside it that needs a password fails at once and the check reads as failed. Give such a command a NOPASSWD rule, or keep sudo out of checks.

Detection privilege

Every detection read runs under a declared privilege: login (the connecting user, unprivileged), root (root on every connection), or elevated (root over SSH; locally, you first and sudo for a read that failed). Which reads run in which lane, and how batches are framed, killed, and timed out: detection.md.

How values that vary per machine, or must stay secret, reach a config without being written into it. The sandbox that makes this necessary is described in configs.md.

References

A config never reads the environment. It writes a reference instead, with zap.env('NAME'):

The reference stays inert in the declaration and in the plan. Zap resolves it from the operator environment when it acts, in these fields only:

A reference where none is taken fails when Zap reads the config, naming the resource, the field, and what to use instead:

A reference in a command is replaced as text: put it inside single quotes, or hand the command an arbitrary value through env, which is quoted after it resolves. The values Zap refuses in a command, and why: security.md. A template's vars value can't hold a line break, which would add a line to the file (resources.md). An env-file value can't hold a NUL. A value holding U+FDD0 or U+FDD1 is refused wherever it would be substituted, an env value included: a value is substituted once and can't carry a reference of its own.

zap.env('NAME') returns a string, so a reference composes like one:

That path has a reference in it, and a recipe can splice a value it was handed without knowing whether it is one. A recipe makes its own with env_ref('NAME'), imported from @fuzdev/zap/env_ref.ts. The name must be an environment variable name (letters, digits, and _, not starting with a digit).

While the config is evaluated that string is opaque. It holds a marker, not the value, so interpolating and concatenating it are the only things to do with it:

• slicing it, splitting it, or changing its case damages the marker, and the config fails to evaluate, naming the field;
• a regular-expression replace that strips non-word characters, or encodeURIComponent, silently turns it into ordinary text;
• code that inspects a value (its length, its first character) sees the marker.

A reference is the string zap.env or env_ref returns. Text that merely looks like one is text: $$, $$NAME$$, ${NAME}, and {env:NAME} in a command or a file are what they say. The two characters the marker is built from (U+FDD0 and U+FDD1) can't appear in a config's own strings; content that holds them comes from a source or remote file.

Previews and messages show a reference as {env:NAME}:

What each reference a plan uses resolves to is printed once, in a references: block under the target, and is part of the plan and its hash: a plain reference's value, or for a secret only that it is one. So a value you wouldn't want in a preview or a CI log belongs under a name Zap reads as a secret, or in zap.mask.

Text in a command can spell {env:NAME} too. Where it matters which it is, the target: line and a template's vars print the exact form, {"$env":"NAME"}, and plan_hash covers it.

A command, a path, or an SSH destination that still holds an unresolved reference is never run, touched, or connected to: Zap refuses first.

Target-categorized resolution

Two kinds of placeholder resolve against two different machines:

So a resource's part of the plan doesn't depend on the environment or the target's home, and a remote path that needs a home with none declared is undetermined rather than guessed. The home itself is part of the plan beside it: a remote one as the declared target's home, your own as the local plan's home: line. A resource's resolved values reach the hashes of the last-run report and, for a tracked source, the lock.

The target's host, user, and bootstrap_user resolve from references too; they are connection context (targets.md).

The env file

Every config command accepts --env-file <path>, a file of NAME=VALUE lines loaded into the operator environment before anything resolves. A name set in both the file and your shell takes the file's value:

One explicit file, no auto-discovery, no .env plus .env.<mode> merging. Keep env files out of version control and commit a .example with the names. Name it for what it is, say zap.env or zap.production.env; don't reuse the name of an env file your app reads on the host, which deploy.shared may be linking into releases.

The format is a strict subset of dotenv: Zap reads only lines the common loaders agree on, and a line it doesn't understand is an error instead of a guess. (A loader that interpolates still reads a $ its own way.)

A name is letters, digits, and _, not starting with a digit. There is no interpolation ($OTHER is text) and no value spanning lines. These don't load: a line with no =, a name that isn't one (export counts only before a space), a name assigned twice, a quote left open or followed by anything but a comment, an unquoted value that begins with # or holds one after whitespace (quote the value, or move the comment to its own line), an unquoted value ending in a backslash or holding a control character other than a tab, or a Unicode line or paragraph separator (U+2028, U+2029), and a NUL in an assignment. Whitespace around the = is trimmed, and a byte-order mark at the start is skipped. The error names the file, the line, and the name when the line has one, and never any part of a value or of the line.

Zap warns, once per command, about an env file its group or everyone can write (whoever can rewrite it chooses the host a deploy goes to), and about one they can read when it holds a secret by its name or the form of its value (the file is read before the config, so a variable only mask() lists doesn't count), saying which. chmod 600 answers both.

Unset references

A reference with no value, or an empty one, is handled by what the command does:

• A wetrun (apply or deploy) refuses to start. Every referenced variable must be set and non-empty, or the run fails before any side effect. An empty DATABASE_URL would otherwise be written into a .env file as nothing.
• A comparing dry run (plan, apply, detect) is unverifiable. Detection resolves references into the desired side of its comparison, so an unset one makes the answer unsound in both directions: it can hide drift (the target already holds the empty value) and invent it (the target holds the real one). The command leads with the banner and exits 1:UNVERIFIABLE — 2 referenced variable(s) are unset or empty, so this comparison cannot be trusted: DATABASE_URL, SMTP_PASSWORD an unset reference resolves to an empty string, which can both hide real drift and invent drift that isn't there. provide them (--env-file or the environment) and re-run.

  The check covers what the comparison resolves: the resources, and the target's host, user, and bootstrap_user. The user the run connects as is held to more: if it resolves to nothing the command stops before it connects (below), since ssh would pick an account of its own. It ignores the deploy block and a fetch credential (the auth token of a remote file or a build source). A database's auth.hosts is part of the comparison and is covered.

• A deploy dry run warns. It compares nothing (the preflight is wetrun-only), so its rendered plan is sound.
• A remote host, or a declared connecting user, that resolves to nothing is an error before any connection. Zap won't SSH to nowhere, or as whichever account ssh picks: plan, detect, apply, and deploy exit 2, naming the variable that is unset or empty.

Unverifiable

The banner above is the unverifiable verdict: the desired side of a comparison couldn't be built. It is the twin of undetermined, where the observed side couldn't be read. Both outrank "converged" and "drifted" in the exit code, because neither claim was established.

Secrets

One rule decides whether a reference is a secret, and everything that treats secrets differently asks it. In order:

1. Where it is used. A reference in a remote file's or a build source's auth is a secret, whatever it is called.
2. What you said. zap.unmask('NAME') makes a reference plain, and zap.mask('NAME') makes it a secret. Unmasking a reference used as an auth credential is an error.
3. Its name, by the rule in Secret names below.
4. The form of its value. A value is a secret, whatever its name, when it holds a URL with a password (postgres://app:…@db/app, so a DATABASE_URL needs no mask), an http or https URL with a user, git+https included (https://<token>@git.example.com/…: HTTP reads a user only as a credential, where ssh://git@… and postgres://app@… name an account), a PEM private key, or an HTTP authorization value (Basic with its encoded user:password, or Bearer with a token of 16 characters or more, alone or as an Authorization: or Proxy-Authorization: header line). A password holding an unencoded ? or # still counts when no @ comes before that character (postgres://app:p#ss@db/app, as libpq reads it: up to the first @ after it), unless what precedes it is all digits, which reads as a port. A password in a query string or in key=value form, and a secret in a URL's path (a webhook's), aren't recognized: name the variable for what it is or zap.mask it.

What is masked is a value Zap resolves: a name no field references registers nothing, so zap.mask doesn't scrub a value a command reads from the target's own environment.

Secret names

Case-insensitive. A name is a secret's when it:

The last word is the part after the final _, passing over a trailing number written apart or glued on (SMTP_PASS_2, DB_PASS2; AUTH0 is a name, not AUTH), a version (DB_PASS_V2), and a qualifier naming an environment or a rotation (PROD, PRODUCTION, STAGING, STAGE, DEV, DEVELOPMENT, TEST, TESTING, QA, UAT, OLD, PREV, PREVIOUS, NEW, NEXT, CURRENT, PRIMARY, SECONDARY), so DB_PASS_PROD is a secret. A plural reads as its word (DB_CREDS, HASH_SALTS), except for AUTH, PRIVATE, SESSION, COOKIE, WEBHOOK, and a word ending in PASS, whose plurals count or switch something (MAX_SESSIONS, MAX_PASSES).

So DB_PASS, GITHUB_PAT, SENTRY_DSN, and SLACK_WEBHOOK_URL are secrets, and AUTH_HOST, PRIVATE_IP, and SESSION_TIMEOUT aren't. A secret-named variable is plain while its value is a switch (true, false, yes, no, on, off, or a single digit, in any case, whitespace around it ignored), so ENABLE_AUTH=true masks nothing.

Masked hosts and review

A target.host, a connecting user, or a deploy.health.domain behind a secret reference makes a plan no review can bind, since its hash would name no one machine or be computed from the secret. zap apply --wetrun and zap deploy --wetrun refuse it before anything runs, a dry run shows the plan under an UNBINDABLE note with no plan_hash and records no preview, and a masked host keeps no last-run report. The message names the cause:

What masking covers

A secret's resolved value is masked out of everything Zap prints or writes: the text report, --json events, warnings, held reasons, drift observations, deploy step output, and errors. Masking is by value. Besides the value itself Zap looks for it trimmed, URL-encoded, JSON-escaped, and single-quoted for a shell as Zap's own commands carry it (each ' written '\''); for each line of 24 characters or more of a value that spans several (a PEM key, with its \n decoded when it was written on one line; the -----BEGIN…----- lines aside); and for the password or token inside a URL or an authorization value, when that is 8 characters or more. A password that also appears elsewhere in its own value (postgres://app:postgres@db/app) is an ordinary word and is masked only as part of the whole. A secret a tool prints in any other form (the address ssh resolved a secret host name to, a URL it rewrote around a short password) is not found. The executor itself never sees a masked string; masking happens where output is consumed. A plan's steps hold only the inert reference; its references: block holds the value of a plain one, with any secret inside that value masked, and for a secret only the fact. Commands reach their shell on stdin, so a resolved value is on no ssh or shell argv (security.md). There is no --show-secrets.

The same rule decides how zap.lock addresses a tracked source: a secret reference is hashed as a fixed token, any other by its value (lock.md).

The last-run report on disk is masked the same way. Each resource's hash takes a secret reference as a fixed [MASKED:NAME] token and masks every registered secret out of any other value, so the report can't be used to test a guess at a secret, and a changed secret value isn't visible to zap status (which says so beside each resource that references one). status rebuilds its masker from its own environment, so for an exact "unchanged since" it needs the same env the run had, secrets included; without one it fails closed to "changed since".

A literal secret in a config is rejected by every command: when a value that is both referenced and resolvable in the current environment also appears written out in the config, the secret gate fails, naming the field and the variable and showing none of the text. It looks for a secret's whole value, 8 characters or more: a shorter one turns up in ordinary text by chance. It is best-effort by design, so it never fails spuriously on a machine that simply lacks the secret.

How Zap pins the evaluator that runs the config and the content it fetches, what zap.lock holds, the commands that move it, and what Zap keeps under ~/.zap. Background: concepts.md.

zap.lock is declared intent, not cached state. It belongs in version control with the config. It records the toolchain pin and the tracked pins; everything else Zap knows about a machine it reads live. The file is the config's name with .lock for its extension, a regular file: a config itself named *.lock is refused (the lock would overwrite it), and so is a symlink where the lock goes, by every read and every write.

The toolchain pin

Every command but zap lock evaluates the config only with the fgro build (Gro's runtime) whose blake3 the lock's toolchain records:

zap lock writes it: it hashes the binary --fgro or ZAP_FGRO names, evaluates the config with that binary, and records its blake3, whatever the lock pinned before. It prints the pin, and the one it replaced when the pin moved:

A moved pin reads pinned fgro <new> (was <old>). Every other command reads the pin before it evaluates:

• no pin, because there is no lock or no zap lock has pinned one in it, refuses the evaluation, exit 2, saying to run zap lock;
• a binary that hashes to something else refuses, exit 2: run zap lock to pin the build you mean to use, or point --fgro at the pinned one. zap update doesn't re-pin it: moving the evaluator is zap lock's alone, so it shows up in the lock's diff by itself;
• zap lock --check reports a binary off its pin as a stale toolchain pin, exit 1, and evaluates nothing, so the entries go unchecked until it is pinned.

A build of fgro is not reproducible across machines, so the pin names one binary: another machine evaluates the config only with a copy of the same bytes, or after its own zap lock, which shows in the lock's diff. An unchanged binary isn't hashed in full on every command (On-disk state).

A "version": 1 lock has no toolchain pin: it reads, and every command refuses until zap lock rewrites it. A "version": 2 lock reads as it is; the next write records it as version 3, which a zap build that reads only version 2 refuses. A lock with a version newer than this zap reads is refused, zap lock included.

Two kinds of fetched content

A file with remote content, a build, whose source archive is fetched and built, and an apt_repo, whose signing key is fetched and installed, take bytes from a URL. Each is pinned by the blake3 of the fetched bytes, so the same declaration always resolves to the same bytes. The pin lives in one of two places:

Vendored is self-contained: a URL and a hash, both in the config, and editing the version means editing the hash. Tracked is the reviewed-upgrade path: bump the version in the config, run zap update, and read the new pin in the lock diff before committing both.

What an entry holds

kind is remote_file, build, or apt_key. blake3 is the pin, 64 lowercase hex with no prefix. config_hash, in the same form, is the blake3 of the resource's declaration with the pin folded in and Zap's resource-hash version ahead of it: the fixed point the entry was minted for. It is how Zap knows an entry is stale: edit what the hash covers (the URL, a strip_components, a build's run, an apt_repo's source) and the recomputed hash no longer matches, so the pin is no longer known to be the pin for this declaration. It leaves out what doesn't change what the pin is the pin for: the resource's identity (id, name, depends_on), an auth credential, and a file's validate command. A new Zap version that changes what the hash covers reads every entry stale once, until zap update.

The hash is unkeyed. It tells a stale entry from a current one, not a genuine entry from a forged one: whoever can edit zap.lock can write a matching config_hash for any pin. The lock is trusted as reviewed input, like the config beside it, so review its diff before committing it.

zap.lock is committed, so the hash must not be a way to test a guess at a secret. A reference that is a secret (by its use as an auth credential, by mask(), by its name, or by the form of its value) is hashed as the fixed token [MASKED:NAME], whatever its value. Consequences:

• Rotating a token in a tracked URL doesn't make the entry stale. The lock verifies on a machine that doesn't have the secret when the entry's URL and path hold no non-secret reference, and when the secret is one by more than the form of its value (a variable secret only by that form has to be set).
• A reference that only looks like a secret (KEYCLOAK_VERSION) loses its staleness signal too. zap lock, zap update, and zap lock --check print a note: naming each reference addressed this way because of its name or the form of its value, with the reason; zap.unmask('NAME') makes a non-secret one count again.
• Whether a reference is a secret can depend on its value: a URL is one only while it holds a password, and a secret-named variable isn't one while it holds a switch (true, 1). An entry minted under one reading and checked under the other never reads current: it reads stale, or unverifiable when the variable is unset and only its value would make it a secret.

Any other reference is hashed by its resolved value, with every secret value the config references anywhere replaced by its token where it occurs inside it, as the output masking replaces it: a DOWNLOAD_URL that carries the value of a SIGNING_SECRET the config also uses is hashed with that part as [MASKED:SIGNING_SECRET], so its entry moves when the rest of the URL does and not when the secret is rotated with it. A secret shorter than 8 characters, or any form of it shorter than that (trimmed, or with its \n decoded), is not replaced: replacing zig wherever it occurs would move unrelated addresses with the secret's value, and so few characters are guessable anyway. A secret can only be replaced while it is set. While a variable the config uses as a secret (by its use as a credential, mask(), or its name) is unset, zap lock and zap update don't mint an entry whose URL or path holds a non-secret reference, and name the variable to set. Such an entry already in the lock is still checked: an address that matches reads current, and only one that changed reads unverifiable, naming the variable, since the change may be the secret's. A value that carries a secret under an ordinary name (a BASE_URL with a token in it) that no secret reference names should be listed in mask(). A build's run, env values, and verify block are hashed as declared: a reference there counts as the reference, whatever its value, so the entry moves only when the declaration does.

Standing

Every command that reads the lock classifies each tracked resource: