Configuration Reference

1[image]
2base = "fedora:44"
3name = "myenv"
4 
5[image.packages]
6install = ["git", "gcc", "ripgrep"]
7remove = ["vim-minimal"]
8 
9[image.run]
10commands = ["dnf clean all"]

1[container]
2name = "myenv"
3home = "~/containers/myenv"
4shell = "zsh"
5 
6[container.mounts]
7extra = ["~/Projects:/home/user/Projects:z"]
8 
9[container.env]
10EDITOR = "nvim"
11TERM = "xterm-256color"
12forward = ["SSH_AUTH_SOCK", "AWS_*"]
13 
14[container.services]
15redis = "redis-server /etc/redis/redis.conf"
16postgres = { command = "postgres -D /home/user/pgdata", restart = "on-failure" }

[security]
secrets = ["openai_key"]              # Secret=openai_key,type=env,target=openai_key

1[[security.secrets]]
2name = "aws_creds"
3type = "mount"                        # env (default) or mount
4target = "/run/secrets/aws"           # destination name inside the container
5mode = "0400"
6 
7[[security.secrets]]
8name = "gh_token"
9source = "systemd"                    # podman (default) or systemd
10target = "GH_TOKEN"                   # Environment=GH_TOKEN=%d/gh_token

1[security]
2apparmor = "unconfined"
3seccomp = "default"
4read_only_rootfs = true
5userns = "nomap"
6cap_preset = "monitoring"
7cap_add = ["SYS_ADMIN"]

[network]
mode = "pasta"
ports = ["8080:80", "443:443"]
offline = false

1[storage.shared_caches]
2cargo = true
3mbx = true
4rustup = false
5 
6[[storage.shared_caches.custom]]
7name = "models"
8container_path = "~/.cache/models"

1[storage.host_caches]
2npm = true
3mbx = true
4 
5[[storage.host_caches.custom]]
6name = "zig"
7host_path = "~/.cache/zig"
8container_path = "~/.cache/zig"

[integration.hardware]
webcam = true
kvm = true

[integration.host_exec]
enabled = true
allowlist = { git = "/usr/bin/git", systemctl = "/usr/bin/systemctl" }

1[integration]
2wayland    = true
3audio      = true
4gpu        = "auto"
5dbus       = true
6notify     = true
7xdg_open   = true
8clipboard  = true
9ssh_agent  = true
10sync_fonts = true
11sync_icons = true
12sync_themes = true
13 
14[integration.host_exec]
15enabled = true
16allowlist = { git = "/usr/bin/git" }
17 
18[integration.xdg_dirs]
19documents = true
20downloads = true
21projects = true
22 
23[integration.export]
24apps = ["gedit", "nautilus"]
25bins = ["rg", "gcc"]

1[lifecycle]
2quadlet      = true
3autostart    = true
4on_stop      = "keep"
5auto_update  = true
6idle_timeout = "off"

[systemd]
requires = ["postgres.service", "redis.service"]
after    = ["network-online.target"]

[dbus]
preset = "gnome"

1[dbus]
2preset = "portal"
3talk = [
4    "org.freedesktop.Notifications",
5    "org.mpris.MediaPlayer2.*",
6]
7own = [
8    "org.mpris.MediaPlayer2.podbox_app",
9]

1[wayland]
2firewall = true
3blocked_interfaces = [
4    "zwlr_screencopy_manager_v1",
5    "ext_image_copy_capture_v1",
6]

