Quadlet reference
These unit files are generated per container:
| File | Path (5.6–5.x) | Path (6.0+) | Purpose |
|---|---|---|---|
<name>.build | ~/.config/containers/systemd/ | ~/.config/containers/systemd/<name>/ | Image build definition |
<name>.container | ~/.config/containers/systemd/ | ~/.config/containers/systemd/<name>/ | Container runtime |
<name>.socket | ~/.config/systemd/user/ | ~/.config/systemd/user/ | Host-guest Unix socket (custom) |
<name>-host.service | ~/.config/systemd/user/ | ~/.config/systemd/user/ | Host socket server (custom) |
<name>-proxy.service | ~/.config/systemd/user/ | ~/.config/systemd/user/ | D-Bus proxy (conditional, custom) |
<name>-compositor.service | ~/.config/systemd/user/ | ~/.config/systemd/user/ | Wayland firewall proxy (conditional, custom) |
<name>-x11.service | ~/.config/systemd/user/ | ~/.config/systemd/user/ | Per-container X11 bridge (conditional, custom) |
.build file
| Key | Value | Notes |
|---|---|---|
ImageTag | localhost/podbox-<name>:latest | Local tag for built image |
File | Absolute path to Containerfile | Must be absolute |
Retry | From image.pull_retry | Pull retry count (default 3) |
RetryDelay | From image.pull_retry_delay | Pull retry delay (default 5s) |
.socket file
| Key | Value | Notes |
|---|---|---|
ListenStream | %t/podbox/<name>.sock | %t = $XDG_RUNTIME_DIR |
Service | <name>-host.service | Activates the host socket server |
SocketMode | 0600 | User-only access |
DirectoryMode | 0700 | Parent dir permissions |
.container file
[Unit]
| Key | Value | Notes |
|---|---|---|
Description | podbox -- <name> | Human-readable name |
Requires | <name>.socket | Socket must be available |
After | <name>.socket | Socket starts first |
Requires | <name>-proxy.service | D-Bus proxy (conditional on [dbus] rules) |
After | <name>-proxy.service | Proxy starts first (conditional) |
Requires | <name>-compositor.service | Wayland firewall (conditional on Wayland proxy) |
After | <name>-compositor.service | Compositor starts first (conditional) |
Wants | <name>-x11.service | Optional X11 bridge (conditional on integration.x11) |
After | <name>-x11.service | X11 bridge is started before the container (conditional) |
Requires | User-defined from [systemd].requires | Custom dependencies |
After | User-defined from [systemd].after | Custom ordering |
StartLimitBurst | 5 | Max restarts in interval |
StartLimitIntervalSec | 30s | Restart burst window |
[Container]
| Key | Value | Notes |
|---|---|---|
Image | Prebuilt ref or localhost/podbox-<name>:latest | Prebuilt images use the registry ref directly; custom builds use local tag |
Retry | From image.pull_retry | Pull retries (prebuilt only) |
RetryDelay | From image.pull_retry_delay | Pull retry delay (prebuilt only) |
ContainerName | <name> | Podman container name |
UserNS | keep-id (default) | User namespace mode (configurable via security.userns: keep-id, nomap, private) |
User | root | Run as root inside the container (UID mapped via UserNS) |
SecurityLabelDisable | true | Required for Wayland socket access |
SeccompProfile | From security.seccomp | Seccomp profile (conditional, e.g. "default", "unconfined") |
NoNewPrivileges | true | Emitted when security.no_new_privileges = true (default). Set false to allow sudo, su, AUR helpers. |
Memory | From container.memory | Memory limit (conditional, e.g. "4G") |
PodmanArgs=--cpus= | From container.cpus | CPU limit (conditional, e.g. "0.5" → --cpus=0.5; Quadlet has no CpuQuota key) |
ReadOnly | true | Read-only rootfs (conditional on security.read_only_rootfs) |
RunInit | true | Always (catatonit as PID 1 for zombie reaping) |
WorkingDir | /home/%u | Always (default working directory) |
AddCapability | From security.cap_preset + security.cap_add | Capabilities (conditional; Quadlet has no CpuQuota key, so --cpus still goes through PodmanArgs) |
AppArmor | From security.apparmor | AppArmor profile (conditional, e.g. "unconfined") |
AddDevice | /dev/dri | GPU (conditional on gpu=true or gpu="auto" with DRI present) |
AddDevice | nvidia.com/gpu=all when a host CDI spec exists, else -/dev/nvidiactl, -/dev/nvidia0…-/dev/nvidia7, -/dev/nvidia-modeset, -/dev/nvidia-uvm, -/dev/nvidia-uvm-tools | NVIDIA GPU passthrough (conditional on gpu="nvidia" or gpu="auto" with NVIDIA present; - marks each fallback node optional, and doctor suggests nvidia-ctk cdi generate for full driver passthrough) |
Network | From network.mode | Network mode (default host) |
PublishPort | From network.ports | Port mapping (conditional, ignored in host mode) |
AutoUpdate | registry or local | Auto-update (conditional on lifecycle.auto_update; registry for prebuilt, local for custom) |
ReloadCmd | From container.reload_cmd | Reload command (conditional) |
Timezone | local | Timezone sync (conditional on host /etc/localtime; replaces the old bind-mount so zone-name lookups keep working) |
Environment= entries
| Variable | Source | Notes |
|---|---|---|
HOME | /home/%u | Always set |
HOST_USER | Host username | Injected into container |
HOST_UID | %U (systemd) | Host UID |
HOST_GID | %G (systemd) | Host GID |
PATH | /run/podbox/bin:... | Interceptor directory prepended |
WAYLAND_DISPLAY | From host env | Wayland display (conditional) |
DISPLAY | :0 | X11 display (conditional on integration.x11; explicit [container.env] DISPLAY wins) |
XDG_RUNTIME_DIR | %t | Always set when Wayland is enabled |
MOZ_ENABLE_WAYLAND | 1 | Wayland-native Firefox/Thunderbird (conditional) |
PIPEWIRE_RUNTIME_DIR | %t | PipeWire runtime dir (conditional) |
PULSE_SERVER | unix:%t/pulse/native | PulseAudio server (conditional) |
DBUS_SESSION_BUS_ADDRESS | Proxy or direct | D-Bus address (conditional) |
SSH_AUTH_SOCK | /run/podbox/ssh-agent.sock | SSH agent (conditional, Podman ≥ 5.6) |
GPG_TTY | /dev/pts/0 | GPG TTY (conditional) |
GNUPGHOME | /run/podbox/gnupg | GPG home (conditional) |
LANG | From host locale | Locale (conditional; LC_* overrides stay with the user) |
PODBOX_CONTAINER | <name> | Always set; identifies the container |
Custom [container.env] entries are also passed as Environment=.
Volume= entries
| Source | Destination | Mode | Condition |
|---|---|---|---|
<context>/.flatpak-info | /.flatpak-info | ro | Always (sandbox detection — tricks apps into using portals) |
%h/containers/<name> | /home/%u | Z | Always (isolated home) |
| XDG dirs | /home/%u/<dir> | ro,z or z | Per [integration.xdg_dirs] |
%h/.themes | /home/%u/.themes | ro | sync_themes + path exists |
%h/.local/share/themes | /home/%u/.local/share/themes | ro | sync_themes + path exists |
%h/.icons | /home/%u/.icons | ro | sync_icons + path exists |
%h/.local/share/icons | /home/%u/.local/share/icons | ro | sync_icons + path exists |
%h/.fonts | /home/%u/.fonts | ro | sync_fonts + path exists |
%h/.local/share/fonts | /home/%u/.local/share/fonts | ro | sync_fonts + path exists |
/etc/timezone | /etc/timezone | ro | File exists on host (Debian convention; /etc/localtime itself is set up via Timezone=local, not a bind-mount) |
| Wayland socket | Wayland socket | ro | wayland = true |
%t/pipewire-0 | %t/pipewire-0 | (none) | audio = true + PipeWire present |
%t/pulse | %t/pulse | (none) | audio = true + PulseAudio present |
| D-Bus socket | D-Bus socket | (none) | dbus = true |
| SSH agent socket | /run/podbox/ssh-agent.sock | (none) | ssh_agent = true + SSH_AUTH_SOCK present on host (plus Environment=SSH_AUTH_SOCK) |
| GPG agent socket | /run/podbox/gnupg/S.gpg-agent | ro | gpg_agent = true |
%t/podbox/<name>.sock | %t/podbox/<name>.sock | (none) | Always (host-guest socket) |
/dev/bus/usb | /dev/bus/usb | (none, never :z) | integration.hardware.usb = true (optional mount: skipped when the host has no USB bus) |
| Extra mounts | Per config | Per config | From [container.mounts].extra |
%t/podbox/<name>-x11 | /tmp/.X11-unix | ro | integration.x11 = true |
PodmanArgs=
Only settings with no native Quadlet key go through PodmanArgs=:
| Arg | Notes |
|---|---|
--cpus=<n> | From container.cpus (conditional; Quadlet has no CpuQuota key, and --cpus also takes fractions like 0.5) |
[Service]
| Key | Value | Notes |
|---|---|---|
Restart | on-failure | Auto-restart on crash |
RestartSec | 2s | Delay between restarts |
Quadlet runs containers with --rm --replace, so every box is ephemeral:
stopping one removes it, and persistent state lives in the home volume and
snapshots. (lifecycle.on_stop is deprecated and emits nothing.)
[Install]
| Key | Value | Notes |
|---|---|---|
WantedBy | default.target | Only when lifecycle.autostart = true |
Companion .service files
<name>-host.service
Generated at ~/.config/containers/systemd/<name>-host.service:
ini
1[Unit]2Description=podbox host socket server -- <name>3 4[Service]5Type=simple6ExecStart=<podbox> serve <name>7Restart=on-failure8RestartSec=2s9RuntimeDirectory=podbox10 11[Install]12WantedBy=<name>.socket<name>-proxy.service (D-Bus proxy)
Generated when [dbus] talk/own rules are configured. See dbus-proxy.md for details.
<name>-compositor.service (Wayland firewall)
Generated when wayland.firewall = true (default). Runs podbox compositor <name> to filter
Wayland protocol access.
<name>-x11.service (xwayland-satellite)
Generated when integration.x11 = true. The host-side satellite connects to
the same filtered or direct Wayland socket used by the container and exposes
an isolated :0 X socket directory:
ini
1[Unit]2Wants=<name>-x11.service3After=<name>-x11.service4 5[Service]6Type=notify7ExecStart=<xwayland-satellite> :08Environment=WAYLAND_DISPLAY=<derived Wayland socket>9PrivateTmp=yes10PrivateNetwork=yes11BindPaths=%t/podbox/<name>-x11:/tmp/.X11-unixThe companion unit is optional at runtime: the container can start if the satellite is unavailable, but X11 applications will not work.
Podman Version Targeting
Podbox targets Podman 5.5+ with feature gating at 5.6 and 6.0.
| Feature | Podman 5.5.x | Podman ≥ 5.6, < 6.0 | Podman ≥ 6.0 |
|---|---|---|---|
ssh_agent | Volume= + Environment=SSH_AUTH_SOCK on all versions | Volume= + Environment=SSH_AUTH_SOCK on all versions | Volume= + Environment=SSH_AUTH_SOCK on all versions |
| Quadlet install | Manual copy into ~/.config/containers/systemd/ | podman quadlet install --replace with file args (flat layout) | podman quadlet install --replace --application <name> <dir> (app-subdir layout) |
| Quadlet uninstall | Manual file remove + systemctl daemon-reload | podman quadlet rm <name>.container (flat) | podman quadlet rm --recursive <name> (app-subdir) + flat fallback |
| Container list | podman ps --filter label=podbox.* | podman quadlet list | podman quadlet list |
Layout by version:
- 5.6–5.x: Units at
…/systemd/<name>.container(flat). - 6.0+: Units at
…/systemd/<name>/<name>.container(app-subdir via--application).
Status, doctor, and start probes check both layouts, so upgrades between versions are transparent.
See podbox doctor to check Podman version compatibility.
Important Notes
%tis the systemd specifier for$XDG_RUNTIME_DIR— never substitute it.%his the systemd specifier for the user's home — never substitute it.%U/%Gexpand to the user's UID and GID at unit start time.- Quadlet files (
.container,.build) go in~/.config/containers/systemd/.- Podman 5.6–5.x: flat layout (
<name>.container). - Podman 6.0+: app-subdir layout (
<name>/<name>.container).
- Podman 5.6–5.x: flat layout (
- Custom systemd units (
.socket,-host.service, etc.) always go in~/.config/systemd/user/. - Re-running
podbox enableis safe — it uses--replaceto overwrite existing Quadlet files idempotently.