# Docker and Compose

Connect the docker command to Kuvo, publish ports, mount folders and run Intel images.

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:

```text
$ 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:

```sh
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

```sh
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](/docs/troubleshooting/).

## Compose

Compose works unchanged:

```sh
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](/docs/app/#compose-projects).

## Published ports

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

```sh
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:

```sh
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:

```sh
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:

```sh
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:

```sh
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](/docs/uninstall/) to remove it.