Quadlet Keys Used
Four Quadlet/systemd unit files are generated per container:
| File |
Path |
Purpose |
<name>.build |
~/.config/containers/systemd/ |
Image build definition |
<name>.socket |
~/.config/containers/systemd/ |
Host-guest Unix socket |
<name>.container |
~/.config/containers/systemd/ |
Container runtime |
<name>-host.service |
~/.config/containers/systemd/ |
Host socket server |
<name>-proxy.service |
~/.config/containers/systemd/ |
D-Bus proxy (conditional) |
<name>-compositor.service |
~/.config/containers/systemd/ |
Wayland firewall proxy (conditional) |
.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") |
CpuQuota |
From container.cpus × 100000µs |
CPU quota (conditional, e.g. "2.0" → CpuQuota=200000) |
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:
[Unit]
Description=podbox host socket server -- <name>
[Service]
Type=simple
ExecStart=<podbox> serve <name>
Restart=on-failure
RestartSec=2s
RuntimeDirectory=podbox
[Install]
WantedBy=<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:
| Feature |
Podman 5.5.x |
Podman ≥ 5.6 |
ssh_agent |
Warns and skips |
SshAgent=default + Environment= |
| Quadlet install |
podman quadlet install (uses --replace for idempotent re-runs) |
podman quadlet install |
| Quadlet uninstall |
Manual file remove + systemctl daemon-reload |
podman quadlet rm |
| Container list |
podman ps --filter label=podbox.* |
podman quadlet list |
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.- Files go in
~/.config/containers/systemd/, NOT ~/.config/systemd/user/.
- Re-running
podbox enable is safe — it uses --replace to overwrite existing Quadlet files idempotently.