Configuration

There are two kinds of local state. Client config answers "what host or workspace do I usually mean?" Project config answers "how do I replay this set of services?" Keep those jobs separate.

Yeet stores client config in:

$XDG_CONFIG_HOME/yeet/config.toml

If XDG_CONFIG_HOME is unset, yeet uses ~/.config/yeet/config.toml. Existing ~/.yeet/prefs.json files migrate automatically on first run.

Schema:

default_host = "morpheus-catch"
workspaces = ["/srv/yeet-services"]

default_host is the catch host (Tailscale hostname) that yeet uses when you do not specify a host with @<host>, --host, or yeet.toml. This is not the SSH machine host from yeet init; it is the operating target after catch is installed. See Tailscale for details.

workspaces is the list of service workspace directories yeet can fall back to when the current directory does not contain a yeet.toml. Each registered workspace owns one or more catch hosts, and a catch host belongs to only one registered workspace.

Commands:

yeet config
yeet config --host=<catch-host>
yeet config --workspace ~/yeet-services
yeet config --add-workspace ~/lab-services
yeet config --remove-workspace ~/lab-services
yeet config --clear-workspaces

--workspace and --add-workspace require the directory to already exist. To create and register a workspace during host setup, use yeet init --workspace.

When you run yeet from a project directory, it can persist service defaults in a yeet.toml file. This file is the replay recipe for the services in that directory.

For homelab services, use a Service Workspace so Compose files, env files, Dockerfiles, scripts, binaries, and yeet.toml stay together.

yeet run --web writes the same project config entries as yeet run. Payload paths, env files, service-root settings, ZFS flags, snapshot overrides, cron schedules, and payload args are saved in yeet.toml the same way.

Yeet first looks for yeet.toml in or above the current directory. If none is found, it falls back to the registered workspace that owns the target catch host. A local or upward yeet.toml always wins over workspace fallback.

If an interactive command finds a local yeet.toml that is not registered as a workspace yet, yeet can ask whether to save that directory in client config. If the file declares one catch host, yeet can also save that host as the default. If it declares multiple hosts, yeet asks which one should become the default for commands run outside the workspace.

Host ownership belongs in yeet.toml:

version = 1
hosts = ["morpheus-catch", "trinity-catch"]

Example:

version = 1
hosts = ["morpheus-catch", "trinity-catch"]

[[services]]
name = "uptime-kuma"
host = "morpheus-catch"
payload = "./uptime-kuma/compose.yml"
args = ["--net=svc,ts"]

[[services]]
name = "sensor-collector"
host = "trinity-catch"
payload = "./bin/sensor-collector"
sandbox = "on"
sandbox_ro = ["/etc/sensor-collector"]
sandbox_rw = ["/srv/sensor-cache:/cache"]
args = ["--listen", ":9100"]

[[services]]
name = "backup"
host = "morpheus-catch"
payload = "./jobs/backup.sh"
schedule = "0 3 * * *"
run_as = "backup"
args = ["--net=iso", "--", "--full"]

Notes:

• Yeet stores payload relative to the yeet.toml directory when possible.
• schedule is the sole marker for a scheduled native service and contains its five-field cron expression. Do not set type for scheduled services.
• args keeps run control flags before -- and binary or script arguments after --.
• sandbox records the authoritative native state as legacy, on, or off. Commands select only on or off; legacy records an older active generation that has not received an explicit choice.
• sandbox_ro stores read-only files or directories. sandbox_rw stores writable directories. Each entry is SOURCE or SOURCE:DEST, and the normalized lists never contain the reset control token.
• hosts controls host-scoped commands like yeet status with no args.

If the live host state changes from another checkout, use yeet service sync instead of editing around the drift by hand.

Fresh successful native runs save the resolved explicit sandbox policy. A matching service set writes Catch's authoritative result only after the remote mutation succeeds. See Native Sandboxing before editing these fields by hand.

Client:

• CATCH_HOST: default target catch host (Tailscale hostname). See Tailscale.

yeet edit uses $EDITOR if set, otherwise vim.