Troubleshooting

Check the basics

kuvo status

If it says Kuvo 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. Run:

eval "$(kuvo env)"
docker version

If kuvo itself isn’t found, open Kuvo 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 isn’t open. Open it, or run any kuvo command, which starts it.

A port is already in use

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

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 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 needs to reach dl-cdn.alpinelinux.org the first time. Check your connection, VPN or firewall and try again.
Right after quitting. The VM’s disk can stay locked for a moment after Kuvo quits. Kuvo 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 clean up inside Docker with docker system prune.

Start over

To reset Kuvo’s VM while keeping the app, quit Kuvo, 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.

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.