https://github.com/yeetrun/yeet
A lightweight service manager for deploying and managing services on remote Linux machines over SSH. Easily push binaries and containers without systemd configuration. Simple commands to start, stop, restart services and view logs. Supports multiple networking options including Tailscale and macvlan.
https://github.com/yeetrun/yeet
containerization containers deployment devops go linux networking remote-management service-manager ssh tailscale
Last synced: 22 days ago
JSON representation
A lightweight service manager for deploying and managing services on remote Linux machines over SSH. Easily push binaries and containers without systemd configuration. Simple commands to start, stop, restart services and view logs. Supports multiple networking options including Tailscale and macvlan.
- Host: GitHub
- URL: https://github.com/yeetrun/yeet
- Owner: yeetrun
- License: apache-2.0
- Created: 2025-04-17T23:08:47.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-09-18T20:27:44.000Z (5 months ago)
- Last Synced: 2025-09-18T22:52:49.768Z (5 months ago)
- Topics: containerization, containers, deployment, devops, go, linux, networking, remote-management, service-manager, ssh, tailscale
- Language: Go
- Homepage: https://catchall.sh/
- Size: 3.47 MB
- Stars: 6
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Authors: AUTHORS
Awesome Lists containing this project
README
# yeet
A personal homelab service manager built around Tailscale RPC. See the [Architecture](https://yeetrun.com/docs/concepts/architecture) page for how the pieces fit together.
## Read This First
This repository is **personal infrastructure tooling** for how I run my homelab. It is not intended for a general audience, likely will not work for you as-is, and may rely on assumptions, configs, and workflows that only exist in my environment. Use it only as a reference or starting point.
## Install yeet (release binary)
```bash
curl -fsSL https://yeetrun.com/install.sh | sh
```
Nightly build:
```bash
curl -fsSL https://yeetrun.com/install.sh | sh -s -- --nightly
```
## Toolchain Setup (Recommended: mise)
If you already have Go in your `PATH`, you can skip mise and use the Go commands elsewhere in this README. If not, the quickest path is to use mise to install the toolchain and run the bootstrap task.
1) Install mise (use a package manager like Homebrew/apt/dnf/pacman, or run the installer script):
```bash
curl https://mise.run | sh
```
2) Activate mise in your shell (zsh example — swap for bash/fish as needed):
```bash
echo 'eval "$(mise activate zsh)"' >> ~/.zshrc
```
3) From the repo root, install tools (Go 1.25.5) + bootstrap a host:
```bash
mise install
mise run init-host -- root@
```
## High-Level Overview
yeet is a lightweight client + server setup for deploying and managing services on remote Linux machines. The primary use case is running Docker images on a host over Tailscale with a tiny workflow (`yeet run `).
- Run Docker images or Compose stacks on a remote host
- Push locally-built images into an internal registry when you need them
- Manage service lifecycle (start/stop/restart/logs/status)
- Push updates over Tailscale RPC
- Support a few networking modes used in my lab (e.g., Tailscale, macvlan)
## Docker Quickstart (Most Common Path: Compose)
Host terminology: `yeet init root@` uses the SSH **machine host**. `yeet run @` (and `CATCH_HOST`) uses the **catch host** (Tailscale/tsnet hostname).
```bash
yeet init root@
yeet run ./compose.yml
yeet ssh
```
Note: from a repo checkout, `yeet init` builds and uploads `catch`. Released yeet binaries (or `--from-github`) download the latest stable release; add `--nightly` for nightly builds.
Note: `yeet run` for compose does not pull new images by default. To refresh images, use `yeet run --pull ./compose.yml` or `yeet docker update `.
Note: Docker hosts must enable the containerd snapshotter so pushed images show up locally (see Installation in the docs).
Other common variants (in order of use):
```bash
yeet run ./Dockerfile
yeet run ./bin/ -- --app-flag value
```
Less common (registry image or pushing a local image):
```bash
yeet run nginx:latest
yeet docker push : --run
```
## Tailscale OAuth Setup
If you use `--net=ts` for service networking, configure an OAuth client secret
on the catch host:
```bash
yeet tailscale --setup
# or
yeet tailscale --setup --client-secret=tskey-client-...
```
The interactive flow links you to the admin console steps for creating a tag
and trust credential, then writes the secret to the catch host for you.
## Documentation
The docs site is the user manual and the source of truth for behavior and workflows:
- [Quick Start](https://yeetrun.com/docs/getting-started/quick-start)
- [Workflows](https://yeetrun.com/docs/operations/workflows) (Docker-first walkthroughs)
- [Installation](https://yeetrun.com/docs/getting-started/installation)
- [Architecture](https://yeetrun.com/docs/concepts/architecture)
- [CLI Overview](https://yeetrun.com/docs/cli/cli-overview)
- [yeet CLI](https://yeetrun.com/docs/cli/yeet-cli)
- [catch CLI](https://yeetrun.com/docs/cli/catch-cli)
- [Networking](https://yeetrun.com/docs/concepts/networking)
- [Tailscale](https://yeetrun.com/docs/concepts/tailscale)
- [Service Types](https://yeetrun.com/docs/concepts/service-types)
- [Configuration & Prefs](https://yeetrun.com/docs/concepts/configuration-and-prefs)
- [Data Layout](https://yeetrun.com/docs/concepts/data-layout)
- [Troubleshooting](https://yeetrun.com/docs/operations/troubleshooting)
- [Development](https://yeetrun.com/docs/development)
- [FAQ](https://yeetrun.com/docs/faq)
## Components
- **yeet**: client CLI used from my workstation (see the [yeet CLI](https://yeetrun.com/docs/cli/yeet-cli) reference)
- **catch**: service manager daemon running on homelab hosts (see the [catch CLI](https://yeetrun.com/docs/cli/catch-cli) reference)
## How I Run It
In my homelab, I run `catch` on each host and use `yeet` to push binaries/images, manage versions, and poke at service state over Tailscale. The [Networking](https://yeetrun.com/docs/concepts/networking) and [Configuration & Prefs](https://yeetrun.com/docs/concepts/configuration-and-prefs) pages describe the host targeting and network modes that make this work in my lab. The workflow is optimized for my machines and my network topology, not for general compatibility.
## Security Notes
Currently, services managed by `catch` run as root. This is fine for my lab, but it is not a good default for production or multi-tenant setups. See the [FAQ](https://yeetrun.com/docs/faq) for current limitations.
## License
BSD 3-Clause. See `LICENSE`.