tool-containers
Search docs…Ctrl K
Menu
GitHub (opens in new tab)

Run devbox with Podman

run.sh opens a rootless devbox shell on the current directory. devbox.container runs the same image as a Quadlet systemd user service that you open shells in.

Images
  • GHCRghcr.io/hambn/devbox
  • Docker Hubdocker.io/hambn/devbox
Use case
Rootless development shell or Quadlet service
Source
tools/base/devbox/docs/podman (opens in new tab)
On this page

Prerequisites

  • Podman 4.3 or later for run.sh, which uses --userns=keep-id:uid=1000,gid=1000.
  • Podman 4.4 or later for the Quadlet service.

Open a shell

Shell
./run.sh

Run as a user service

The service mounts ~/workspace and keeps the container running with sleep infinity:

Shell
mkdir -p ~/.config/containers/systemd ~/workspace
cp devbox.container ~/.config/containers/systemd/
systemctl --user daemon-reload
systemctl --user start devbox
podman exec -it systemd-devbox zsh -l

AutoUpdate=registry lets podman auto-update pull a newer image and restart the service.

Variables

Variable Required Purpose
DEVBOX_IMAGE no Image run.sh runs. Defaults to ghcr.io/hambn/devbox:ubuntu-full; use any variant, or a digest reference to pin one build. Edit Image= in the unit for the service.

Workspace

The workspace is mounted at /workspace with :Z, which relabels it on SELinux hosts. Your host UID maps to sysadmin, so files keep your ownership. sudo works inside the user namespace but gives no privileges on the host.

Files

  • run.sh opens a rootless shell on the current directory.
  • devbox.container is the Quadlet unit for the user service.

Cleanup

Shell
systemctl --user stop devbox
rm ~/.config/containers/systemd/devbox.container
systemctl --user daemon-reload

File contents

devbox.container18 lines
# ~/.config/containers/systemd/devbox.container
# systemctl --user daemon-reload && systemctl --user start devbox
[Unit]
Description=devbox development container

[Container]
Image=ghcr.io/hambn/devbox:ubuntu-full
AutoUpdate=registry
UserNS=keep-id:uid=1000,gid=1000
Volume=%h/workspace:/workspace:Z
WorkingDir=/workspace
Exec=sleep infinity

[Service]
Restart=on-failure

[Install]
WantedBy=default.target
run.sh10 lines
#!/usr/bin/env bash
# Open a devbox shell rootlessly with the current directory at /workspace; :Z relabels it on SELinux hosts.
set -euo pipefail

image=${DEVBOX_IMAGE:-ghcr.io/hambn/devbox:ubuntu-full}
podman run -it --rm \
    --userns=keep-id:uid=1000,gid=1000 \
    --volume "$PWD:/workspace:Z" \
    --workdir /workspace \
    "$image" "$@"

Topics