DOCSEARCHbyAlgolia
Submit Docs

Yeet Documentation

website·Indexed 29 days ago

https://yeetrun.com/

A tool for deploying and managing containers, binaries, and microVMs from a single CLI. Yeet provides native sandboxing, ZFS-backed snapshots, and Tailscale integration for homelab service orchestration, featuring a local CLI and a remote host-side component called catch.

Tokens
31.7K
Snippets
228
Records
267
Agent score
47%

What's inside Yeet

  1. Overview of Native Sandboxing in Yeet

    Native sandboxing controls the filesystem and namespace view of native binaries, shebang scripts, and scheduled jobs using Bubblewrap. It provides the workload with its service data and required runtime files without exposing the entire host filesystem. While it reduces visibility, it shares the host kernel and is not a VM security boundary; for untrusted code, a non-root service account should be used.

  2. Understand Yeet's target use case and trust model

    Yeet is designed for homelab-style use by operators comfortable with Linux hosts over SSH. It is not a general-purpose or multi-tenant orchestrator. It assumes a single-operator trust model using Linux/systemd hosts and Tailscale connectivity.

  3. Understand Yeet DNS service discovery

    Yeet DNS allows services and VMs on the svc network to find each other using names instead of hard-coded private IP addresses. It is specifically for workloads joined to the yeet service network and is not a replacement for a LAN resolver or a tailnet-wide naming system. Services without svc networking (e.g., those using only ts) do not get Yeet DNS records.

  4. Use the catch CLI for host-side management

    The catch binary runs on remote Linux hosts and receives requests from yeet. While yeet init is the preferred method for installation and updates, catch can be invoked directly for manual installs, checking binary versions, or debugging startup issues. Direct invocation bypasses some guardrails provided by yeet init.
    catch [flags] [install|version|is-catch]

  5. Understand the Yeet architecture and components

    Yeet consists of two primary components: yeet (a CLI running on the developer's workstation) and catch (a remote daemon running on each managed Linux host). The CLI communicates with the daemon over Tailscale to manage services. There is no central scheduler; state is maintained on the hosts themselves, and the CLI is used to manipulate that state.

  6. Fix binary architecture mismatches

    Ensure binaries are built for the specific architecture of the catch host. If the CPU cannot execute the binary, the service will fail to start.
    # Example: Build for linux/amd64
GOOS=linux GOARCH=amd64 go build -o ./bin/<svc> ./cmd/<svc>

# Run the binary
yeet run <svc> ./bin/<svc>

  7. Deploy native binaries and scripts

    Deploy compiled binaries or scripts. Binaries must be built for the catch host architecture (e.g., Linux amd64). Native services run in a Bubblewrap sandbox by default. You can configure read-only (--sandbox-ro) and read-write (--sandbox-rw) directories during deploy or via yeet service set.
    # Build and deploy binary
GOOS=linux GOARCH=amd64 go build -o ./bin/<svc> ./cmd/<svc>
yeet run <svc> ./bin/<svc>

# Deploy script with arguments
yeet run <svc> ./script.sh -- --app-flag value

# Deploy with sandbox mounts
yeet run api ./api --sandbox-ro=/etc/api --sandbox-rw=/srv/api-cache:/cache

# Update sandbox state for existing service
yeet service set api --sandbox=on

# Replace specific sandbox-ro entries using reset
yeet service set api --sandbox-ro=reset --sandbox-ro=/etc/api

  8. Check project and service status

    The yeet status command provides an overview of services. It supports bulk reading of Docker, systemd, and VM status for performance. You can query specific services across hosts or output the status in JSON format for automation.
    # Check status of specific services
yeet status <svc-a> <svc-b>

# Output status as JSON
yeet status --format=json

# Output status as pretty-printed JSON
yeet status --format=json-pretty

  9. Deploy OCI images and Dockerfiles

    Yeet supports deploying directly from image references or local Dockerfiles. Image references are pulled by the host, while Dockerfiles are built locally for the host architecture and then pushed to the Catch host.
    # Deploy from a public image
yeet run <svc> nginx:latest

# Deploy from a private registry with port mapping
yeet run -p 8000:8000 <svc> ghcr.io/org/app:latest

# Push a local image to the host registry and run immediately
yeet docker push <svc> <local-image>:<tag> --run

# Deploy from a local Dockerfile
yeet run <svc> ./Dockerfile

  10. Deploy a native binary as a host service

    To run a single long-running process from a local executable, build the binary for the target host architecture (e.g., Linux amd64) and use the yeet run command. Native services run as the shared yeet-svc account by default, but you can specify a different host account using --run-as. The first successful deploy creates a yeet.toml file in the current Service Workspace to track configuration.
    # Build for target host
GOOS=linux GOARCH=amd64 go build -o ./bin/my-service ./cmd/my-service

# Deploy as default yeet-svc user
yeet run my-service ./bin/my-service

# Deploy as a specific user/group
yeet run my-service ./bin/my-service --run-as=app:app

  11. Host requirements for VM payloads

    To run VM payloads, the host must meet the following requirements:

    • Architecture: x86_64/amd64 Linux
    • Devices: /dev/kvm and /dev/net/tun
    • Tools: qemu-img, zstd, e2fsck, resize2fs, mount, umount, and ip
    • Filesystem: An executable Catch data filesystem (mounts for <data-root>/vm-jailer must not use noexec).

  12. Deploy custom services (Dockerfiles, Binaries, and Scripts)

    Custom services can be deployed using Dockerfiles, compiled binaries, or scripts.

    • Dockerfiles: Deploy directly from the workspace.
    • Binaries: Build for the catch host architecture before deploying.
    • Identity: Native services run as yeet-svc by default; use --run-as to specify a different account.
    • Sandboxing: Native services use Bubblewrap by default. Use --sandbox-ro for read-only paths and --sandbox-rw for writable paths.
    • Scheduled Jobs: Use the --cron flag to schedule a script or binary.
    cd ~/yeet-services

# Deploy from Dockerfile
yeet run mqtt-bridge ./mqtt-bridge/Dockerfile

# Build and deploy a binary
GOOS=linux GOARCH=amd64 go build -o ./bin/sensor-collector ./sensor-collector/cmd/sensor-collector
yeet run sensor-collector ./bin/sensor-collector

# Deploy binary with specific user and sandbox settings
yeet run sensor-collector ./bin/sensor-collector \
  --run-as=sensors:sensors \
  --sandbox-ro=/etc/sensor-collector \
  --sandbox-rw=/srv/sensor-cache:/cache

# Deploy a scheduled backup script
yeet run backup ./jobs/backup.sh --cron="0 3 * * *"