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) |
.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) |
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) |
AppArmorProfile | From security.apparmor | AppArmor profile (conditional, e.g. "unconfined") |
AddDevice | /dev/dri | GPU (conditional on gpu=true or gpu="auto" with DRI present) |
AddDevice | -/dev/nvidiactl, -/dev/nvidia0 | NVIDIA GPU (conditional on gpu="nvidia" or gpu="auto" with NVIDIA present) |
AddDevice | -/dev/nvidia-uvm | NVIDIA UVM (conditional, when available) |
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) |
SshAgent | default | SSH agent passthrough (conditional on ssh_agent, requires Podman ≥ 5.6) |
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) |
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, LC_ALL, LC_CTYPE | From host locale | Locale (conditional) |
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/localtime | /etc/localtime | ro | File exists on host |
/etc/timezone | /etc/timezone | ro | File exists on host |
| 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 |
| 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) |
| Extra mounts | Per config | Per config | From [container.mounts].extra |
PodmanArgs=
| Arg | Notes |
|---|
--init | catatonit as PID 1 (zombie reaping) |
--workdir=/home/%u | Default working directory |
--cap-add=<cap> | Per security.cap_preset + security.cap_add (conditional) |
[Service]
| Key | Value | Notes |
|---|
Restart | on-failure | Auto-restart on crash |
RestartSec | 2s | Delay between restarts |
AutoRemove | true | Only when lifecycle.on_stop = "remove" |
[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:
1[Unit]
2Description=podbox host socket server -- <name>
3
4[Service]
5Type=simple
6ExecStart=<podbox> serve <name>
7Restart=on-failure
8RestartSec=2s
9RuntimeDirectory=podbox
10
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.
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 | Warns and skips | SshAgent=default + Environment= | SshAgent=default + Environment= |
| 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
%t is the systemd specifier for $XDG_RUNTIME_DIR — never substitute it.%h is the systemd specifier for the user's home — never substitute it.%U / %G expand 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). - Custom systemd units (
.socket, -host.service, etc.) always go in ~/.config/systemd/user/. - Re-running
podbox enable is safe — it uses --replace to overwrite existing Quadlet files idempotently.