How yeet Works

Yeet has two parts:

• yeet runs on your workstation.
• catch runs on each Linux host you manage.

You use yeet init once per host to install catch. After that, yeet talks to catch over Tailscale and asks it to install, update, inspect, and remove services.

There is no hidden scheduler. The state lives on hosts you control, and the CLI is the handle you use to move that state deliberately.

When you run yeet run <svc> <payload>, responsibility moves in this order:

1. yeet detects the payload type.
2. yeet ships the payload or deployment recipe to catch.
3. catch writes the service files under the service root.
4. catch installs or updates the service as systemd, Docker Compose, a cron timer, or a VM service.
5. yeet streams status, logs, and events back to your terminal.

For the command path, start with Workflows. For payload detection, see Service Types.

Setup uses the SSH machine host:

yeet init root@<machine-host>

Normal commands use the catch host:

CATCH_HOST=<catch-host> yeet status
yeet --host=<catch-host> status
yeet run <svc>@<catch-host> ./compose.yml

See How Commands Work for host targeting and argument routing.

Catch owns the live service state on the host. A local yeet.toml stores the replay recipe for your project: payload path, host, network mode, service root, snapshot settings, cron schedule, and payload args.

Those are intentionally different jobs. Catch knows what is running. The local project file knows how you want to run it again. If those drift, make the drift visible instead of guessing.

If live state changes from another checkout, sync it back:

yeet service sync <svc>

Each service can have generations. A new deploy creates a new generation, and rollback can return to the previous one when a previous generation is available. Generations recover deployed definitions and install artifacts. They are not storage snapshots.

Use staging when you want to upload a payload before applying it:

yeet stage <svc> ./bin/<svc>
yeet stage <svc> show
yeet stage <svc> commit

Services can use host ports, the private service network, a Tailscale service node, the host LAN, or combinations of those modes. The mode also controls outbound internet: svc uses the catch host gateway, lan uses the LAN or VLAN gateway, and plain ts needs a Tailscale exit node for ordinary internet. VMs use the service network by default for management.

Reachability, DNS, and egress are one system. Choose all three before deploying a service with custom networking.

See Networking, DNS, and Tailscale for the details that affect operators.

Catch must run as a tagged Tailscale node, such as tag:catch. Your tailnet policy decides which devices and tags can reach catch. Catch rejects untagged, user-owned nodes because it is server infrastructure. Identity is part of the control plane.

See Tailscale Setup for the policy shape.