Guides / Install

Install kosa8

Two ways in. Pick the Mac app if you want an icon to double-click; pick the one-line installer if you live in a terminal. They install the same thing.

The Mac app

Download kosa8_0.17.0_macos_app.zip from the releases page, unzip it, and drag kosa8.app to your Applications folder.

The app carries the command-line tool and the background service inside it, so this is the only thing you need — there is nothing to install first. It is signed and notarized by Apple, so it opens without a warning.

One line

$ curl -fsSL https://kosa8.com/install.sh | sh

The installer works out whether you have an Apple or Intel chip, checks the download against the published fingerprints before anything runs, and puts kosa8 on your PATH.

Homebrew

$ brew tap AzmxAI/kosa8
$ brew install kosa8

Windows

PS> irm https://kosa8.com/install.ps1 | iex

Linux

The same one-line installer works, and there are .deb, .rpm and .apk packages on the releases page.

Which machines run sandboxes

Sandboxes are real virtual machines, so they need a hypervisor kosa8 can drive.

Apple Silicon Mac — on Apple's Virtualization framework.
x86-64 Linux — on KVM with Cloud Hypervisor. The installer puts the daemon in place and says what else to install: cloud-hypervisor, virtiofsd, and access to /dev/kvm. kosa8 doctor checks all of it.
Windows 11 on x86-64 (preview) — in WSL2. After installing, run kosa8 wsl setup once: it sets up the Linux engine in an Ubuntu distribution and connects the CLI to it.

Everything else — an Intel Mac, Windows 10, Windows on ARM, JioOS on a JioBook — drives one of those. On that machine run kosa8 daemon start --listen 127.0.0.1:7440 and kosa8 worker pair --url https://…; here, kosa8 worker join with the code it prints. Every command then works normally.

Check it worked

Start the background service

Nothing runs until the daemon is up. The Mac app starts it for you.

$ kosa8 daemon start

Run something

The first run fetches the guest image for your release (a few hundred megabytes), checks it against the release's published checksum, and keeps it in ~/.kosa8/guest. Later runs start straight away. With KOSA8_OFFLINE=1 nothing is fetched: copy the guest image in from an air-gap bundle.

$ kosa8 run alpine echo hi
hi

If anything looks wrong

kosa8 doctor checks the parts that commonly go wrong — the daemon, the guest images, the virtualization entitlement — and tells you which one is missing.

$ kosa8 doctor

Next

Your first sandbox — make a sealed machine and run something inside it.

Using kosa8 from code?

For Node, install @kosa8/sdk (or @kosa8/ai-sdk-sandbox for the Vercel AI SDK) with the daemon running, and follow Install and prerequisites and the Quickstart. Docker clients such as dockerode and Testcontainers work by setting DOCKER_HOST=unix://$HOME/.kosa8/run/kosa8.sock.