ZTD — Zero Trust Dev

Let the agent go YOLO: introducing ZTD

Sun, 14 Jun 2026 00:00:00 +0000

Let the agent go YOLO: introducing ZTD

There’s a moment, a few hours into pairing with a coding agent, when you realize you’ve stopped reading the permission prompts. Allow rm? Allow curl | sh? Allow writing outside the repo? Yes, yes, yes. The dialog that was supposed to keep you safe has become muscle memory — which means it keeps you safe in exactly the way a seatbelt you’ve unbuckled does.

An autonomous agent run

Mon, 01 Jan 0001 00:00:00 +0000

An autonomous agent run

This walkthrough shows the end-to-end shape of ZTD: you initiate, the agent runs unattended in isolation, and the only thing that leaves the VM is a git branch you can review. Every step below is implemented today — ztd cattle composes the whole sequence into one command.

The scenario

You want an agent to attempt a change on myapp without babysitting approval prompts and without any risk to your host.

Commands

Mon, 01 Jan 0001 00:00:00 +0000

Commands

Everything is driven through ztd <verb>. ztd is a Go (Cobra) binary with its runtime assets embedded, so an installed copy needs no source checkout — see Install. The tables below spell it ./ztd, which is the shim in a source checkout: it builds the binary and execs it, pointing it at the live tree so script edits take effect without a rebuild. If you installed ztd, drop the ./ — nothing else differs.

The zero-trust model

Mon, 01 Jan 0001 00:00:00 +0000

The zero-trust model

ZTD’s name is its thesis: the host never implicitly trusts the guest. The guest is treated as compromised-by-default, and ZTD’s job is to guarantee the blast radius of anything that happens inside ends at the VM.

This is what makes it safe to run an agent in “YOLO” mode — no per-action approval prompts. The guardrail is a machine boundary, not a dialog box you’d eventually click through anyway.

Use the Proxmox backend

Mon, 01 Jan 0001 00:00:00 +0000

Use the Proxmox backend

Run the same VM on a remote Proxmox node. The interface is identical to the local backend — only TARGET changes — and your host needs only Docker (no libvirt/qemu).

Validated end-to-end against a real PVE 8 node (boot → SSH → guest Docker + Claude Code). Attribute names track bpg/proxmox; if your provider version differs, expect to adjust a name or two.

You need three things from your Proxmox node: an API token, the names of the node/datastores/bridge ztd should use, and snippets enabled on a datastore. This guide walks through each.

vz — macOS backend (lima)

Mon, 01 Jan 0001 00:00:00 +0000

Plan — the `vz` macOS local backend (lima)

This plan delivers vz, ZTD’s fourth backend and its first for macOS operators: a disposable, isolated Linux guest running locally on Apple’s Virtualization.framework, driven by lima. It is the headline item of Phase 3 (roadmap).

It is delivered as a sequence of phases, each executed as one Opus-orchestrated red/green/verify cycle — see the red-green-verify skill. Do not attempt the whole backend in one pass; lock one behavioral contract per phase.

Your first ZTD VM

Mon, 01 Jan 0001 00:00:00 +0000

Your first ZTD VM

By the end of this tutorial you will have booted an isolated Debian VM with its own Docker daemon, opened a shell inside it, reached a service running in it from your host, and destroyed it cleanly — all driven through the single ./ztd interface. Allow about 15 minutes the first time (provider downloads and the base image are cached afterward).

Before you start

You need a Linux host with:

Architecture

Mon, 01 Jan 0001 00:00:00 +0000

Architecture

Two principles shape ZTD: one interface across every backend, and all orchestration tooling in Docker.

One interface, many backends

 ztd CLI (Go / Cobra) ← the single binary; assets embedded
 │
 ├── host lane ─────────────────────────► vz (macOS)
 │ (bash, on the host) lima / Virtualization.framework
 │
 └── container lane
 │ Taskfile → Terraform root ← runs inside the toolbox container
 │ selects ONE backend module by TARGET
 ┌─────────────┼───────────────────────┐
 kvm-local proxmox ec2
 (libvirt) (bpg/proxmox) (aws provider)
 └─────────────┴───────────────────────┘
 │ all four consume the SAME
 cloud-init (Docker + Node + agent + creds)

The CLI routes each verb down one of two lanes. Most dispatch into the toolbox container, which runs Task and Terraform; the host lane runs bash directly on the host for the verbs that inspect or mutate host state (check, setup, the agent workflow) and for the whole vz backend, which has no usable Terraform provider and drives Apple’s hypervisor from the host.

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Configuration

