# yoink > A small, opinionated container deploy CLI + TUI for people who run a handful of services on a handful of VPS or bare-metal hosts. yoink is one binary that connects to hosts over SSH and drives Docker. Its whole interface is the `yoink` CLI and a `yoink.yaml` file in the repo. Every link below is the Markdown source of a docs page. ## If you are an agent asked to deploy a repo 1. Install: `brew install oddur/yoink/yoink` (other methods: https://yoink.is/llms.mdx/docs/how-to/install/content.md). 2. Follow the first deploy: https://yoink.is/llms.mdx/docs/tutorials/first-deploy/content.md. 3. Edit `yoink.yaml`, then run `yoink up --dry-run --format=markdown` and show the operator the diff before applying. 4. Apply with `yoink up`. A failed healthcheck-gated swap exits non-zero. 5. Verify with `yoink status`. Roll back with `yoink rollback `. 6. Read the limits first: https://yoink.is/llms.mdx/docs/explanation/ai-agents/content.md. `yoink tui` is for humans, and `yoink secrets edit` opens `$EDITOR`. The full docs in one file: https://yoink.is/llms-full.txt ## Tutorials - [Tutorials](https://yoink.is/llms.mdx/docs/tutorials/content.md): Three lessons that each take you along one fixed path to a working deploy. - [First deploy](https://yoink.is/llms.mdx/docs/tutorials/first-deploy/content.md): Go from a new host to a running container in five minutes with yoink init and yoink up. - [Hetzner → HTTPS in ~90 seconds](https://yoink.is/llms.mdx/docs/tutorials/hetzner-quickstart/content.md): Provision a Hetzner cx23, get a real Let's Encrypt cert through nip.io, and reach a live HTTPS endpoint in approximately 90 seconds. - [TanStack Start + postgres from scratch](https://yoink.is/llms.mdx/docs/tutorials/tanstack-stack/content.md): Scaffold a TanStack Start app, add postgres with yoink add, deploy, and open the app with yoink pf. ## How-to guides - [How-to guides](https://yoink.is/llms.mdx/docs/how-to/content.md): Each guide gives the steps for one task, from the goal to a result that runs in production. ### Setup - [Install](https://yoink.is/llms.mdx/docs/how-to/install/content.md): Install yoink with Homebrew, Cargo, curl, or a pre-built binary. Each method puts the same single binary on your PATH. - [Connect to a host over SSH](https://yoink.is/llms.mdx/docs/how-to/ssh-access/content.md): Give yoink SSH access to a host that has a root password, a non-default key, a deploy key in the repo, Tailscale, or a local VM. - [Provision a Hetzner host with HTTPS](https://yoink.is/llms.mdx/docs/how-to/hetzner-https-host/content.md): Provision a Hetzner cx23 and deploy a service behind HTTPS with one block of commands, then change it for your app or your hostname. - [Add dynamic shell completion](https://yoink.is/llms.mdx/docs/how-to/dynamic-shell-completion/content.md): Connect the hidden __complete helper to Bash or Zsh so that TAB completes service names, host addresses, and config files. ### Secrets & Security - [Sealed secrets workflow](https://yoink.is/llms.mdx/docs/how-to/sealed-secrets-workflow/content.md): Generate an AGE keypair, seal values into the repo, use them at deploy time, and rotate or share them between environments. - [AGE secrets in GitHub Actions](https://yoink.is/llms.mdx/docs/how-to/age-in-github-actions/content.md): Generate a CI-only AGE identity, put it into a GitHub secret, and deploy from Actions with one environment variable. - [Read secrets from an external secret manager](https://yoink.is/llms.mdx/docs/how-to/external-secrets/content.md): Config for provider command with sops, Doppler, Infisical, Vault, AWS Secrets Manager, 1Password, Bitwarden, and a plain dotenv file. - [Cloudflare Origin Certificates](https://yoink.is/llms.mdx/docs/how-to/cloudflare-origin-certs/content.md): Issue a 15-year Cloudflare Origin Certificate and lock your origin to Cloudflare's edge with Authenticated Origin Pulls. - [Defense-in-depth web serving (Cloudflare + CrowdSec + Coraza)](https://yoink.is/llms.mdx/docs/how-to/defense-in-depth/content.md): Deploy a hardened web stack with no license fee from Cloudflare Free, CrowdSec, Coraza WAF, and sealed origin certificates. - [Relax a hardened default for one service](https://yoink.is/llms.mdx/docs/how-to/relax-security-defaults/content.md): Find the hardened default that stops an image, and override only that field for only that service. - [Pass host devices into a container](https://yoink.is/llms.mdx/docs/how-to/hardware-passthrough/content.md): Give one service access to a GPU, a USB device, FUSE, a webcam, or a TPM, and keep the other hardened defaults. ### Deploy Patterns - [Standalone (no-registry) deploys](https://yoink.is/llms.mdx/docs/how-to/standalone-mode/content.md): Ship images directly to hosts over SSH with no registry, with layer-level dedup from the bundled unregistry transport. - [Build locally and deploy through a registry](https://yoink.is/llms.mdx/docs/how-to/local-build-push/content.md): Build an image on your machine, push it to a registry, and deploy it with yoink. - [Run staging alongside prod](https://yoink.is/llms.mdx/docs/how-to/staging-alongside-prod/content.md): Run a staging environment on the same hosts as production with separate configs that have namespaced services and networks. - [Distribute services across hosts](https://yoink.is/llms.mdx/docs/how-to/multi-host-distribution/content.md): Set replicas and services[].hosts to scale a stateless app, run a singleton, pin a stateful service, or run one service for each region. - [Run multiple projects on one host](https://yoink.is/llms.mdx/docs/how-to/multiple-projects-one-host/content.md): Use one yoink.yaml for each host and include the service fragments of each project repo. - [Edit-save-deploy with `--watch`](https://yoink.is/llms.mdx/docs/how-to/watch-mode/content.md): Poll the config for changes and deploy again automatically on every save, for hot reload in prod-like local development. - [Pre-merge dry-run on every PR](https://yoink.is/llms.mdx/docs/how-to/pr-comment-dry-run/content.md): Post a sticky GitHub PR comment that shows what yoink up changes before the merge. - [Run Terraform (or any infra glue) from a hook](https://yoink.is/llms.mdx/docs/how-to/terraform-from-hooks/content.md): Provision DNS, certificates, databases, or other external resources in a pre-deploy hook that runs on your computer and reads the sealed bundle through a secrets profile. - [Self-hosted registry on a yoink host](https://yoink.is/llms.mdx/docs/how-to/self-hosted-registry/content.md): Run registry:2 as a yoink-managed service, expose it over the tailnet, and push images to it. ### Templates - [Adding a service via `yoink add`](https://yoink.is/llms.mdx/docs/how-to/using-templates/content.md): Select a vetted template such as postgres, redis or meilisearch, answer the prompts, and get a service fragment with sealed secrets. - [Write a template for `yoink add`](https://yoink.is/llms.mdx/docs/how-to/write-a-template/content.md): Create a template manifest and a service template, add the template from a branch, and correct permission failures on the first deploy. - [Publish a template](https://yoink.is/llms.mdx/docs/how-to/publish-a-template/content.md): Choose a repo layout for a yoink add template, tell consumers which ref to pin, and submit a template to the bundled set. ### Networking & Proxy - [Add HTTPS to a service](https://yoink.is/llms.mdx/docs/how-to/add-https/content.md): Give a deployed service a public domain and a Let's Encrypt cert through the bundled Caddy proxy. - [gRPC hosting](https://yoink.is/llms.mdx/docs/how-to/grpc-hosting/content.md): Expose a native gRPC backend (Tonic, grpc-go, grpc-java) with upstream_h2c, which also works for REST. - [Caddy plugins (xcaddy, no registry)](https://yoink.is/llms.mdx/docs/how-to/caddy-plugins/content.md): Build a custom Caddy binary with rate-limit, l4, redis-storage, and third-party DNS providers on each host, with no registry. - [Caddy snippets cookbook](https://yoink.is/llms.mdx/docs/how-to/caddy-snippets/content.md): Caddyfile and JSON snippets for forward auth, basic auth, IP allowlist, custom headers, redirects, and maintenance pages. - [Debug a service with a port-forward](https://yoink.is/llms.mdx/docs/how-to/port-forward/content.md): Open a tunnel from your laptop to a container port with yoink pf, from the CLI or the TUI, and close it again. ### Storage & Backup - [Volume backups with restic](https://yoink.is/llms.mdx/docs/how-to/volume-backups/content.md): Nightly restic snapshots to any S3-compatible backend, and postgres WAL archiving for point-in-time recovery. - [Multi-host Let's Encrypt with Redis storage](https://yoink.is/llms.mdx/docs/how-to/multi-host-redis-storage/content.md): Share ACME certificate state across hosts through Redis to stay below the Let's Encrypt rate limits. ### Operations - [Read the audit log](https://yoink.is/llms.mdx/docs/how-to/audit-log/content.md): Merge the operator-side and on-host JSONL logs to see every state change that yoink made, also for deploys whose containers no longer exist. - [Auto-heal unhealthy containers](https://yoink.is/llms.mdx/docs/how-to/auto-heal/content.md): Restart the containers that Docker marks unhealthy with a small sidecar, without a yoink subcommand or a template. - [Notify chat / paging / observability on deploy](https://yoink.is/llms.mdx/docs/how-to/notify-on-deploy/content.md): Send HTTP webhooks with templated bodies and sealed credentials to ntfy, Slack, Grafana, or a different receiver when a run starts or finishes. ### Developer Tooling - [Edit container files with `yoink vscode`](https://yoink.is/llms.mdx/docs/how-to/vscode/content.md): Open VS Code in the browser on the live filesystem of a running container, with only SSH and a browser on your computer. - [Drive yoink from an AI agent](https://yoink.is/llms.mdx/docs/how-to/drive-yoink-from-an-agent/content.md): Give an AI coding agent a deploy change, preview the diff, apply it, and roll back if the rollout fails. ### When it fails - [Troubleshooting](https://yoink.is/llms.mdx/docs/how-to/troubleshooting/content.md): Common error messages, their causes, and the steps to correct them. ## Reference - [Reference](https://yoink.is/llms.mdx/docs/reference/content.md): Lookup pages for every CLI flag, config field, TUI keybind, and audit event. ### Commands - [CLI](https://yoink.is/llms.mdx/docs/reference/cli/content.md): Every subcommand, flag, and tag-resolution rule, with the diagnostic commands yoink doctor and yoink status. - [Commands for agents](https://yoink.is/llms.mdx/docs/reference/agent-commands/content.md): The yoink subcommands that an AI coding agent uses most. - [TUI](https://yoink.is/llms.mdx/docs/reference/tui/content.md): The keybind tables for every TUI pane, the log piping, and the drift detail view. - [`yoink add` and the bundled templates](https://yoink.is/llms.mdx/docs/reference/yoink-add/content.md): The sequence that yoink add runs for a template, and the list of templates that ship with yoink. - [Port-forward reference](https://yoink.is/llms.mdx/docs/reference/port-forward/content.md): The argument forms, modes, errors, TUI keys, row markers, and guarantees of yoink pf. - [yoink vscode sidecar](https://yoink.is/llms.mdx/docs/reference/vscode-sidecar/content.md): The flags of yoink vscode, the properties of its sidecar container, and the filesystem view of the editor. ### Config - [Configuration](https://yoink.is/llms.mdx/docs/reference/config/content.md): The complete yoink.yaml schema with every field, its type, and its default. - [Proxy config](https://yoink.is/llms.mdx/docs/reference/proxy/content.md): The per-service proxy fields and the top-level proxy block, with the handler order, the merge rules, and the xcaddy build behavior. - [xcaddy build reference](https://yoink.is/llms.mdx/docs/reference/xcaddy/content.md): Image tags, labels, rebuild rules, and the generated Dockerfile of the proxy.xcaddy build, with a list of Caddy plugins. - [Secrets resolution and bundle formats](https://yoink.is/llms.mdx/docs/reference/secrets/content.md): The order in which yoink finds an age identity, the rules for provider command, and the dotenv and JSON bundle formats. - [Security defaults](https://yoink.is/llms.mdx/docs/reference/security-defaults/content.md): The default value, the effect, and the opt-out of each hardened run option, with the devices syntax and its validation rules. - [Webhooks](https://yoink.is/llms.mdx/docs/reference/webhooks/content.md): Triggers, template variables, fields, secret substitution, and error values for the webhooks block. - [Template manifest](https://yoink.is/llms.mdx/docs/reference/template-manifest/content.md): The fields of template.yaml for yoink add, the rules for variables, files and secrets, and how template refs resolve. ### Behavior - [Deploy mechanics](https://yoink.is/llms.mdx/docs/reference/deploy-mechanics/content.md): The inputs of spec_hash, the deploy lock parameters, the secrets lookup order, the prune rules, and the container host config that yoink builds. - [Audit event schema](https://yoink.is/llms.mdx/docs/reference/audit-event-schema/content.md): The JSON fields of each event variant in /var/lib/yoink/audit/events.jsonl. - [Audit log coverage](https://yoink.is/llms.mdx/docs/reference/audit-log-coverage/content.md): The operations that yoink records in the audit log and the operations that it does not record. - [Glossary](https://yoink.is/llms.mdx/docs/reference/glossary/content.md): Definitions of the terms that occur across the docs, for example spec_hash, unregistry, provider: age, and yoink-ingress. ### Example configs - [Examples](https://yoink.is/llms.mdx/docs/reference/examples/content.md): Three complete annotated yoink.yaml configs for a hobby tool, a polyglot stack, and production. - [Hobby tool / utility](https://yoink.is/llms.mdx/docs/reference/examples/hobby-tool/content.md): A yoink.yaml for one host and one service that builds locally with no registry. This is the minimal config. - [Polyglot stack](https://yoink.is/llms.mdx/docs/reference/examples/polyglot-stack/content.md): A Rust API, a Node web frontend, Caddy, and Redis on a single host with per-tier networks. - [Production-shape](https://yoink.is/llms.mdx/docs/reference/examples/production/content.md): A full production config with multiple hosts, replicas, sealed secrets, pre-deploy hooks, and drift detection. ## Explanation - [Explanation](https://yoink.is/llms.mdx/docs/explanation/content.md): Why yoink works the way it does: the design choices, the trade-offs, and the comparison with other tools. ### About yoink - [What & why](https://yoink.is/llms.mdx/docs/explanation/what-and-why/content.md): What yoink does, why it exists, and who it is for. - [Compared to other tools](https://yoink.is/llms.mdx/docs/explanation/compared/content.md): A side-by-side comparison of yoink with Kamal, Kubernetes, Dokku, Coolify, and plain docker compose. - [yoink and AI agents](https://yoink.is/llms.mdx/docs/explanation/ai-agents/content.md): Why a CLI, YAML files, and deterministic exit codes let Claude Code, Cursor, Aider, and GitHub Copilot Workspace operate yoink. ### How it works - [How it works](https://yoink.is/llms.mdx/docs/explanation/architecture/content.md): How yoink works internally: drift detection with spec_hash, the deploy lock, rolling swaps that a healthcheck gates, and deploys in dependency order. - [Deploy modes](https://yoink.is/llms.mdx/docs/explanation/deploy-modes/content.md): The three ways to ship an image: CI-built from a registry, local-build shipped directly, and mixed. - [Image shipping: transports and trade-offs](https://yoink.is/llms.mdx/docs/explanation/image-shipping/content.md): How yoink ships an image without a registry, how the unregistry and tarball transports work, and where a self-hosted registry fits. - [Pre-deploy hooks](https://yoink.is/llms.mdx/docs/explanation/hooks/content.md): Why 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` polls](https://yoink.is/llms.mdx/docs/explanation/watch-polling/content.md): Why yoink up --watch polls the config on a 2 s tick and does not use a file watcher, and what that costs. ### Security & secrets - [Security](https://yoink.is/llms.mdx/docs/explanation/security/content.md): Why yoink hardens every container by default, why each opt-out is explicit, and why device passthrough replaces privileged mode. - [Secrets](https://yoink.is/llms.mdx/docs/explanation/secrets/content.md): How 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 layer](https://yoink.is/llms.mdx/docs/explanation/defense-in-depth/content.md): What 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 proxy](https://yoink.is/llms.mdx/docs/explanation/proxy/content.md): How the bundled Caddy proxy puts a service on HTTPS from one field, and why yoink owns the routing change. - [How yoink builds Caddy plugins](https://yoink.is/llms.mdx/docs/explanation/xcaddy-builds/content.md): Why yoink compiles a custom Caddy on each proxy host, when it rebuilds, and what the build costs. - [Cloudflare Origin Certificates and Let's Encrypt](https://yoink.is/llms.mdx/docs/explanation/cloudflare-origin-certs/content.md): Why an origin behind Cloudflare can use an Origin Certificate in place of Let's Encrypt, and how that choice behaves on many hosts. - [Networking](https://yoink.is/llms.mdx/docs/explanation/networking/content.md): How yoink reaches hosts through SSH and Tailscale, how services spread across hosts, and how yoink pf debugs a service without a published port. ### Templates & storage - [Templates (`yoink add`)](https://yoink.is/llms.mdx/docs/explanation/templates/content.md): What a yoink add template is, how it handles secrets and hardening, and how template versions resolve. - [How volume backups work](https://yoink.is/llms.mdx/docs/explanation/volume-backups/content.md): The design of the restic backup service, why restic dedup makes off-site backups cheap, and how postgres WAL archiving closes the gap between snapshots.