Devsy
Tutorials

Podman Provider Setup

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

Install Podman

Linux

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

macOS

brew install podman
podman machine init
podman machine start

Podman Desktop also works.

Windows

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

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

podman machine init
podman machine start
podman info

Set PODMAN_HOST to the Windows named pipe from podman machine inspect, as described below. A Unix socket inside WSL does not work. Run podman system connection list and make this machine's connection the default, because Devsy uses the native Podman client and the Docker-compatible API.

Add the provider

devsy provider add podman

Options

OptionDefaultDescription
PODMAN_PATHpodmanPath to the podman binary, if it is not on PATH.
PODMAN_HOSTunsetPodman API endpoint. On Windows, use the machine named pipe in npipe:////./pipe/<pipe-name> form, not a Unix socket inside WSL. On Linux and macOS, use unix:// followed by the socket path.
PODMAN_ELEVATIONnoneRun podman through pkexec, sudo or doas to reach a rootful socket the current user cannot access. Leave it as none for rootless Podman. pkexec needs a desktop session with a polkit agent, so use sudo or doas on headless hosts.
INACTIVITY_TIMEOUTunsetStop the container after this idle time, for example 10m or 1h.

To update an existing provider:

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

Or set the option when you add the provider:

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

Rootless and rootful

Rootless is the default. Containers run as your user. Use rootful only when a container must bind-mount root-owned paths or needs a network setup 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 keeps images, containers, and volumes. They are hidden while the other mode is active.

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

After switching modes, run podman machine inspect <machine-name> for the machine you started and update PODMAN_HOST:

  • macOS: use unix:// followed by .ConnectionInfo.PodmanSocket.Path.
  • Windows: read .ConnectionInfo.PodmanPipe.Path and use npipe:////./pipe/<pipe-name>, replacing <pipe-name> with the name after \\.\pipe\ in that path.

Run podman system connection list, then select the connection for the same machine and mode with podman system connection default <connection-name>. PODMAN_HOST selects the Docker-compatible API, and the native Podman CLI uses its own default connection. Keep PODMAN_ELEVATION as none: the machine connection is already authenticated.

Start a workspace

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

Troubleshooting

Socket not found or permission denied

Devsy cannot reach the Podman socket. On macOS and Windows, check podman machine list and start the machine 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 machine

On macOS and Windows with remote Podman, bind mount sources are paths inside the machine. A host directory works only if it is shared into the machine. A path that exists on your desktop can be missing in the machine. See Podman's volume documentation.

Check the connection, the machine, and the source in the guest, 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 can differ from your host user. The rootless socket is /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: make the native Podman connection and PODMAN_HOST select the same machine and mode.
  • Source exists but access fails: check file permissions for the engine user and the SELinux policy. Do not relabel shared system paths.
  • Socket absent inside the workspace container: Devsy does not mount the engine socket into the container. If the workspace needs engine access, bind mount the guest socket to the path its tools expect.

A shared socket gives the container control of the engine as the service user. Add it only for a workspace you trust.

Known differences

Dockerfile builds

Devsy builds with podman buildx build, which uses Buildah, not BuildKit. Dockerfile features that only BuildKit supports can fail. Rewrite those steps.

Compose

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

sudo apt-get install -y podman-compose

Do not install docker-compose-plugin. It adds docker compose to the Docker CLI and pulls in Docker. Check which provider is active:

podman compose version

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

On this page