zscripts

Overview

zscripts is a suite of 20 PowerShell scripts — roughly 3,400 lines — that operate a production AWS environment running several independent applications. It is the tooling that starts, deploys, backs up, and repairs every project on this site.

The design goal is unusual for a deployment toolchain: it exists to make an AI coding assistant cheaper and more accurate to work with. Each script takes a deterministic, well-understood operation that an agent would otherwise have to reason through step by step — SSH, archive, upload, compose, verify — and reduces it to one word.

It is open source and available on GitHub.

The problem

Working with a coding agent on real infrastructure surfaces a specific inefficiency. Ask it to deploy, and it must first reconstruct the whole procedure from scratch: which directory is the source of truth, what to exclude from the archive, how to reach the host, whether there's disk space, which compose project owns the container, how to confirm the new build actually shipped. That reasoning is spent on orchestration, not on code — and it is re-derived on every session, because the agent starts each conversation with no memory of the last one.

The cost is not only tokens. An agent improvising a multi-step deploy can get a step subtly wrong in a way that is expensive to notice — restoring the wrong environment file, skipping a cache invalidation, or declaring success without verifying the deployed build.

Encoding the procedure once, in a script, fixes both problems at the same time. The steps become deterministic and reviewable, and the agent's context stays focused on the actual engineering work.

The command set

Grouped by what they do:

• Local development — zstart brings up local containers per project (evo.ehs on 8080, Evomedia on 5173, SWAG on 4173), with detached and custom-port modes. zkill tears down processes by port, and zrestart chains the two atomically. zstart_docker handles the Docker Desktop daemon on Windows.
• Deployment — zdeploy ships any of five independent targets to EC2: the Evomedia site, evo.ehs, SWAG Estimates, the shared edge nginx proxy, and the Umami analytics stack. Each has its own compose project and can be deployed without touching the others.
• Backup & sync — zbackup creates timestamped, tagged local snapshots per project; zsync mirrors them to OneDrive incrementally via robocopy; and zbackup_ec2 pulls application and database archives down from the server.
• Diagnostics — zec2 runs TCP and HTTP reachability checks across all projects, zec2online is a fast TCP-only variant, and zrepair audits container routing end-to-end: it verifies the nginx proxy path, checks compose health, and runs a smoke test that loads a page and asserts a 200.
• Shared library — ZHelpers.ps1 (~530 lines) holds the common archive, SSH, and output-formatting logic every script draws on, so behavior stays consistent across the suite.

Inside zdeploy

zdeploy.ps1 is the largest script in the suite (~560 lines) and the clearest illustration of why the approach pays off. A single -evo run performs the full sequence:

• Archive with exclusions — builds a clean zip, skipping node_modules, dist, .git, and nested archive formats at any depth.
• Disk preflight — before uploading anything, prunes stale deploy artifacts, dangling images, and build cache on the instance, truncates oversized container logs, and aborts the deploy if less than 1.5 GB remains free — with the exact growpart / resize2fs remedy in the error message.
• Secrets preservation — backs up the target's .env before the directory is replaced, then restores it afterward, so credentials survive a destructive redeploy.
• Rebuild and cut over — runs docker compose build and up -d for that project only, then reloads the shared edge nginx so it re-resolves the new container's IP — a step that, when skipped, produces intermittent 502s from a stale DNS cache.
• Verification — polls the running container for its build-version.json and compares it against the expected incremented build label, so a silently failed build is caught rather than reported as success.
• Post-deploy cleanup — reclaims the disk consumed by the build, leaving the instance ready for the next deploy.

// Every one of those steps was added because it failed in production at least once first.

Measured impact

Every script prints exactly how much output it produced, captured from a transcript of the run — so the numbers below are measured, not estimated. These are the real per-run figures:

• zdeploy — ~810 tokens on a cached deploy; a full rebuild that reinstalls dependencies spikes to ~35,000
• zstart ~760 · zsync ~770 · zrestart ~720 per run
• zbackup ~440 · zkill ~380 · zrepair ~360 · zec2 ~330 per run

Across an active development day — mostly cached deploys, the occasional full rebuild — that comes to about 26,500 tokens of infrastructure output kept out of the agent's context window. The per-run figures are measured; the daily total applies typical run counts, so it scales with cadence.

The honest framing matters more than a big headline. In dollars the saving is small — a few cents a day at input-token rates. The real return is context: every token of Docker and SSH noise the agent doesn't read is context it keeps for the actual engineering. It would be easy to quote a far larger number by assuming an agent re-derives each deploy from raw commands step by step — a plausible upper bound north of 100,000 tokens a day — but that's an estimate, not a measurement, so the figures here are the ones that were actually recorded.

Live usage

The figures above aren't a one-time benchmark. Every z-script run records its own output volume to a local log, and this section renders the real, accumulating totals — refreshed each time the site is deployed. Each script keeps a fixed color; hover any bar for the detail.

// Passive tracking — no synthetic runs. The numbers grow as the tools get used.

Technology stack

• PowerShell — 20 scripts, ~3,400 lines, with a shared helper module
• OpenSSH — key-based SSH and SCP to the EC2 host
• Docker & Docker Compose — per-project stacks, built and cut over remotely
• AWS EC2 — Ubuntu target host
• robocopy — incremental backup mirroring