Getting started · Kuvo Box

Kuvo Box is a native macOS app that runs the real Docker Engine in a small Linux virtual machine. You keep using the docker command, Compose and your existing scripts. Kuvo Box gives them an engine to talk to and a window to see what’s running.

It’s free for personal and other noncommercial use, its source is on GitHub, and it has no account or sign-in. Commercial use needs a separate license; see the license.

Your first container

Download Kuvo.dmg, open it, and drag Kuvo Box onto the Applications folder.
Open it. The first launch sets up the Linux VM, which takes a minute or so. After that, Kuvo Box is ready about three seconds after you open it.
When Kuvo Box asks Use Kuvo Box for the docker command?, choose Use Kuvo Box. It makes Kuvo Box the default for every terminal, and it stays that way after a restart. If you chose Not Now, use the Use Kuvo Box for docker button in Kuvo Box’s window, or run:
```
docker context create kuvo --docker host=unix://$HOME/.kuvo/docker.sock
docker context use kuvo
```
Run something:
```
docker run -d -p 8080:80 nginx:alpine
```
Open localhost:8080. The container also shows up in Kuvo Box’s sidebar with its live resources and logs.

What you need

A Mac with Apple silicon (M1 or later).
macOS 15 Sequoia or later.
An internet connection the first time you open Kuvo Box, to download Alpine Linux and Docker.
The docker command. If you don’t have it, see The docker command.

Find the right guide

I want to…	Start here
Use Docker and Compose with Kuvo Box	Docker and Compose
Learn my way around the window	The app
Run commands in containers from scripts	CLI reference
Give a coding agent somewhere safe to work	Coding agents
Understand what’s running on my Mac	How it works
Fix something that isn’t working	Troubleshooting

Coming from Docker Desktop

You don’t need to uninstall Docker Desktop to try Kuvo Box. They use separate VMs and separate sockets, so images and containers aren’t shared: anything you pulled in Docker Desktop needs pulling again in Kuvo Box.

Run only one of them at a time if you publish ports. Both forward container ports to localhost, and only one can listen on a given port.

Opening Docker Desktop switches the docker command back to it. Run docker context use kuvo to return to Kuvo Box.