# Installation

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

## Download

Download the latest release from [GitHub](https://github.com/serhatandic/kuvo/releases/latest) 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:

```sh
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](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, as described in [Docker and Compose](/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.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](https://github.com/apple/swift-argument-parser) for the CLI, and [SwiftTerm](https://github.com/migueldeicaza/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.