The app

Kuvo Box’s window has two parts: a sidebar with your containers, images or volumes, and a detail view for whatever you select. Switch between them with the tabs at the top of the sidebar, or press ⌘ 1 for containers, ⌘ 2 for images and ⌘ 3 for volumes. They’re also in the View menu. Everything updates on its own as containers start, stop and change, whether you used the app, the docker command or the kuvo command.

The sidebar

Each container has a row with a status dot, its name, its image and up to two published ports. Running containers also show a small CPU graph and their current CPU use.

• Hover a row to reveal a start or stop button.
• Right-click a row for everything else: restart, pause, open a terminal, open a published port in your browser, copy the ID or name, archive, or remove.
• Filter with the field at the top. It matches names and images. Press Esc to clear it. Containers, images and volumes each keep their own filter.

The status dot is green with a soft pulse while a container runs, yellow when it’s paused, orange while it’s starting, stopping or restarting, blue if it was created but never started, and gray when it’s stopped.

Compose projects

Containers started by Docker Compose are grouped under their project. The project row shows how many services are running and their combined CPU.

• Hover the project’s icon to turn it into a chevron, then click to collapse or expand the group. Filtering always expands groups so matches are never hidden.
• Select the project to see its combined resources and its services’ logs merged into one stream, each line labeled with its service in its own color.
• Start, stop, restart or remove the whole project from the toolbar or by right-clicking the project row.

When you remove a project, Kuvo Box asks whether to keep its volumes. Remove deletes the containers and keeps the data in their volumes. Remove with Volumes also deletes the volumes the containers mount and the project’s named volumes. Volumes still used by other containers are always kept.

Container details

Select a container to see:

• The title bar: its name, how long it’s been running (and its health check status, if it has one), its image, and who created it if it was made with kuvo new.
• The toolbar: a button for each published port that opens it in your browser, a terminal, start or stop, restart, archive, and remove.
• Resources and Logs, described below.

Resources

The Resources pane shows CPU, memory and network use, updated every second, with a minute of history.

• CPU is a percentage of one core, so a container using two full cores shows 200%.
• Memory is the container’s current use, out of the memory available to the VM.
• Network is total traffic, with received and sent shown separately below it.

Live stats only stream while the window is on screen. When you close, minimize or cover the window, Kuvo Box stops collecting them, which is a large part of why it uses so little power when you’re not looking at it.

Logs

The Logs pane follows the container’s output as it’s written, with the colors the program printed.

• The wrap button (a return arrow) wraps long lines to fit the pane. It’s off by default, so long lines run past the edge and you scroll sideways to read them.
• The clock button shows or hides the time each line arrived.
• The trash button clears the view. It doesn’t delete anything from the container.

The wrap and clock buttons are tinted while they’re on, and Kuvo Box remembers both settings.

For a Compose project, logs from every service are merged in time order, each labeled with its service.

Terminal

