Quickstart

Get an isolated VM running in about a minute, from any directory — there is no ZTD source tree to clone.

1. Install ztd

macOS:

brew tap frob/ztd https://gitlab.com/frob/homebrew-ztd.git
brew install --cask ztd

Linux (see Install ztd for checksums and other architectures):

VERSION=0.4.3
base="https://gitlab.com/frob/ztd/-/releases/$VERSION/downloads"
curl -fL "$base/ztd_${VERSION}_linux_amd64.tar.gz" | tar -xz ztd
install -Dm755 ztd ~/.local/bin/ztd

2. Prepare the host

All orchestration tooling (Terraform, Task) runs in a container. What the host needs is Docker, plus a hypervisor if the VM is local: lima on macOS, libvirt/qemu on Linux. Remote backends (proxmox, ec2) need only Docker.

ztd check      # verifies everything and prints the fix for anything missing
ztd setup      # local Linux only: applies the two host-side fixes it flags

On Arch, the Linux side of that is:

sudo pacman -S --needed qemu-full libvirt dnsmasq virtiofsd
sudo systemctl enable --now libvirtd
sudo usermod -aG libvirt "$USER"   # then re-login

ztd check is the authority here — run it until it’s green rather than guessing.

3. Bring up a VM

From the directory holding the work you want the agent to touch:

ztd init       # writes .ztd/ztd.toml — every key is commented; defaults boot
ztd up         # boot the VM (prints its IP when done)

The backend defaults to whatever “local” means on your machine: vz on macOS, kvm on Linux.

4. Use it

ztd ssh              # shell into the VM
ztd tunnel -- 8080   # reach a guest service at http://localhost:8080

Inside the VM you get its own Docker daemon, Node, and the agent runner — fully isolated from your host’s Docker. Your working tree is live-shared into the guest, and files the guest creates are owned by you on the host.

5. Tear it down

ztd down       # destroy the VM

Cattle, not pets: nothing of value lives in the VM. Your work leaves over git; the VM is disposable.

New to ZTD? Work through Your first ZTD VM.
Want the remote backend? See Use the Proxmox backend.
Curious why it’s built this way? Read The zero-trust model.