Explanation
Why yoink works the way it does: the design choices, the trade-offs, and the comparison with other tools.
These pages give the reasons for the design of yoink. yoink is a small, opinionated container deploy CLI and TUI. It is for people who run a small number of services on a small number of bare-metal hosts.
About yoink
- What & whyWhat yoink does, why it exists, and who it is for.
- Compared to other toolsA side-by-side comparison of yoink with Kamal, Kubernetes, Dokku, Coolify, and plain docker compose.
- yoink and AI agentsWhy a CLI, YAML files, and deterministic exit codes let Claude Code, Cursor, Aider, and GitHub Copilot Workspace operate yoink.
How it works
- How it worksHow yoink works internally: drift detection with spec_hash, the deploy lock, rolling swaps that a healthcheck gates, and deploys in dependency order.
- Deploy modesThe three ways to ship an image: CI-built from a registry, local-build shipped directly, and mixed.
- Image shipping: transports and trade-offsHow yoink ships an image without a registry, how the unregistry and tarball transports work, and where a self-hosted registry fits.
- Pre-deploy hooksWhy yoink runs infra glue as a pre-deploy hook, how the subprocess and container flavors differ, and how hooks relate to drift detection.
- Why --watch pollsWhy yoink up --watch polls the config on a 2 s tick and does not use a file watcher, and what that costs.
Security & secrets
- SecurityWhy yoink hardens every container by default, why each opt-out is explicit, and why device passthrough replaces privileged mode.
- SecretsHow yoink resolves secrets at deploy time, what the age-sealed file protects, and when an external secret manager is the better fit.
- Defense-in-depth web serving, layer by layerWhat Cloudflare Free, CrowdSec, and Coraza each add to a public-facing service, and why the yoink config for the stack has its shape.
Proxy & networking
- Reverse proxyHow the bundled Caddy proxy puts a service on HTTPS from one field, and why yoink owns the routing change.
- How yoink builds Caddy pluginsWhy yoink compiles a custom Caddy on each proxy host, when it rebuilds, and what the build costs.
- Cloudflare Origin Certificates and Let's EncryptWhy an origin behind Cloudflare can use an Origin Certificate in place of Let's Encrypt, and how that choice behaves on many hosts.
- NetworkingHow yoink reaches hosts through SSH and Tailscale, how services spread across hosts, and how yoink pf debugs a service without a published port.