Binaries & Scripts

Binary and script payloads become systemd services on the catch host. Use this path for a single long-running process that does not need a container.

Native binaries, scripts, and timer-backed jobs can use --net=iso. Catch runs the service inside an iso network namespace while leaving its user, group, capabilities, and filesystem policy unchanged. Root and non-root workloads use the same network path. iso controls ordinary workload traffic; it does not claim to contain a hostile host-root process.

This is the direct path. Build or write the thing, hand it to yeet, and catch installs it as a host service. The host must have any runtime dependencies the payload expects.

Run these commands from a Service Workspace. The first successful deploy writes yeet.toml in the current directory.

New native services run as the shared yeet-svc account by default. Select a different existing host account when needed:

yeet run <svc> ./bin/<svc> --run-as=app:app

Yeet saves that identity and reuses it on later deploys. The shared default reduces workload privilege but is not isolation between native services.

Build for the target host architecture before deploying. For a typical Linux amd64 host:

GOOS=linux GOARCH=amd64 go build -o ./bin/<svc> ./cmd/<svc>
yeet run <svc> ./bin/<svc>

Scripts need a shebang and executable-compatible contents for the host. If the shebang points at a missing interpreter, the service will fail.

yeet run <svc> ./script.sh
yeet run <svc> ./script.sh -- --app-flag value

Yeet saves arguments after -- as payload args and replays them on future runs.

Rebuild or edit the local payload, then re-run yeet run. For an existing service, a payload-only redeploy reuses saved run options from yeet.toml. That is useful because the binary changes more often than the network, root, or env-file decision.

yeet run <svc> ./bin/<svc>
yeet run <svc> ./script.sh

Use --force when you want to redeploy even if yeet detects no payload or configuration changes.

yeet run --force <svc> ./bin/<svc>

Choose a network during the first deployment:

yeet run <svc> ./bin/<svc> --net=iso
yeet run <svc> ./script.sh --net=svc

Change an existing native service through service set. The network mutation restarts a long-running service immediately; a timer remains the scheduling unit and the change does not invoke its job as a verification side effect.

yeet service set <svc> --net=iso
yeet service set <svc> --net=host

Network selection and --run-as are independent. One transaction can request both without treating root or non-root identity as a network requirement. Rerunning yeet run with different network settings for an existing service stops with service set guidance, while payload-only redeployments still work. If Catch applies the remote mutation but the local project update fails, run yeet service sync <svc>.

Existing native services keep their current identity until an explicit migration. To adopt the managed default:

yeet service set <svc> --run-as=yeet-svc

The migration updates service-root ownership and the systemd unit together, then restores the previous state if the new unit cannot start. Non-root native services cannot bind privileged host ports directly; use a higher port, a root-owned proxy, or explicitly choose --run-as=root.

Binary and script services can use a ZFS dataset as their service root. This is useful when the process writes persistent data and you want yeet-managed snapshots before redeploys. If the process is stateless, a normal path is enough.

yeet run <svc> ./bin/<svc> --service-root=tank/apps/<svc> --zfs

With --zfs, --service-root is a dataset name. See ZFS for dataset creation, snapshot defaults, and service-root moves.

yeet env copy <svc> ./app.env
yeet env edit <svc>
yeet env set <svc> LOG_LEVEL=debug
yeet copy ./config.yml <svc>:config/config.yml

When you pass --env-file during yeet run, yeet stores the env file path in yeet.toml and re-uploads it on future runs. Keep that env file in the workspace so the deploy recipe does not depend on a random absolute path.

yeet run --env-file=prod.env <svc> ./bin/<svc>

yeet status <svc>
yeet logs -f <svc>
yeet restart <svc>
yeet stop <svc>
yeet start <svc>

Use Workflows for common deploy and update flows, and Service Types for detection details.

yeet rm <svc>
yeet rm --clean <svc>

--clean removes the managed service data root and local yeet.toml entry in addition to uninstalling the systemd service. Read the confirmation prompt before accepting.