Docker and Compose

Kuvo Box 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 Box’s engine listens on a Unix socket at ~/.kuvo/docker.sock. Point the docker command at it once, with a Docker context.

Use a Docker context

A context is a named connection the docker command remembers. The first time Kuvo Box starts, it offers to create one called kuvo and make it the default. To do it yourself, for example if you chose Not Now:

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

This applies to every terminal, script and Compose file, and stays after a restart. docker context ls shows your contexts, with the active one marked *.

Opening Docker Desktop switches the context back to Docker Desktop. Run docker context use kuvo to return to Kuvo Box. To use Docker Desktop again on purpose, run docker context use desktop-linux.

One terminal only

To use Kuvo Box in a single terminal without changing the default, set DOCKER_HOST there. kuvo env prints the right setting:

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

Apply it with eval "$(kuvo env)". It lasts until you close that terminal, and takes priority over the active context.

Check the connection

docker version

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

Compose

Compose works unchanged:

docker compose up -d

In Kuvo Box’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 Box 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 Box 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 Box 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 Box:

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. When you delete them, with Kuvo Box or the docker command, the space comes back to your Mac within a few seconds. Kuvo Box › Storage… shows what’s using space and frees it; see Storage. See Uninstall to remove the disk.