First-Run Validation

Use this playbook after yeet init on a fresh host. It checks the connection to catch first, then the payload paths that should work on a normal Debian/Ubuntu-style server. Run the optional KVM, LAN, and ZFS checks only when you plan to use those features.

Run these tests before deploying a real app or storing real data.

All examples use disposable service names. If you have more than one catch host, set CATCH_HOST=<catch-host> or pass --host=<catch-host> so every command targets the fresh host.

Run this playbook from your Service Workspace, or from a temporary validation directory. Smoke deploys write yeet.toml in the current directory. If you use a temporary directory, delete it when you are done.

CATCH_HOST=<catch-host> yeet version
CATCH_HOST=<catch-host> yeet status

If this is your only catch host, the unqualified commands should work too:

yeet version
yeet status

On a host using the default filesystem layout, confirm Catch state exists at /var/lib/yeet and the default service root is below it:

yeet ssh -- test -d /var/lib/yeet
yeet ssh -- test -d /var/lib/yeet/services

Skip these path checks when you selected custom roots or ZFS during init. Those roots are preserved instead of being rewritten to the filesystem defaults.

If you have Tailscale installed locally, yeet list-hosts can also confirm the catch node is visible in your tailnet. It is optional for this playbook because normal yeet commands use the catch Tailscale identity and ordinary network reachability from your workstation.

If yeet status cannot connect, confirm yeet init stored a Tailscale OAuth client secret or catch-node auth key, and confirm the catch node has the required tag. After fixing the tag or policy, rerun init:

yeet init root@<machine-host>

See Tailscale if the SSH machine host and catch host names are confusing, or if the tailnet policy needs tagOwners/grant changes before catch can use the tag you selected.

This validates the most common path: Docker on the host, published host ports, service status, logs, and cleanup.

yeet run -p 18080:80 yeet-smoke-web nginx:alpine
yeet status yeet-smoke-web
yeet info yeet-smoke-web
yeet logs yeet-smoke-web

From the catch host itself, confirm the published port answers:

yeet ssh -- curl -fsS http://127.0.0.1:18080/ >/dev/null

Then remove the disposable service:

yeet rm --clean yeet-smoke-web

--clean deletes the service data and removes the disposable yeet.toml entry, so read the confirmation prompt before accepting.

If this fails, start with Docker payloads fail.

This validates host systemd services without involving containers.

cat > yeet-smoke-script.sh <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
while true; do
  date
  sleep 30
done
EOF
chmod +x yeet-smoke-script.sh

yeet run yeet-smoke-script ./yeet-smoke-script.sh
yeet status yeet-smoke-script
yeet info yeet-smoke-script
yeet ssh yeet-smoke-script -- id
yeet logs yeet-smoke-script
yeet service set yeet-smoke-script --run-as=root
yeet service set yeet-smoke-script --run-as=yeet-svc
yeet rm --clean yeet-smoke-script
rm yeet-smoke-script.sh

For a new native service, yeet info should show Run as: yeet-svc and the service shell should report that account. This checks the workload identity; Catch and its host-management helpers still run with the privileges they need. The two service set commands exercise an explicit identity migration in both directions before cleanup.

Each identity change updates ownership and the systemd unit as one rollback-safe operation. If your service uses a ZFS dataset, yeet preserves that root and applies the same identity migration there instead of copying it to the default filesystem path.

If this fails while Docker payloads work, inspect the unit with:

yeet ssh -- systemctl status yeet-smoke-script.service

Cron payloads are systemd timers. This validates timer creation and one scheduled run.

cat > yeet-smoke-cron.sh <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
date
EOF
chmod +x yeet-smoke-cron.sh

yeet cron yeet-smoke-cron ./yeet-smoke-cron.sh "* * * * *"
yeet status yeet-smoke-cron
sleep 70
yeet logs yeet-smoke-cron
yeet rm --clean yeet-smoke-cron
rm yeet-smoke-cron.sh

VM payloads require x86_64 Linux, KVM, TUN/TAP, and a few host filesystem and networking tools. Many VPS providers do not expose nested virtualization; that is a host limitation, not a failed yeet install.

yeet ssh -- sh -lc '
test -e /dev/kvm && echo kvm=yes || echo kvm=no
test -e /dev/net/tun && echo tun=yes || echo tun=no
for c in qemu-img zstd e2fsck resize2fs mount umount ip; do
  command -v "$c" >/dev/null && echo "$c=yes" || echo "$c=no"
done
'

If the VM devices exist but tools are missing on a Debian/Ubuntu host, interactive yeet init can ask before installing them. You can also install the packages listed in VMs.

On a VM-capable Debian/Ubuntu host, interactive yeet init can also ask to prepare VM LAN bridge support. Say yes when you plan to run VMs with --net=lan. Say no to defer it; the first VM LAN create prompts again before it creates the VM service.

If KVM and TUN/TAP are available and the required tools are present, create a disposable VM:

yeet vm images catalog
yeet run yeet-smoke-vm vm://ubuntu/26.04
yeet ssh yeet-smoke-vm -- uname -a
yeet rm --clean yeet-smoke-vm

To verify the NixOS image family too, run the same smoke check with vm://nixos/26.05.

If KVM is missing, use containers, binaries, scripts, and cron jobs on this host, and run VM payloads on a KVM-capable machine. See VMs.

LAN networking requires a host attached to a network where macvlan and DHCP make sense. A WAN-only VPS usually should skip this check. LAN services use the LAN or VLAN gateway for outbound internet.

yeet run yeet-smoke-lan nginx:alpine --net=lan
yeet ip yeet-smoke-lan
yeet rm --clean yeet-smoke-lan

For VM LAN networking, run the same idea with a disposable VM:

yeet run yeet-smoke-vm-lan vm://ubuntu/26.04 --net=lan
yeet ip yeet-smoke-vm-lan
yeet rm --clean yeet-smoke-vm-lan

If the host needs a bridge, yeet prompts before creating the VM. Applying the bridge can briefly interrupt host networking. If the command disconnects during that step, wait for the host to come back and rerun the same command.

ZFS-backed service roots require an existing parent dataset. Skip this if you do not plan to use ZFS. Optional storage checks are useful only when they match the storage you are actually going to operate.

ZFS datasets are not copied or deleted implicitly. Use ZFS tools to confirm a custom or nested dataset remains mounted at the path you selected before and after any Catch upgrade.

yeet run yeet-smoke-zfs nginx:alpine --service-root=tank/apps/yeet-smoke-zfs --zfs
yeet rm --clean yeet-smoke-zfs

See Networking and ZFS for the full model. Use svc,ts instead of plain ts when a service needs both a Tailscale identity and normal outbound internet through the catch host.

After the smoke tests, yeet status should not list the disposable services:

yeet status

If a service removal fails, rerun the remove command and then inspect Troubleshooting for the relevant payload type.