Data Layout

Catch stores live state on each host under its data directory. You usually do not need to edit these files directly, but the layout helps when you inspect a host or plan service roots.

You do not need to memorize the tree. Know which directory is disposable and which one contains data you intend to keep.

Fresh yeet init installs default to $HOME/yeet-data on the catch host. Interactive init asks before using that path. Manual catch runs use the same default unless you pass catch --data-dir. Pick a path you are willing to back up, monitor, and explain later.

<data-dir>/
  db.json
  services/
  mounts/
  registry/
  tsnet/

Use Host Setup for first-time host setup and catch reference for manual catch flags.

By default, services live under:

<data-dir>/services/<svc>/

Set a custom service root at first deploy:

yeet run <svc> ./compose.yml --service-root=/srv/apps/<svc>

Use a ZFS dataset as the service root:

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

Inside a service root, the common directories are:

<service-root>/
  bin/
  run/
  data/
  env/

• bin/ contains install artifacts such as binaries, compose files, and units.
• run/ contains runtime files.
• data/ contains persistent application data.
• env/ contains environment files managed by yeet env.

yeet run can set the root for a new service. Stop an existing service before moving its root with yeet service set. Moving storage while the process is writing to it can corrupt or lose data.

yeet stop <svc>
yeet service set <svc> --service-root=/srv/apps/<svc> --copy
yeet start <svc>

Use --empty instead of --copy when you want a new empty root.

For ZFS-backed moves:

yeet stop <svc>
yeet service set <svc> --service-root=tank/apps/<svc> --zfs --copy
yeet start <svc>

Parent directories or parent datasets must already exist. yeet service set leaves the old root in place as a rollback handle until you decide otherwise.

Use yeet host set when you want to change the catch data directory or the default root for future services. This is a host-level change, so inspect first and read the plan before applying it:

yeet info
yeet host set --data-dir=/srv/yeet-data
yeet host set --services-root=/srv/yeet-services --migrate-services=all
yeet host set --zfs --data-dir=flash/yeet/data --services-root=flash/yeet/services --migrate-services=all

Run yeet info to inspect the current host data directory, services root, catch service root, and service/VM inventory. Use yeet info --host=<catch-host> when you want to inspect a host other than the current default.

Changing the data directory copies catch state, reinstalls the catch unit, and restarts catch. Changing the default services root affects services that still live under the previous default root. With --migrate-services=all, yeet stops those services, moves their roots, updates catch, and starts services that were running before the move. With --migrate-services=none, those services stay at their current roots and continue to run there.

With --zfs, --data-dir and --services-root are dataset names. The services root is a dataset prefix: migrated services and catch use child datasets such as flash/yeet/services/<svc>.

If you omit --migrate-services in an interactive terminal, yeet asks whether to migrate affected services. With --yes, pass --migrate-services=all or --migrate-services=none explicitly. After a migration, yeet updates matching entries in the local yeet.toml; pass --config ./yeet.toml when you run the command outside the project directory.

yeet.toml stores the local recipe for future runs. Catch stores the live root on the host. If they drift, sync the live settings back.

If another checkout changes live service settings, sync them back:

yeet service sync <svc>
yeet service sync --all

ZFS-backed service roots can get yeet-managed recovery points before deploys, Docker image updates, and service-root moves. Use the ZFS guide for snapshot defaults, retention, clone-first recovery, and VM disk behavior:

• ZFS
• Workflows: recover data