Configuration

Full schema for yoink.yaml. Canonical source: yoink/src/config.rs.

Top level

Host

Each host needs an address; that can be either a literal address: or, for cases where the address itself is sensitive (a public IP that you front through Cloudflare, a tailnet hostname you'd rather not commit), a sealed-secret reference via address_secret:. Set exactly one; neither or both is rejected at config load.

hosts:
  - { address: prod-eu-1, user: deploy }
  - { address: prod-us-1, user: deploy }

  # Deploy-key-in-repo flavour (for fresh VPS hosts without
  # ssh-agent already configured for them):
  - address: 1.2.3.4
    user: root
    ssh_key_secret: PROD_HOST_SSH_KEY

  # Address-in-repo-too flavour: the IP lives in `secrets.age`,
  # never in the committed yaml. Resolved at deploy time.
  - address_secret: DOCS_HOST_IP
    user: deploy
    ssh_key_secret: DOCS_DEPLOY_SSH_KEY

yoink hosts add --address-secret <KEY> --user <USER> --name <NAME> writes the sealed-address fragment shape. --name is required (no literal address to derive a fragment filename from).

Deploy

Secrets

Two providers, selected by the provider: tag.

provider: age (default, batteries-included)

A single sealed dotenv file committed alongside yoink.yaml, decrypted at deploy time with the operator's age identity (private half) resolved in priority order:

1. YOINK_AGE_KEY env (raw key): CI / managed-env contexts
2. YOINK_AGE_KEY_FILE env (path): explicit override
3. ~/.config/yoink/keys/*.key: laptop default; yoink scans the dir and picks whichever key's public half matches one of recipients: below
4. ~/.config/yoink/age.key: legacy single-key fallback

The keys-dir scan (#3) is what makes yoink secrets key generate work without per-project env-var setup; multiple projects with distinct identities coexist there, picked by recipient match.

The recipient/identity split is the asymmetric-keypair mental model; see Sealed secrets (age) in the secrets guide for the full explanation.

Secrets profiles

A profile names "what env shape does one downstream tool expect" and lets the same recipe drive both an operator shell (Taskfile, CI workflow) and a yoink pre-deploy hook. Without profiles, the same bundle-key → env-var-name mapping is hand-encoded in N Taskfiles plus N CI workflows, with a separate unset block per consumer for env-leak cleanup; profiles consolidate it next to the bundle that supplies the values.

SecretsProfile

Profile names must match [a-z0-9-]+ (lowercase letters, digits, hyphens).

secrets:
  provider: age
  recipients: [age1…]
  profiles:
    terraform-cloudflare:
      include: [CLOUDFLARE_API_TOKEN,
                TFSTATE_B2_KEY_ID, TFSTATE_B2_APPLICATION_KEY]
      rename:
        TFSTATE_B2_KEY_ID:          AWS_ACCESS_KEY_ID
        TFSTATE_B2_APPLICATION_KEY: AWS_SECRET_ACCESS_KEY
      unset: [B2_ENDPOINT, B2_BUCKET_NAME]

Use it from a Taskfile:

env:
  YOINK_TF:
    sh: cd ../../deploy-prod && yoink secrets env --profile terraform-cloudflare
tasks:
  tf:plan:
    cmds:
      - eval "$YOINK_TF" && terraform plan

Or from a yoink pre-deploy hook (subprocess flavor — runs on the operator's machine):

hooks:
  pre_deploy:
    - name: cloudflare-tf-apply
      working_dir: ../terraform/cloudflare
      cmd: ["sh", "-c",
            "terraform init -input=false && terraform apply -auto-approve"]
      secrets_profile: terraform-cloudflare

The profile's unset: applies on subprocess hooks (yoink calls Command::env_remove for each entry); container hooks reject it because there's no parent env to clear. See Run Terraform from a hook for the full walkthrough.

In CI, when GITHUB_ENV is set in the environment, yoink secrets env auto-prepends echo '::add-mask::<value>' lines for every revealed value — no per-key copy-paste needed; new keys added to the profile are masked automatically.

Bootstrap: yoink secrets key generate writes a fresh identity to ~/.config/yoink/keys/<recipient>.key (mode 0600) by default and prints the matching recipient (age1…, public; paste into recipients: above). --out PATH writes to a specific file at mode 0600 instead. --print sends the secret to stdout for piping into a CI secret store (… --print | gh secret set YOINK_AGE_KEY). yoink secrets key public re-derives the recipient from whichever identity yoink would use right now (handy "is the key in my shell the same one yoink.yaml expects?" check). See the secrets guide.

provider: command (bring-your-own-tool)

Yoink invokes the configured command and reads a secrets bundle from stdout. Format auto-detects between dotenv and JSON. Lets operators wire any external manager (Doppler, 1Password, HashiCorp Vault, AWS Secrets Manager, the Infisical CLI, Bitwarden, …) without yoink growing first-party integrations for each.

secrets:
  provider: command
  command: ["doppler", "secrets", "download", "--no-file", "--format", "env"]

See the secrets guide for per-tool wiring.

Registry

Yoink resolves these at deploy time and passes them as X-Registry-Auth on every pull.

Proxy

The bundled Caddy reverse proxy. See the proxy guide for the full operator-side picture.

Xcaddy

Builds a custom caddy on each proxy host using xcaddy. Content-addressed by build inputs, tagged locally as yoink-caddy:<hash>; subsequent up runs short-circuit until plugins or version change. No registry needed.

ProxyTls

When set, every routed service uses this cert by default. Per-service tls_cert_secret: / tls_key_secret: overrides remain available for the rare different-cert-per-service case. :80 → :443 redirect auto-emitted.

ClientAuth

Service

Build

Run

RunOptions

The hardened defaults make new containers prod-safe out of the box. Override per-service when needed.

See Security defaults for the full picture.

Hooks

Two places hooks live:

• Per-service services[].pre_deploy: runs before that service's wave starts (so a database migration finishes before the api container that depends on it is even pulled). Once per up, on the first host that has the service.
• Top-level hooks.pre_deploy: runs before any service-wave starts. Once per up, on the first host overall. Use for cluster-wide concerns that don't belong to a single service.

hooks:
  pre_deploy:
    - name: cluster-bootstrap
      image: my/bootstrap-tool
      tag: v1

Both shapes use the same Hook entry shape below. A non-zero exit aborts the deploy before the swap; the old container stays live.

Hook

A hook runs in one of two flavors, distinguished by the presence of image::

• Container hook (image: + tag: set): yoink pulls the image and runs cmd: inside docker on the first host. Use for pinned tool images or isolation from the operator's filesystem.
• Subprocess hook (no image:, no tag:): yoink invokes cmd[0] directly on the operator's machine (or the CI runner). Inherits the parent env. Use for tools already on PATH (terraform, dbmate, alembic, gcloud, …) — see Run Terraform from a hook.

Webhooks

Outbound HTTP calls fired on RunStarted / RunFinished. Operator-side: the request goes from the box running yoink up, not from each host. Best-effort: every fire records a WebhookFired audit event whose ok field carries the outcome; a failure never aborts the deploy. See Notify chat / paging / observability on deploy for templating, secrets, and worked receiver examples (ntfy, Slack, Grafana).

webhooks:
  - name: slack-deploys
    url: "https://hooks.slack.com/${secret:SLACK_WEBHOOK_PATH}"
    on: [run_succeeded, run_failed]
    headers:
      Content-Type: application/json
    body: '{ "text": "{{ command }} {{ services | join(\", \") }}{% if error %} — {{ error }}{% endif %}" }'

Templating runs in two passes per field: ${secret:NAME} literal substitution from the sealed bundle, then minijinja rendering with UndefinedBehavior::Strict. Available template variables: event, ok, command, services, deploy_id, actor, host, git_sha, yoink_version, error, ts. See Notify chat / paging / observability on deploy: Template context for the full table.

Tag overrides at deploy time

Any service or hook with tag: unset (or set to a literal that you want to override) accepts --tag at the CLI:

yoink up --tag api=$(git rev-parse HEAD) --tag web=$(git rev-parse HEAD)

tag: { service: api } mirrors the runtime tag, useful for pre_deploy migrations that must use the exact image being deployed.

Includes

include: globs are resolved relative to the config file's directory. Each matched file is parsed as a partial config; only services: and hooks.pre_deploy: are permitted in fragments and they merge into the entry config's lists. All other top-level fields (hosts, deploy, secrets, registry, proxy, slug) belong only in the entry config.

# yoink.prod.yaml
hosts: [...]
deploy: { networks: [...] }
include:
  - services/prod/*.yaml

# services/prod/api.yaml
services:
  - name: api
    image: ghcr.io/you/api
    # ...

Environment-variable substitution

Any ${VAR} reference in yoink.yaml (or in a fragment loaded via include:) is substituted against the process environment at config-load time, before YAML parsing.

hosts:
  - address: ${HOST_IP}
    user: root
services:
  - name: hello
    domain:
      - ${HOST_IP}.nip.io

Run with HOST_IP=1.2.3.4 yoink up …. Useful for throwaway-host recipes, ephemeral preview environments, and any other case where one of the values isn't known until invocation time.

Rules:

• Only the unambiguous ${NAME} form is recognized. Bare $NAME and lone $ characters pass through unchanged so values containing literal dollar signs are unaffected.
• NAME must match [A-Za-z_][A-Za-z0-9_]*. Anything else (including ${HOST-IP}, ${1BAD}, or unterminated ${) errors with a snippet pointing at the bad reference.
• Missing variables are a hard error rather than silent empty substitution; a quietly-empty address: produces baffling failures further down the deploy.
• The POSIX ${NAME:-default} form supplies a fallback when NAME is unset. Useful for commands that parse the full config but don't actually use the value (e.g. yoink secrets seal against a config whose hosts/domains reference ${HOST_IP}). Set the var explicitly when you do mean to use it.
• For long-lived secrets, prefer secrets: (sealed or provider: command) over passing values via env. The substitution path is intended for routing parameters (host IPs, hostnames, port numbers), not credentials.

See also

• CLI reference — every subcommand and flag.
• Examples — three complete annotated yoink.yamls (hobby, polyglot, production).
• Secrets — the mental model behind the secrets: block.
• Reverse proxy — the schema and behavior of the proxy: block.