.ztd/ztd.toml is the ONE file you edit. Every dependency’s config — Terraform variables, the lima instance YAML, cloud-init, the compose env — is generated inside the ztd binary from ztd.toml + built-in defaults. There is no terraform.tfvars, no lima/cloud-init/compose file you ever touch directly. Secrets live separately in .ztd/secrets/*.env (gitignored) — never in ztd.toml, which is meant to be committed.

Scaffold it with:

ztd init

This writes .ztd/ztd.toml with every key commented out — an all-defaults project boots as-is; uncomment only what you want to change.

Forward a port from the VM

Mon, 01 Jan 0001 00:00:00 +0000

Forward a port from the VM

Reach a service running inside the guest from your host’s localhost.

./ztd tunnel -- 8080

This opens an SSH tunnel (-N -L 8080:localhost:8080) to the VM using its ephemeral key. Open http://localhost:8080 to hit the guest service. Stop the tunnel with Ctrl-C.

A different port

The port comes after -- (that’s how Task forwards CLI arguments):

./ztd tunnel -- 5432 # e.g. a Postgres running in the VM

Multiple ports at once

Run one tunnel per port in separate terminals, or open them in the background:

Standalone CLI (install + run anywhere)

Mon, 01 Jan 0001 00:00:00 +0000

Plan — the standalone, installable `ztd` CLI

Turn ztd from “a binary that must run inside a checkout of this repo” into a self-contained CLI you install (Homebrew on macOS, a downloaded binary on Linux) and run from any project directory: brew install ztd → cd my-project → ztd init → ztd up. The binary carries everything it needs; the only config a user ever touches is a single ztd.toml.

Backend cohesion & parity

Mon, 01 Jan 0001 00:00:00 +0000

Plan — backend cohesion & parity

Keep the backends (kvm, proxmox, ec2, vz) sharing one pipeline, branching only where the mechanism genuinely differs — so functionality and testing stay in parity as the set grows. Delivered as red/green/verify phases with an independent review, like the vz backend and standalone CLI plans.

The decision: centralize at the contract, NOT at Terraform

A tempting way to “unify” would be to route vz through Terraform too. Rejected, because it adds branching rather than removing it:

Backends

Mon, 01 Jan 0001 00:00:00 +0000

Backends

A backend is a stable contract — inputs (name, size, image, cloud-init, repo-sync mode, ports) and outputs (a reachable SSH endpoint, instance id). Most backends implement it as a Terraform module; the macOS vz backend implements it host-side with lima instead (no usable Terraform provider, and it drives Virtualization.framework on the host). The same interface drives every backend; only TARGET changes.

Backend	Status	Notes
`kvm` (libvirt)	available	Local Linux host. `dmacvicar/libvirt` 0.9.x; repo live-mounted over virtiofs.
`proxmox` (bpg)	validated	Remote node; cloud-init uploaded as a snippet.
`ec2` (aws)	validated	AWS instance; Debian AMI auto-looked-up; public IP is a real Terraform output. See the EC2 how-to.
`vz` (Apple Virtualization)	available	macOS local via `lima` — host-side (not Terraform); reached over lima’s forwarded SSH port. See the vz how-to.
`hetzner` / `digitalocean` / `vultr`	planned	Same contract.
`verda`	planned	GPU cloud, for GPU agent workloads.

libvirt version pin

The kvm backend pins dmacvicar/libvirt to ~> 0.9.8 — the raw-XML schema (devices, os, memory_backing as attributes), which the module needs for native virtiofs. Note 0.9.x exposes no computed guest IP, so ztd reads it from the libvirt DHCP lease via virsh rather than a Terraform output.

Cattle, not pets

Mon, 01 Jan 0001 00:00:00 +0000

Cattle, not pets

A ZTD VM is cattle: created for a task, run unattended, and destroyed. It is never a pet — a long-lived box you nurture, patch, and fear losing.

The lifecycle

up ─▶ provision ─▶ inject ephemeral key + synced secrets ─▶ sync/clone repo
 ─▶ launch agent (YOLO) ─▶ agent works autonomously
 ─▶ push result branch [+ open MR] ─▶ export audit ─▶ down (manual, v1)

The operator initiates; the run is autonomous. Results are durable because they land in git — a branch or merge request. The VM itself holds nothing of value, so destroying it costs nothing.

Publish the agent's results

Mon, 01 Jan 0001 00:00:00 +0000

Publish the agent’s results (git runs on the host)

The agent works inside an untrusted VM, so the VM never holds forge credentials and never contacts a forge — all forge git is a host operation. Code goes in via the repo sync; results come out through the host.

Why not push from the VM?

A push from the guest would need a forge credential in the guest. Even a short-lived, repo-scoped token is still a credential sitting in an assumed-compromised box — one more thing to leak. Keeping every clone/push on the trusted host removes that surface entirely. The only credential the guest ever holds is the per-VM ephemeral SSH key, which grants nothing on your forge. See The zero-trust model.

Use the vz (macOS) backend

Mon, 01 Jan 0001 00:00:00 +0000

Use the vz (macOS) backend

Run a disposable ZTD guest locally on macOS — on Apple’s Virtualization.framework via lima, instead of KVM (which macOS doesn’t have). This is the vz backend.

vz is the native local backend on macOS, the way kvm is on Linux — so on a Mac, local resolves to vz automatically and a bare ./ztd up (no TARGET) does the right thing. TARGET=vz is just the explicit form; the examples below spell it out for clarity, but you can drop it on macOS.

Host prerequisites

Mon, 01 Jan 0001 00:00:00 +0000

Host prerequisites

ZTD keeps the host footprint minimal: all orchestration tooling (Terraform, providers, Task) runs in the toolbox container. The only thing that can’t be containerized is a hypervisor for a local VM — and that is “the VM” itself.

Backend	Host needs
`kvm` (local Linux)	Docker + libvirt/qemu + `virtiofsd`
`vz` (local macOS)	Docker + Virtualization.framework (via `lima`)
`proxmox` / `ec2` (remote)	Docker only

virtiofsd relays the repo live-share into the guest (it runs as root and reflects the guest uid to the host owner, so files created in the VM are owned by you on the host).

Reset or destroy a VM

Mon, 01 Jan 0001 00:00:00 +0000

Reset or destroy a VM

Destroy

./ztd down

Removes the VM and its disk. On a remote backend, prefix with the target:

TARGET=proxmox ./ztd down

Reset to a clean state

To throw away a VM and recreate it from clean cloud-init in one step:

./ztd reset

This is down followed by up. Use it when an agent run has left the VM in a state you don’t trust and you want a known-good box again — which, given ZTD’s cattle model, is the normal way to “fix” a VM.

Roadmap

Mon, 01 Jan 0001 00:00:00 +0000

Roadmap

ZTD is pre-v1. Phases 0, 1 and 2 are complete — all four backends are validated end to end and the Go CLI ships as an installable binary. Phase 3 is in progress.

Phase 0 — done

Dockerized Terraform + Taskfile. Backends kvm (local) and proxmox. Shared cloud-init. Single interface via TARGET. Host needs only Docker (plus libvirt/qemu for local).

Phase 1 — done

All three backends — kvm, proxmox, and ec2 — validated end-to-end (./ztd test green on each).

Use the EC2 backend

Mon, 01 Jan 0001 00:00:00 +0000

Use the EC2 (AWS) backend

The ec2 backend runs the disposable VM as an AWS EC2 instance. It reuses the same shared cloud-init, ephemeral SSH key, and host-side agent workflow (mount/fetch/auth/run/audit) as the other backends — only the “where the VM lives” layer differs.

Status: validated end-to-end (TARGET=ec2 ./ztd test green on a real account). EC2 instances cost money per running hour — ztd down terminates them; don’t leave one running.

Pin or override the toolbox image

Mon, 01 Jan 0001 00:00:00 +0000

Pin or override the toolbox image

The kvm, proxmox, and ec2 backends provision through the toolbox container — Terraform, Task, the libvirt client, and the pinned Go toolchain all live there so your host needs only Docker. (The vz backend runs limactl on the host and uses no toolbox at all, so none of this applies to it.)

Which image that container runs is decided by the ztd binary, not by you editing a compose file.

ztd

Mon, 01 Jan 0001 00:00:00 +0000

ztd

Zero Trust Dev — disposable isolated VMs for untrusted dev work

Options

 -h, --help help for ztd

ztd attach

Mon, 01 Jan 0001 00:00:00 +0000

ztd attach

Reattach to the guest agent’s tmux session (bash scripts/run-agent.sh attach)

ztd attach [flags]

Options

 -h, --help help for attach

ztd audit

Mon, 01 Jan 0001 00:00:00 +0000

ztd audit

Export a run’s audit record to .ztd/runs/ (bash scripts/audit.sh)

ztd audit [flags]

Options

 -h, --help help for audit

ztd auth

Mon, 01 Jan 0001 00:00:00 +0000

ztd auth

Sync the operator’s Claude Code login into the guest (bash scripts/auth-sync.sh)

ztd auth [flags]

Options

 -h, --help help for auth

ztd cattle

Mon, 01 Jan 0001 00:00:00 +0000

ztd cattle

One-shot up→auth→skills→commands→run (bash scripts/cattle.sh)

ztd cattle [flags]

Options

 -h, --help help for cattle

ztd check

Mon, 01 Jan 0001 00:00:00 +0000

ztd check

Run the host-side preflight (bash scripts/check-requirements.sh)

ztd check [flags]

Options

 -h, --help help for check

ztd commands

Mon, 01 Jan 0001 00:00:00 +0000

ztd commands

Provision/pull the guest agent’s ~/.claude/commands (bash scripts/agent-sync.sh commands)

ztd commands [flags]

Options

 -h, --help help for commands

ztd config

Mon, 01 Jan 0001 00:00:00 +0000

ztd config

Print the resolved ztd configuration

ztd config [flags]

Options

 -h, --help help for config

ztd down

Mon, 01 Jan 0001 00:00:00 +0000

ztd down

Tear down the VM (discards the ephemeral key + transient git remote on success)

ztd down [flags]

Options

 -h, --help help for down

ztd fetch

Mon, 01 Jan 0001 00:00:00 +0000

ztd fetch

Fetch the guest’s commits into the operator’s checkout (bash scripts/fetch-remote.sh)

ztd fetch [flags]

Options

 -h, --help help for fetch

ztd init

Mon, 01 Jan 0001 00:00:00 +0000

ztd init

Scaffold this project’s .ztd/ztd.toml (the single config file)

ztd init [flags]

Options

 -h, --help help for init

ztd ip

Mon, 01 Jan 0001 00:00:00 +0000

ztd ip

Print the VM’s IP address

ztd ip [flags]

Options

 -h, --help help for ip

ztd list:orphans

Mon, 01 Jan 0001 00:00:00 +0000

ztd list:orphans

List orphaned VMs/resources not tracked by state

ztd list:orphans [flags]

Options

 -h, --help help for list:orphans

ztd logs

Mon, 01 Jan 0001 00:00:00 +0000

ztd logs

Follow guest cloud-init/provisioning output

ztd logs [flags]

Options

 -h, --help help for logs

ztd mount

Mon, 01 Jan 0001 00:00:00 +0000

ztd mount

SSHFS-mount a remote guest’s repo (bash scripts/mount-remote.sh mount)

ztd mount [flags]

Options

 -h, --help help for mount

ztd plan

Mon, 01 Jan 0001 00:00:00 +0000

ztd plan

Show the Terraform plan for the VM

ztd plan [flags]

Options

 -h, --help help for plan

ztd purge

Mon, 01 Jan 0001 00:00:00 +0000

ztd purge

Destroy all ztd-managed resources

ztd purge [flags]

Options

 -h, --help help for purge

ztd reset

Mon, 01 Jan 0001 00:00:00 +0000

ztd reset

Recreate the VM (down+up; keeps the ephemeral key)

ztd reset [flags]

Options

 -h, --help help for reset

ztd run

Mon, 01 Jan 0001 00:00:00 +0000

ztd run

Launch the agent in a guest tmux session (bash scripts/run-agent.sh run)

ztd run [flags]

Options

 -h, --help help for run

ztd setup

Mon, 01 Jan 0001 00:00:00 +0000

ztd setup

Install the persistent Docker→libvirt forwarding fix (–transient, –undo)

ztd setup [flags]

Options

 -h, --help help for setup

ztd skills

Mon, 01 Jan 0001 00:00:00 +0000

ztd skills

Provision/pull the guest agent’s ~/.claude/skills (bash scripts/agent-sync.sh skills)

ztd skills [flags]

Options

 -h, --help help for skills

ztd ssh

Mon, 01 Jan 0001 00:00:00 +0000

ztd ssh

Shell into the VM (ephemeral key)

ztd ssh [flags]

Options

 -h, --help help for ssh

ztd status

Mon, 01 Jan 0001 00:00:00 +0000

ztd status

Report the ztd VM’s status (–watch for a live readiness dashboard)

ztd status [flags]

Options

 -h, --help help for status
 --timeout duration how long --watch waits for the guest to be fully ready before giving up (default 10m0s)
 --watch live readiness dashboard: poll the guest and watch features (SSH, cloud-init, virtiofs repo, Docker, Node, Claude) go green as they come online

ztd test

Mon, 01 Jan 0001 00:00:00 +0000

ztd test

Run the full acceptance suite for the current backend (bash scripts/smoke-test[-proxmox|-ec2].sh)

ztd test [flags]

Options

 -h, --help help for test

ztd test:config

Mon, 01 Jan 0001 00:00:00 +0000

ztd test:config

Run the VM-free config-loader unit test (bash scripts/test-config.sh)

ztd test:config [flags]

Options

 -h, --help help for test:config

ztd tunnel

Mon, 01 Jan 0001 00:00:00 +0000

ztd tunnel

Forward a VM port to localhost (default 8080; e.g. ztd tunnel 8080)

ztd tunnel [port] [flags]

Options

 -h, --help help for tunnel

ztd unmount

Mon, 01 Jan 0001 00:00:00 +0000

ztd unmount

Unmount a remote guest’s repo (bash scripts/mount-remote.sh unmount)

ztd unmount [flags]

Options

 -h, --help help for unmount

ztd up

Mon, 01 Jan 0001 00:00:00 +0000

ztd up

Boot the VM (generates the ephemeral guest key first)

ztd up [flags]

Options

 -h, --help help for up

ztd validate

Mon, 01 Jan 0001 00:00:00 +0000

ztd validate

Validate the Terraform configuration

ztd validate [flags]

Options

 -h, --help help for validate

ztd version

Mon, 01 Jan 0001 00:00:00 +0000

ztd version

Print the ztd version

ztd version [flags]

Options

 -h, --help help for version

Install ztd

Mon, 01 Jan 0001 00:00:00 +0000

Install ztd

ztd is a single static binary. It carries its own runtime assets — the Terraform root, the lima template, cloud-init, the toolbox compose file — embedded inside it, so there is no ZTD source checkout to clone and nothing to keep in sync with the binary.

What it still needs from the host is the thing that can’t be shipped in a binary:

Backend	Host needs
`vz` (local macOS)	Docker + lima
`kvm` (local Linux)	Docker + libvirt/qemu/dnsmasq + `virtiofsd`
`proxmox` / `ec2` (remote)	Docker only

Run ztd check after installing — it verifies every one of those and tells you the exact command to fix what’s missing.

ZTD — Zero Trust Dev

Let the agent go YOLO: introducing ZTD

Let the agent go YOLO: introducing ZTD

An autonomous agent run

An autonomous agent run

The scenario

Commands

Commands

The zero-trust model

The zero-trust model

Use the Proxmox backend

Use the Proxmox backend

vz — macOS backend (lima)

Plan — the vz macOS local backend (lima)

Your first ZTD VM

Your first ZTD VM

Before you start

Architecture

Architecture

One interface, many backends

Configuration

Configuration

Forward a port from the VM

Forward a port from the VM

A different port

Multiple ports at once

Standalone CLI (install + run anywhere)

Plan — the standalone, installable ztd CLI

Backend cohesion & parity

Plan — backend cohesion & parity

The decision: centralize at the contract, NOT at Terraform

Backends

Backends

libvirt version pin

Cattle, not pets

Cattle, not pets

The lifecycle

Publish the agent's results

Publish the agent’s results (git runs on the host)

Why not push from the VM?

Use the vz (macOS) backend

Use the vz (macOS) backend

Host prerequisites

Host prerequisites

Reset or destroy a VM

Reset or destroy a VM

Destroy

Reset to a clean state

Roadmap

Roadmap

Phase 0 — done

Phase 1 — done

Use the EC2 backend

Use the EC2 (AWS) backend

Pin or override the toolbox image

Pin or override the toolbox image

ztd

ztd

Options

SEE ALSO

ztd attach

ztd attach

Options

SEE ALSO

ztd audit

ztd audit

Options

SEE ALSO

ztd auth

ztd auth

Options

SEE ALSO

ztd cattle

ztd cattle

Options

SEE ALSO

ztd check

ztd check

Options

SEE ALSO

Plan — the `vz` macOS local backend (lima)

Plan — the standalone, installable `ztd` CLI