Docker and Compose

Kuvo runs the standard Docker Engine, so docker, docker compose and docker buildx work as they always do. The only thing to set up is where the docker command sends its requests.

Connect the docker command

Kuvo’s engine listens on a Unix socket at ~/.kuvo/docker.sock. There are two ways to use it.

Set DOCKER_HOST

kuvo env prints the right setting:

$ kuvo env
export DOCKER_HOST=unix:///Users/you/.kuvo/docker.sock

Apply it to the current shell with eval "$(kuvo env)", or add that line to ~/.zshrc to make it permanent. DOCKER_HOST takes priority over Docker contexts, so this works even if Docker Desktop is installed.

Use a Docker context

A context lets you switch between Kuvo and other engines by name:

docker context create kuvo --docker host=unix://$HOME/.kuvo/docker.sock
docker context use kuvo

Switch back with docker context use default (or desktop-linux for Docker Desktop).

Check the connection

docker version

The Server section should show the Docker version running in Kuvo. If it can’t connect, make sure Kuvo is open, and see Troubleshooting.

Compose

Compose works unchanged:

docker compose up -d

In Kuvo’s sidebar, a Compose project’s containers are grouped under the project name. Select the project to see combined resources and merged logs, or start, stop and remove the whole project at once. See Compose projects.

Published ports

When a container publishes a port, Kuvo forwards it to the same port on your Mac:

docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=dev postgres:16-alpine
psql -h localhost -U postgres

Forwarded ports listen on 127.0.0.1 only, so they’re reachable from your Mac but not from other devices on your network.

Bind mounts

Kuvo shares /Users with the VM at the same path, so bind mounts from anywhere in your home folder work as written:

docker run --rm -v "$PWD":/app -w /app node:22 npm test

Folders outside /Users, such as /tmp or /opt, aren’t shared. Mount them from a folder in your home directory instead.

Intel (amd64) images

On Apple silicon, Kuvo runs linux/arm64 images natively. For linux/amd64 images it uses Rosetta, which is much faster than emulating an Intel CPU:

docker run --rm --platform linux/amd64 alpine uname -m
# x86_64

This needs Rosetta installed on your Mac. If an amd64 image fails with an exec format error, install it and restart Kuvo:

softwareupdate --install-rosetta --agree-to-license

Builds

docker build and docker buildx build use the engine’s built-in BuildKit. The build cache lives in the VM’s disk with your images, so clear it the usual way:

docker builder prune

Resources

The VM gets half of your Mac’s CPU cores (at least two) and half of its memory, up to 8 GB. Containers share those resources. To limit a single container, use the usual flags, for example --cpus 2 --memory 2g.

Where your data lives

Images, containers, volumes and the build cache are stored in the VM’s disk image, at ~/Library/Application Support/Kuvo/disk.img. See Uninstall to remove it.