Service Workspace

Use a service workspace before your first yeet run or yeet cron. A directory such as ~/yeet-services keeps third-party Compose apps, env files, custom Dockerfiles, scripts, binaries, and yeet.toml together.

Run deploy and service commands from this directory. Yeet reads and writes yeet.toml in the current directory, so a consistent workspace lets it reuse saved payload paths, hosts, network flags, service roots, snapshots, cron schedules, and payload args.

Run this on your workstation:

mkdir -p ~/yeet-services
cd ~/yeet-services

Use one folder per app or custom service:

~/yeet-services/
  yeet.toml
  uptime-kuma/
    compose.yml
  vaultwarden/
    compose.yml
    vaultwarden.env
  home-assistant/
    compose.yml
  gitea/
    compose.yml
  mqtt-bridge/
    Dockerfile
    config.yml
  sensor-collector/
    cmd/
      sensor-collector/
  jobs/
    backup.sh
  bin/
    sensor-collector

Yeet creates yeet.toml after a successful deploy that saves project config. Create or enter the workspace before deploying so that file lands in the right place. You do not need to create it by hand.

Most homelab apps start from a Compose file:

cd ~/yeet-services
yeet run uptime-kuma ./uptime-kuma/compose.yml
yeet run --env-file=./vaultwarden/vaultwarden.env vaultwarden ./vaultwarden/compose.yml

After each successful deploy, yeet saves the service entry in yeet.toml. Future commands can reuse that saved payload path and deploy options.

Use the same workspace for local Dockerfiles:

cd ~/yeet-services
yeet run mqtt-bridge ./mqtt-bridge/Dockerfile

Build binaries for the catch host architecture before deploying them:

cd ~/yeet-services
GOOS=linux GOARCH=amd64 go build -o ./bin/sensor-collector ./sensor-collector/cmd/sensor-collector
yeet run sensor-collector ./bin/sensor-collector

Put scheduled jobs beside the rest of the homelab payloads:

cd ~/yeet-services
yeet cron backup ./jobs/backup.sh "0 3 * * *"

Run saved services from the workspace directory:

cd ~/yeet-services
yeet run uptime-kuma
yeet run mqtt-bridge

Yeet reads yeet.toml, finds the saved payload path, and reuses saved options such as network mode, env file, service root, snapshot settings, and payload args.

Prefer paths that stay inside the workspace:

yeet run uptime-kuma ./uptime-kuma/compose.yml
yeet run mqtt-bridge ./mqtt-bridge/Dockerfile
yeet run sensor-collector ./bin/sensor-collector

Relative paths make the workspace easier to back up, move, or sync. They also keep yeet.toml readable.

Keep each third-party app in its own folder with its Compose file, env files, and app-specific config. Use shared folders such as bin/ and jobs/ for small custom payloads.

Avoid running deploy commands from random directories. If yeet cannot find the right yeet.toml, it cannot reuse the saved service entry.

Service names must use 1-63 lowercase letters, numbers, and dashes. Start with a letter and end with a letter or number.

• Quick Start installs yeet and catch.
• Payloads helps choose Compose, Dockerfile, binary, script, cron, or VM payloads.
• Workflows shows daily deploy and update commands.
• Configuration & Prefs explains yeet.toml, client prefs, and host defaults.