Home › Docs › klimax as a Docker host

klimax as a Docker host

klimax runs a Docker daemon inside its VM to host kind clusters. That daemon is an ordinary one — you can point your Mac at it and use it for anything, with no Docker Desktop installed.

Point Docker at it

Two ways, and they conflict — pick one. A Docker context persists across shells and is the better default:

$ klimax docker-context        # create and switch to the "klimax" context
$ docker ps                    # now talks to the VM
$ klimax docker-context --unset # switch back to "default"

Or set DOCKER_HOST for the current shell only:

$ eval $(klimax docker-env)
$ eval $(klimax docker-env --unset)

Either way the socket is a Unix socket at ~/.klimax.docker.sock, forwarded by Lima. Nothing listens on a TCP port, so nothing on your network can reach the daemon.

Docker Compose

docker compose is a client-side plugin, not something the daemon provides. The klimax VM ships it, so klimax shell docker compose version works — but that says nothing about your Mac, where the docker CLI looks for plugins in ~/.docker/cli-plugins/. Installing Compose with Homebrew does not put it there:

$ brew install docker-compose
$ docker compose version
docker: unknown command: docker compose   # the binary exists, the plugin link does not

Link it once:

$ mkdir -p ~/.docker/cli-plugins
$ ln -sfn /opt/homebrew/opt/docker-compose/bin/docker-compose \
        ~/.docker/cli-plugins/docker-compose
$ docker compose version

Homebrew suggests an alternative that picks up future plugins automatically — add to ~/.docker/config.json:

{
  "cliPluginsExtraDirs": ["/opt/homebrew/lib/docker/cli-plugins"]
}

Published ports on localhost

This is the part worth configuring deliberately. Set:

network:
  disablePortMirroring: false

and a container's published ports appear on your Mac's loopback, exactly as they would with Docker Desktop:

$ docker run -d -p 8080:80 nginx:alpine
$ curl http://localhost:8080/   # 200 — no port-forward, no VM IP

Lima's hostagent watches for listening ports inside the VM and mirrors each one to 127.0.0.1 on the host as it appears. You publish a port the way you always have, and it lands where you expect.

The trade-off is small and worth knowing: with mirroring on, cluster kubeconfigs use 127.0.0.1, which is stable across VM restarts. With it off, they use the VM's lima0 IP, which macOS assigns and can change — so kubeconfigs need refreshing after a restart. Turning mirroring on actually removes that chore.

Bind mounts

The daemon runs inside the VM and resolves -v sources there. A path your Mac has but the VM does not will not fail — the guest creates an empty directory and the container sees nothing in it. Share the directory first:

vm:
  mounts:
    - location: "~/projects"
      writable: true

Each entry appears at the same absolute path inside the VM, which is what makes docker run -v ~/projects/app:/app resolve. See Sharing host directories.

Registry mirrors and the docker CLI

klimax runs pull-through caches for Docker Hub, quay.io, gcr.io and Artifact Registry, and all of them serve the docker CLI, not just cluster pulls. A docker pull or docker compose up is answered from the local cache on the second fetch, and Docker Hub rate limits stop biting.

Cluster pulls and CLI pulls reach the caches through separate config trees, because two different daemons are involved:

Both use containerd's hosts.toml format — dockerd calls containerd's loader for it — but neither daemon reads the other's directory. Despite the name, certs.d is a general per-registry configuration directory: it held only TLS material when Docker introduced it, and hosts.toml was added to the same layout later to declare mirrors.

Check what a pull will do:

$ klimax shell sudo ls /etc/docker/certs.d
docker.io
gcr.io
quay.io
us-central1-docker.pkg.dev
us-docker.pkg.dev

A mirror is only ever an accelerator: hosts.toml records the real registry as a fallback, so if a cache is down the pull goes direct rather than failing.

What you get over a bare Docker daemon

Alongside Docker Desktop, OrbStack or Colima

They can all be installed at once — each provides its own Docker context, and you switch between them:

$ docker context ls
NAME              DESCRIPTION                       DOCKER ENDPOINT
default           Current DOCKER_HOST based ...     unix:///var/run/docker.sock
klimax *                                            unix:///Users/you/.klimax.docker.sock

What they cannot all do at once is publish to the same port on 127.0.0.1. If you run klimax with disablePortMirroring: false next to another tool, give your containers distinct host ports.

See also

• Configuration — disablePortMirroring, vm.mounts, proxy and CA settings
• Registry mirrors — what is cached and how to add your own
• klimax vs. other tools