How-to guides on ZTD — Zero Trust Dev

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.

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:

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.

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.

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.

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.