Payloads

A payload is the thing you give to yeet run, yeet stage, or yeet cron. Choose the guide that matches what you already have.

Choose the smallest payload type that matches the workload. Use a VM only when the service needs a full guest OS or stronger isolation.

You have	Start with
compose.yml	Containers
Public image, such as nginx:alpine	Containers
Local Dockerfile	Containers
Local container image	Containers
Linux binary	Binaries & Scripts
Shell script or other shebang file	Binaries & Scripts
Scheduled job	Cron Jobs
Ubuntu, NixOS, or imported Linux guest	VMs

Before your first yeet run or yeet cron, create or enter a Service Workspace. A successful deploy writes yeet.toml in the current directory, so the workspace is where yeet saves relative payload paths and future run options.

Keep yeet.toml with the files it references.

Most services follow this loop:

yeet run <svc> <payload>
yeet logs -f <svc>
yeet status <svc>

After the first successful deploy, yeet writes service config to yeet.toml. For an existing service, a payload-only redeploy reuses saved options such as network mode, tags, service root, snapshot settings, and payload args. The payload changes; the operating context stays put unless you change it.

Use the payload guide first. Then add storage or networking options when the service needs them. Network modes also choose the outbound internet path: svc uses the catch host gateway, lan uses the LAN or VLAN gateway, and plain ts needs a Tailscale exit node for ordinary internet access.

Networking and storage flags change how the service runs and recovers.

yeet run <svc> ./compose.yml --net=svc,ts
yeet run <svc> ./compose.yml --service-root=tank/apps/<svc> --zfs

See Networking for svc, lan, ts, and combined modes. See ZFS for dataset-backed service roots and snapshots.

• Workflows shows common deploy and update flows.
• Service Types explains payload detection.
• How Commands Work explains host targeting and argument routing.