Press ⌃ ` (or click the terminal button in the toolbar) to open a shell in the selected container, in a pane next to its resources and logs.

The shell is bash if the image has it, otherwise sh. Each container keeps its own terminal while you switch between containers. From the pane’s header you can move it below the other panes, maximize it, or close it.

To use your own terminal app instead, right-click the container and choose Open in Terminal App, or run kuvo shell <container>.

Archive

Archiving stops a container and keeps it for a while instead of deleting it right away. Archived containers show an archive icon and when they’ll be deleted. Restore starts one again.

You choose how long archived containers are kept in Settings. Nothing else is ever deleted automatically.

Images

Click Images at the top of the sidebar, or press ⌘ 2, to see every image and its size. Like volumes, they’re in two groups: In Use, for images a container was created from, running or stopped, and Unused, with orange icons and their total size in the header.

Each image is one row however many tags it has, so sizes aren’t counted twice. The row shows the tag a container was run with, or a specific tag rather than latest, and +2 tags when there are more.

Untagged images are usually older versions. When you pull a newer nginx:alpine, the tag moves to the new image and the old one loses its name. Kuvo Box lists untagged images by the start of their ID and, if it saw the tag before it moved, says what it was: Was nginx:alpine. A container can keep running an untagged image, so it can also appear under In Use.

Select an image to see:

• Under its name, whether anything uses it, and for an unused untagged image, what replaced it.
• Containers: each container created from it, and whether it’s running. Click one to open it.
• Overview: its tags, size, when it was built, its platform, the ports it exposes and the command it runs. Intel (linux/amd64) images say they run through Rosetta.

Right-click a tag to copy it, or to remove it while the image has others. Right-click an image in the sidebar to copy its name or ID.

Pull an image

Click the pull button in the toolbar, or press ⌘ N, and enter a name like nginx:alpine. Leave out the tag to get latest. If the name is wrong, or the image needs a login, Kuvo Box says so before downloading anything; for private images, run docker login in a terminal first. Once the download starts, the image appears at the top of the list with how much has downloaded, and it’s selected when it’s done.

Pulling an image you already have gets its newest version. If there’s nothing newer, Kuvo Box says it’s already up to date. If there is, the version you had becomes untagged.

Remove images

• Remove an unused image by hovering it and clicking the trash button, by right-clicking it, or by selecting it and clicking Remove in the toolbar. All its tags go with it.
• Remove all unused images with Remove All… in the Unused header. Kuvo Box names the images first, and when some are untagged, offers to remove just those. Images can share layers, so removing several can free less space than their sizes add up to.

Docker won’t remove an image a container was created from, even a stopped one, so remove the container first.

Volumes

Click Volumes at the top of the sidebar, or press ⌘ 3, to see every volume and its size, in two groups:

• In Use: volumes that at least one container mounts, running or stopped. Each row says which containers.
• Unused: volumes no container uses, often left behind by removed containers or old Compose projects. Their icon is orange, and each row shows the Compose project it came from (or Anonymous for a volume Docker named itself) and when it was created. The group’s header shows how many there are and how much space they take.

Anonymous volumes are listed by the first 12 characters of their ID. The filter field matches volume names and Compose projects.

Select a volume to see:

• Under its name, whether anything uses it. For an unused volume, this says why it might still be there: for example, that the Compose project it came from has no containers left, or that it’s anonymous.
• Mounts: each container that uses it, whether that container is running, and the path where the volume appears inside it, marked read-only when it is. Click a container to open it.
• Overview: its size, when it was created, its Compose project, and for an anonymous volume, where those come from.

Right-click a volume in the sidebar to copy its full name, or its path inside the VM.

• Remove an unused volume by hovering it and clicking the trash button, by right-clicking it, or by selecting it and clicking Remove in the toolbar.
• Remove all unused volumes with Remove All… in the Unused header. Kuvo Box names the volumes and says how much data they hold before deleting them. If you’ve filtered the list, only the unused volumes that match are removed.

Removing a volume deletes its data for good. Docker won’t remove a volume while any container uses it, even a stopped one, so remove the container first.

Kuvo Box measures sizes when you open the list and again whenever Docker reports a change, like a container starting or a volume being created. It doesn’t re-measure on a timer, because measuring means reading every file in every volume. Data a running container writes shows up at the next change.

Storage

Choose Kuvo Box › Storage… to see how much space Kuvo Box takes on your Mac and what’s using it. It’s also the Storage tab in Settings.

• Kuvo Box uses … on your Mac is the real size of the VM’s disk on your Mac.
• The bar and the list below split that into Images, Containers (what containers wrote on top of their images), Volumes, Build cache and System (Linux, Docker and the VM’s file system). Each says how much could be freed, for example how much of the images no container uses. Show opens that section in the main window.

Kuvo Box measures when you open the page, after you reclaim space, and after anything is deleted while the page is open. Click the arrow next to Updated to measure again.

Reclaim space

Click Reclaim Space… and choose what to remove:

Choice	Selected at first	What you lose
Unused images	Yes	Nothing: they download again when a container needs them.
Build cache	Yes	Nothing: it’s rebuilt on the next build.
Stopped containers	No	Their changes and logs. Archived containers are always kept.
Unused volumes	No	The data in them. This can’t be undone.

“Unused” means the same as in the Images and Volumes sections: no container, running or stopped, uses it. When it’s done, Kuvo Box shows how much space came back on your Mac, measured from the disk itself. That can be less than the sizes add up to, because images share layers.

Space comes back on its own

You don’t need Reclaim Space to get space back. Whenever Docker deletes something, whether from Kuvo Box or with the docker command, Kuvo Box tells macOS which parts of the VM’s disk are now free, and the disk shrinks on your Mac within a few seconds. Kuvo Box also does this every time the VM starts.

Menu bar

Kuvo Box has a menu bar icon that lists every container with a start or stop button, so you can manage them with the window closed. Closing the window doesn’t stop Kuvo Box or your containers. Quitting Kuvo Box does: it shuts down the VM cleanly, which stops every container.

Settings

Open Kuvo Box › Settings (⌘ ,). The General tab has these settings; the Storage tab is described in Storage.

Setting	What it does
Appearance	System, Light or Dark. In light mode the window’s glass adapts to how bright your wallpaper is.
Delete archived containers after	1 day, 7 days (the default), 30 days, or Never.
Check for updates automatically	On by default. Kuvo Box checks for a new version once a day. See Updates.

Kuvo Box › About Kuvo Box shows the app version and the Docker version running in the VM. Kuvo Box › Check for Updates… checks for a new version right away.

Keyboard shortcuts

Shortcut	Action
⌘ 1	Show containers in the sidebar
⌘ 2	Show images in the sidebar
⌘ 3	Show volumes in the sidebar
⌘ N	Pull an image (while images are shown)
⌃ `	Open or close the terminal for the selected container
⌘ .	Stop the selected container
⌘ R	Start the selected container
⌘ ,	Settings
Esc	Clear the sidebar filter