command-center/agent/managed-skills/quadlet-v1-generator-quirks/SKILL.md

name, description

name	description
quadlet-v1-generator-quirks	When writing or deploying Quadlet .container units on podman 5.x (v1 generator, e.g. Dankclaw), avoid keys the v1 generator hard-fails on and verify generated ExecStart before starting; generated units cannot be enabled.

Quadlet v1 generator quirks (podman 5.x)

The podman 5.x user generator (/usr/lib/systemd/user-generators/podman-user-generator, quadlet v1) behaves differently from the v4 docs. Verified live on Dankclaw 2026-08-28 while deploying the authentik trio.

Hard-fail keys (unit silently fails to generate — systemctl --user cat <unit> shows "could not be found")

• Any dash-prefixed option line in [Container]: --shm-size=512m etc. → generator logs unsupported key '--shm-size' in group 'Container' and skips the whole unit. Omit them; accept podman defaults.
• Command= is unsupported — use Exec= (that is what this generator accepts).

HealthCmd space-splitting

The v1 generator splits HealthCmd on spaces into the healthcheck argv array (podman inspect --format {{.Config.Healthcheck.Test}} <ctr> shows [CMD-SHELL pg_isready -d ... ]). A quoted probe like /bin/sh -c "pg_isready ..." lands as argv token "pg_isready → command-not-found → container reads unhealthy while the DB is actually up. Rule: HealthCmd must contain only space-free argv tokens, e.g. HealthCmd=pg_isready -d authentik -U authentik or python /manage.py check --database default.

Generated units cannot be enabled

systemctl --user enable <generated-unit> fails with "unit is transient or generated". Boot persistence comes from [Install] WantedBy=default.target inside the .container file, honored by the generator at user-manager start; linger must stay on for the deploy user. Deploy handlers: install unit → systemctl --user daemon-reload → systemctl --user start; no enable.

Probe a new key before shipping it

Drop a throwaway probe.container into ~/.config/containers/systemd/, systemctl --user daemon-reload, then check the generator verdict:

journalctl --user --since "1 min ago" -o cat | grep -i "unsupported key"
systemctl --user cat probe.service   # shows the generated ExecStart verbatim
rm ~/.config/containers/systemd/probe.container && systemctl --user daemon-reload

If a healthcheck ever reads unhealthy but logs look fine, suspect this quirk first: compare the baked Healthcheck.Test array against the intended command before believing the status.