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 # ArchmacOS
brew install podman
podman machine init
podman machine startPodman 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 infoSet 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 podmanOptions
| Option | Default | Description |
|---|---|---|
PODMAN_PATH | podman | Path to the podman binary, if it is not on PATH. |
PODMAN_HOST | unset | Podman 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_ELEVATION | none | Run 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_TIMEOUT | unset | Stop 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 podmanOr set the option when you add the provider:
devsy provider add podman -o PODMAN_PATH=/usr/local/bin/podmanRootless 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-machineOr switch the existing default machine:
podman machine stop
podman machine set --rootful
podman machine startSwitching 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.Pathand usenpipe:////./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-workspaceTroubleshooting
Socket not found or permission denied
Devsy cannot reach the Podman socket. On macOS and Windows, check podman machine list and start the selected machine with podman machine start <machine-name>. On Linux, check the user socket:
systemctl --user status podman.socketIf the socket path is not the default, set it:
devsy provider set podman --option PODMAN_HOST=unix:///run/user/$(id -u)/podman/podman.sockBind 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/machineThe 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_HOSTselect 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-composeDo not install docker-compose-plugin. It adds docker compose to the Docker CLI and pulls in Docker. Check which provider is active:
podman compose versionUse podman compose instead of docker-compose in your scripts.