Installation

Download

Download the latest release from GitHub and drag Kuvo.app to your Applications folder. The download is about 3 MB.

Kuvo needs macOS 15 or later on a Mac with Apple silicon.

Kuvo is signed with a Developer ID and notarized by Apple, so it opens like any other app. The first time, macOS asks you to confirm opening an app downloaded from the internet.

First launch

The first time you open Kuvo, it sets up its Linux VM:

1. It downloads the Alpine Linux kernel, initial RAM disk and kernel modules from dl-cdn.alpinelinux.org, about 40 MB, and checks each file against a SHA-256 checksum built into the app.
2. It creates a disk image for the VM. The disk is sparse: it can grow to 64 GB, but only takes the space your images and containers use.
3. Inside the VM, it installs Alpine Linux and Docker from Alpine’s package repository.

This takes a minute or two depending on your connection, and the window shows each step. Later launches skip all of it and boot straight into Docker, usually in about three seconds.

The kuvo command

The kuvo command-line tool is part of the app, so there’s nothing extra to install. Every time Kuvo opens, it makes sure kuvo is on your PATH:

• If /opt/homebrew/bin or /usr/local/bin is writable, it puts a symlink there.
• Otherwise it links ~/.kuvo/bin/kuvo and adds that folder to your PATH in ~/.zprofile (and ~/.bash_profile if you have one).

Open a new terminal window after the first launch, then check:

kuvo status

Kuvo only replaces a kuvo symlink it created itself. It never overwrites a file or someone else’s link.

The docker command

Kuvo runs the Docker engine. To talk to it from a terminal you also need the Docker command, which is a separate program.

If you have Docker Desktop installed, you already have it. Otherwise install it with Homebrew:

brew install docker docker-compose docker-buildx

Homebrew installs Compose and Buildx as plugins in its own folder. Tell the docker command where to find them by adding this to ~/.docker/config.json:

{
  "cliPluginsExtraDirs": ["/opt/homebrew/lib/docker/cli-plugins"]
}

Then point it at Kuvo, as described in Docker and Compose.

Build from source

You need Xcode 16 or later (or its command-line tools with Swift 6).

git clone https://github.com/serhatandic/kuvo.git
cd kuvo
./scripts/build-app.sh
open build/Kuvo.app

build-app.sh makes a release build, signs it with the virtualization entitlement Kuvo needs to run a VM, and puts the app in build/. During development, ./scripts/run.sh builds and runs a debug version instead.

The source has two small dependencies: Apple’s swift-argument-parser for the CLI, and SwiftTerm for the built-in terminal.

Updates

For now, download new releases from GitHub and replace the app. Your containers, images and volumes live in the VM’s disk, not in the app, so they survive the update.