Troubleshooting · Kuvo Box

Check the basics

kuvo status

If it says Kuvo Box is running, the engine is up and the socket path is printed. If the docker command still can’t connect, it isn’t pointed at Kuvo Box. Run:

eval "$(kuvo env)"
docker version

If kuvo itself isn’t found, open Kuvo Box once and start a new terminal window. See The kuvo command.

Cannot connect to the Docker daemon

The docker command is talking to a different socket. Common causes:

DOCKER_HOST isn’t set in this shell. Run eval "$(kuvo env)" or add it to ~/.zshrc.
A Docker context points elsewhere. Run docker context ls. If you created a kuvo context, docker context use kuvo.
Kuvo Box isn’t open. Open it, or run any kuvo command, which starts it.

A port is already in use

Kuvo Box forwards each published port to localhost. If another program already uses that port, including Docker Desktop, the forward can’t open. Quit the other program, or publish on a different port: -p 8081:80.

Intel images fail with “exec format error”

Rosetta isn’t installed. Install it and restart Kuvo Box:

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

Bind mounts are empty

Only /Users is shared with the VM. A path like /tmp/project or /opt/data doesn’t exist inside it. Move the folder into your home directory.

The engine doesn’t start

The window shows what went wrong, with a Try Again button. Kuvo Box keeps two logs that usually explain it:

File	What’s in it
`~/Library/Application Support/Kuvo/console.log`	The VM’s boot output: kernel, setup steps and errors.
`~/Library/Application Support/Kuvo/share/docker.log`	Docker’s own log from inside the VM.

tail -n 50 ~/Library/Application\ Support/Kuvo/console.log
tail -n 50 ~/Library/Application\ Support/Kuvo/share/docker.log

Some common causes:

First launch fails while downloading. Kuvo Box needs to reach dl-cdn.alpinelinux.org the first time. Check your connection, VPN or firewall and try again.
“The VM can’t reach the internet.” The VM got a network address, but neither your Mac nor a public DNS server answered its name lookups. A VPN, firewall or content filter is usually what blocks it. Allow Kuvo Box through, or pause the VPN for the first launch, then click Try Again. If only your Mac’s DNS is blocked, Kuvo Box works around it on its own (see How it works).
Right after quitting. The VM’s disk can stay locked for a moment after Kuvo Box quits. Kuvo Box retries for a few seconds; if it still fails, wait and click Try Again.
The disk is full. Free up space on your Mac, or reclaim space in Kuvo Box with Kuvo Box › Storage… › Reclaim Space… (or docker system prune).

Start over

To reset Kuvo Box’s VM while keeping the app, quit Kuvo Box, then delete its disk:

rm ~/Library/Application\ Support/Kuvo/disk.img

The next launch sets the VM up again from scratch. This deletes all images, containers and volumes in Kuvo Box.

Report a problem

Open an issue on GitHub with:

your macOS version and Mac model,
the output of kuvo status,
the last lines of console.log and docker.log.

Look through the logs before attaching them. They can include container names and paths from your Mac.