# Installation

Download Kuvo Box or build it from source, and get the kuvo and docker commands on your PATH.

## Download

[Download Kuvo.dmg](https://github.com/serhatandic/kuvo-box/releases/latest/download/Kuvo.dmg), open it, and drag **Kuvo Box** onto the **Applications** folder next to it. The download is about 3.4 MB. Older versions are on the [releases page](https://github.com/serhatandic/kuvo-box/releases).

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

Kuvo Box 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 Box, 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, and shrinks again when you delete them.
3. Inside the VM, it installs Alpine Linux and Docker from Alpine's package repository.
4. Once Docker is running, it asks whether to use Kuvo Box for the `docker` command. If you agree, it creates a Docker context called `kuvo` and makes it the default. See [Docker and Compose](/box/docs/docker/#use-a-docker-context).

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.

<img class="only-light" src="/screens/setup-light.webp" alt="Kuvo Box's window while it installs Docker on first launch" width="1600" height="864" />
<img class="only-dark" src="/screens/setup-dark.webp" alt="Kuvo Box's window while it installs Docker on first launch" width="1600" height="864" />

Once Docker is running, and until you run your first container, the window shows two steps: a button that points the `docker` command at Kuvo Box, then a command to try.

<img class="only-light" src="/screens/empty-light.webp" alt="The empty window with two steps: Use Kuvo Box for docker, then a docker run command to copy" width="1600" height="864" />
<img class="only-dark" src="/screens/empty-dark.webp" alt="The empty window with two steps: Use Kuvo Box for docker, then a docker run command to copy" width="1600" height="864" />

## The kuvo command

The `kuvo` command-line tool is part of the app, so there's nothing extra to install. Every time Kuvo Box 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:

```sh
kuvo status
```

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

## The docker command

Kuvo Box 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](https://brew.sh):

```sh
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`:

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

Then point it at Kuvo Box, as described in [Docker and Compose](/box/docs/docker/).

## Build from source

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

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

`build-app.sh` makes a release build, signs it with the virtualization entitlement Kuvo Box 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 three dependencies: Apple's [swift-argument-parser](https://github.com/apple/swift-argument-parser) for the CLI, [SwiftTerm](https://github.com/migueldeicaza/SwiftTerm) for the built-in terminal, and [Sparkle](https://sparkle-project.org) for updates.

## Updates

Kuvo Box updates itself. Once a day it checks the newest release on GitHub, and when there's a new version it shows what's new and asks whether to install it. To check right away, choose **Kuvo Box › Check for Updates…**. To stop the daily check, turn off **Check for updates automatically** in Settings.

Every update is signed with the project's update key, and Kuvo Box refuses one that isn't. The check downloads a small file from github.com; Kuvo Box doesn't send any information about your Mac with it.

Your containers, images and volumes live in the VM's disk, not in the app, so they survive the update.