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

Bind mounts from the Podman machineCopy Anchor Link

On macOS and Windows with remote Podman, additional bind mount sources are paths in the selected engine's filesystem. A host directory shared into the machine is valid when that share is configured and accessible there. Devsy passes these mounts to the engine for source validation; a path existing on your desktop alone does not establish that it exists in the machine. See Podman's volume documentation.

Check the connection, machine, and actual guest source, replacing my-machine and /path/in/machine:

podman system connection list
podman machine inspect my-machine
podman machine ssh my-machine id -u
podman machine ssh my-machine stat /path/in/machine

The machine's rootless UID need not match your macOS or Windows host identity. For a rootless socket source, use the guest UID to check /run/user/<guest-uid>/podman/podman.sock; the rootful socket is normally /run/podman/podman.sock.

• Source missing in the guest: correct the source path or configure the intended host share into the machine.
• Wrong connection or mode: ensure the native Podman connection and Devsy's PODMAN_HOST select the same machine and rootless/rootful service.
• Source exists but access fails: check filesystem permissions for the engine user and applicable SELinux policy. Avoid broad permission changes or relabeling shared system paths.
• Socket absent inside the workspace container: connecting Devsy to the engine does not mount its socket into the container. If the workspace needs engine access, explicitly configure a bind mount from the verified guest socket to the path its tools expect.

Sharing the socket grants the container control of the engine as the service user. Devsy does not add this mount by default; configure it only for a workspace you trust.

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.