Podman Provider Setup

Podman is a built-in Devsy provider. It runs containers without a background daemon and is OCI-compatible, so most devcontainer.json files work unchanged. See known differences for the exceptions.

This page covers installing Podman, adding it as a provider, and starting a workspace.

Install PodmanCopy Anchor Link

LinuxCopy Anchor Link

Use your package manager:

sudo apt-get install -y podman   # Debian / Ubuntu
sudo dnf install -y podman       # Fedora / RHEL / CentOS
sudo pacman -S podman            # Arch

macOSCopy Anchor Link

brew install podman
podman machine init
podman machine start

Podman Desktop also works.

WindowsCopy Anchor Link

Install the Windows Podman client and its WSL2-backed machine. Run Podman and Devsy from Windows, not from an executable installed only inside a WSL distribution.

In PowerShell, initialize and start the machine if it does not already exist:

podman machine init
podman machine start
podman info

Use the Windows named pipe from podman machine inspect for PODMAN_HOST, as described below. A Unix socket inside WSL is not a Windows endpoint. Check podman system connection list and make the connection for this machine the default: Devsy uses the native Podman client as well as the Docker-compatible API.

Add the providerCopy Anchor Link

devsy provider add podman

OptionsCopy Anchor Link

For a provider you already added, update its options:

devsy provider set podman --option PODMAN_PATH=/usr/local/bin/podman
devsy provider get podman

Alternatively, set the option during the initial add instead of running the plain add command above:

devsy provider add podman -o PODMAN_PATH=/usr/local/bin/podman

Rootless and rootfulCopy Anchor Link

Rootless is the default and the recommended setup. Containers run as your user. Use rootful only when a container must bind-mount root-owned paths or needs network setups such as macvlan.

On macOS and Windows, switch the Podman machine mode:

For a new machine:

podman machine init --rootful my-rootful-machine
podman machine start --update-connection my-rootful-machine

Or switch the existing default machine:

podman machine stop
podman machine set --rootful
podman machine start

Switching mode does not delete images, containers or volumes. They are hidden while the other mode is active and return when you switch back.

On Linux, to reach a rootful socket without running everything as root, set PODMAN_ELEVATION to sudo or doas.

Start a workspaceCopy Anchor Link

devsy workspace up --provider podman --id my-workspace https://github.com/my-org/my-repo
devsy workspace ssh my-workspace

TroubleshootingCopy Anchor Link

Socket not found or permission deniedCopy Anchor Link

Devsy cannot reach the Podman socket. On macOS and Windows, check that the machine is running with podman machine list, and start it with podman machine start. On Linux, check the user socket:

systemctl --user status podman.socket

If the socket path is not the default, set it:

devsy provider set podman --option PODMAN_HOST=unix:///run/user/$(id -u)/podman/podman.sock

Known differencesCopy Anchor Link

Dockerfile buildsCopy Anchor Link

Podman builds with Buildah, not BuildKit. BuildKit-only syntax, such as RUN --mount=type=cache under the buildkit frontend, can fail. Remove the # syntax=docker/dockerfile:1 line or rewrite those steps.

ComposeCopy Anchor Link

podman compose hands off to an external provider: the podman-compose package or a standalone docker-compose binary. Install one:

sudo apt-get install -y podman-compose

The docker-compose-plugin package does not work here. It adds the docker compose subcommand to the Docker CLI and pulls in Docker. Check what is available:

podman compose version

Use podman compose instead of docker-compose in your scripts.