# Docker and Compose

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

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**:

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

- `docker` follows the active context; only one is active at a time, for every terminal.
- `kuvo` → `~/.kuvo/docker.sock` → Kuvo Box.
- `desktop-linux` → `~/.docker/run/docker.sock` → Docker Desktop.
- `default` → `/var/run/docker.sock`.

**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:

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

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

## Compose

Compose works unchanged:

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

## Published ports

When a container publishes a port, Kuvo Box 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 Box 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 Box 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 Box:

```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`. 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](/box/docs/app/#storage). See [Uninstall](/box/docs/uninstall/) to remove the disk.