Colima & Podman

Overview

Colima and Podman machine are free, open-source alternatives to Docker Desktop on macOS. Both run a lightweight Linux VM that exposes a Docker-compatible socket, and Dockerman connects to it like any other engine.

Dockerman never installs, updates, starts, or stops these engines. Install and manage Colima or Podman yourself, then configure its socket in Dockerman.

Install

# Colima (plus the Docker CLI it drives)
brew install colima docker

# or Podman
brew install podman

First start (run in your terminal)

The engine creates its VM on the first start, and that step downloads a guest OS image from the internet. Run it yourself in a terminal so you can watch the progress:

# Colima — downloads a ~330 MB guest image on first start
colima start --cpus 4 --memory 8

# Podman — downloads a ~1 GB machine image from quay.io
podman machine init --cpus 4 --memory 8192
podman machine start

The first start can take several minutes depending on your connection. Later starts reuse the downloaded image and finish in seconds.

Pick CPU and memory values that fit your machine — half your CPU cores and 4–8 GB of memory is a good starting point. The upstream default of 2 GB is too small for most image builds.

Behind a proxy

The image download runs inside the engine's own process, so set proxy variables in the same terminal session before the first start:

export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890
colima start   # or: podman machine init

After the first start

Once the VM is running, open Settings → Docker, select a local socket connection, and enter the engine socket path.

Colima normally exposes $HOME/.colima/default/docker.sock.
For Podman machine, run podman machine inspect and use the socket reported by ConnectionInfo.PodmanSocket.Path.

Dockerman currently does not manage Colima or Podman machine lifecycle, CPU, memory, or disk settings. Its Podman verification command can detect a machine socket, but the normal connection flow still requires an explicit working socket path.

Troubleshooting

"Socket not found" means the VM is not running or the configured path is wrong. Run colima start or podman machine start, then verify the path in Settings.
Downloads stall on restricted networks — configure the proxy variables shown above and retry.
The VM's memory usage on the host only grows while it runs; restart the engine to reclaim it.