1# ── Image ──────────────────────────────────────────────
2[image]
3base = "fedora:44"              # Base image for custom builds
4name = "myenv"                  # Image tag name
5image = "ghcr.io/user/myenv:latest"  # Prebuilt ref (omit for custom builds)
6pull_retry = 3                  # Pull retry count
7pull_retry_delay = "5s"         # Delay between pull retries
8 
9[image.packages]
10install = ["git", "gcc", "ripgrep"]
11remove = ["vim-minimal"]
12# manager = "pacman"        # omitted = auto-detect from the image name
13 
14[image.run]
15commands = ["dnf clean all"]    # Extra RUN steps
16 
17# ── Container ──────────────────────────────────────────
18[container]
19name = "myenv"                  # Required; used for unit names and socket paths
20home = "~/containers/myenv"     # Required; isolated home directory (~ expands)
21shell = "bash"                  # Default login shell
22memory = "4G"                   # Memory limit (e.g. "4G", "512M", omitted = unlimited)
23cpus = "2.0"                    # CPU limit (e.g. "2.0", "0.5", omitted = unlimited)
24reload_cmd = "systemctl reload …"  # systemd ReloadCmd (omitted = none)
25 
26[container.mounts]
27extra = ["~/Work:/home/user/Work:z"]
28 
29[container.env]
30EDITOR = "nvim"
31TERM = "xterm-256color"
32# forward = ["HTTP_PROXY", "AWS_*"]  # Host vars copied in at exec time
33 
34# ── Caches ─────────────────────────────────────────────
35# Both opt-in, same keys, different sources:
36#   shared_caches → podbox volumes, shared between podbox containers
37#   host_caches   → a directory you already keep on the host, bind-mounted in
38# rustup and the ~/.cargo/bin half of cargo hold libc-bound binaries and are
39# never shared.
40[storage.shared_caches]
41cargo  = true
42npm    = true
43mbx    = false
44 
45[storage.host_caches]
46mbx = false                       # ~/.cache/mbx on both sides
47 
48[[storage.host_caches.custom]]
49name = "zig"
50host_path = "~/.cache/zig"
51container_path = "~/.cache/zig"
52 
53# ── Security ───────────────────────────────────────────
54[security]
55apparmor = "unconfined"         # AppArmor profile (omitted = none)
56seccomp = "default"             # Seccomp profile (omitted = none, "unconfined" = off)
57security_label_disable = true   # Disable SELinux labels (needed for Wayland)
58no_new_privileges = true        # Block setuid escalation (sudo, su, AUR helpers)
59read_only_rootfs = false        # Make rootfs read-only (requires writable volumes)
60userns = "keep-id"              # UserNS mode: keep-id, nomap, private (omitted = keep-id)
61cap_add = ["SYS_PTRACE"]        # Extra Linux capabilities (omitted = none)
62secrets = ["openai_key"]        # Podman secrets; no value ever lands in the image
63 
64# [[security.secrets]]         # detailed form when you need type/target/mode
65# name = "aws_creds"
66# type = "mount"
67# mode = "0400"
68 
69# ── Provisioning ───────────────────────────────────────
70# One-shot setup inside the container home, after dotfiles.
71[[provision]]
72name = "rust-toolchain"        # a-z0-9_- ; unique per container
73run = "mise use -g rust@stable"  # executed with sh -c from the home
74timeout = "5m"                 # 30s / 5m / 1h (default 5m)
75on_failure = "warn"            # warn (default) or abort
76env = { FOO = "bar" }          # extra variables; no PODBOX_ keys
77root = false                   # run as root inside the container
78 
79# ── Network ────────────────────────────────────────────
80[network]
81mode = "pasta"                  # host, bridge, none, pasta, slirp4netns, private (default: pasta)
82ports = ["8080:80"]             # Port mappings (ignored in host mode)
83 
84# ── Integration ────────────────────────────────────────
85[integration]
86wayland     = true              # Share Wayland socket
87audio       = true              # Share PipeWire / PulseAudio
88gpu         = "auto"            # GPU: true, false, "auto", "nvidia"
89dbus        = true              # Enable D-Bus session bus
90notify      = true              # Forward desktop notifications
91xdg_open    = true              # Forward URI opening (xdg-open)
92clipboard   = true              # Clipboard sharing
93ssh_agent   = false             # Forward SSH agent (needs Podman ≥ 5.6)
94gpg_agent   = false             # Forward GPG agent
95sync_fonts  = true              # Sync ~/.fonts / ~/.local/share/fonts (ro)
96sync_icons  = true              # Sync ~/.icons / ~/.local/share/icons (ro)
97sync_themes = true              # Sync ~/.themes / ~/.local/share/themes (ro)
98 
99[integration.hardware]         # Host device passthrough (all opt-in)
100webcam = false
101kvm = false
102 
103[integration.host_exec]
104enabled = false
105allowlist = { git = "/usr/bin/git" }  # Alias → absolute path (required when enabled)
106 
107[integration.xdg_dirs]
108documents = false
109downloads = false
110pictures  = false
111music     = false
112videos    = false
113desktop   = false
114projects  = false
115 
116[integration.export]
117apps = ["gedit", "nautilus"]    # Export .desktop files for these apps
118bins = ["rg", "gcc"]            # Create bin shims for these commands
119 
120# ── Lifecycle ──────────────────────────────────────────
121[lifecycle]
122quadlet      = false            # Generate systemd Quadlet files on enable
123autostart    = false            # Start container on user login
124on_stop      = "keep"           # Container behavior on stop: "keep" or "remove"
125auto_update  = false            # Label for auto-updates (registry/local)
126idle_timeout = "off"            # Guest daemon idle timeout: "off", "30s", "5m", "1h"
127 
128# ── systemd dependencies ────────────────────────────────
129[systemd]
130requires = ["postgres.service", "redis.service"]
131after    = ["network-online.target"]
132 
133# ── D-Bus ──────────────────────────────────────────────
134[dbus]
135preset = "portal"               # Named preset: flatpak, gnome, kde, portal ("" = none)
136talk = ["org.freedesktop.Notifications"]
137own  = ["org.mpris.MediaPlayer2.podbox_app"]
138 
139# ── Wayland firewall ───────────────────────────────────
140[wayland]
141firewall = true                 # Enable Wayland protocol firewall
142blocked_interfaces = [          # Blocked Wayland globals (default list)
143    "zwlr_screencopy_manager_v1",
144    "ext_image_copy_capture_v1",
145]