Preview · 0.1.0-preview.10 · Apple silicon · macOS 26+

Linux workloads on your Mac, one VM each.

Koala runs jobs, services, development environments and AI agents in ARM64 Linux VMs on Apple silicon. Each VM has its own kernel, disk and network, and gets only the access you grant it.

Get started How it works

$brew install kunalkushwaha/koala/koala

~/project — zsh

$ koala run --image docker.io/library/alpine:3 -- \
    /bin/sh -c 'echo hello from the guest; uname -m'
hello from the guest
aarch64
# a VM that stays up after the terminal closes
$ koala create dev --image docker.io/library/alpine:3 --wait
$ koala start dev --wait
$ koala exec -it dev -- /bin/sh
/ #

01 · Install

Two commands, no `sudo`

brew install kunalkushwaha/koala/koala
koala system install          # set up and start the manager for your user

You need a Mac with Apple silicon and macOS 26 or newer, and images built for linux/arm64. To install from a release archive, see getting started.

02 · Try it

From throwaway job to sandboxed agent

A command in a fresh VM that is removed when the command ends:

koala run --image docker.io/library/alpine:3 -- /bin/sh -c 'echo hello from the guest; uname -m'

Create a persistent VM and work in it:

koala create dev --image docker.io/library/alpine:3 --wait
koala start dev --wait
koala exec -it dev -- /bin/sh        # an interactive shell; type exit to leave
koala stop dev --wait

An environment VM with the internet off and an API key that never enters it. The key stays in your login keychain, and the broker adds it to the requests the policy allows:

koala policy create openai-main --template openai --model gpt-4.1-mini   # asks for the key
koala create agent --image docker.io/library/alpine:3 --no-internet \
  --broker openai=openai-main --wait
koala start agent --wait
koala exec agent -- sh -c 'echo $OPENAI_BASE_URL $OPENAI_API_KEY'

Inside the VM, the service is http://openai.broker.koala.internal/v1, and OPENAI_API_KEY is only a placeholder. See keys on your Mac, networking and the Hermes example.

One command sets an agent up: its VM, the policy that keeps its key on your Mac, a volume, and its setup. Koala shows the whole plan and asks first:

koala template list                     # the templates
koala create hermes --template hermes   # asks for the model key, shows the plan, then asks

See VM templates for agents, and the examples: Hermes, OpenClaw (not tested on Koala yet) and an X agent.

03 · What you get

Built for untrusted workloads

Throwaway jobs

A command in a fresh VM, removed when it ends. For builds, tests and scripts you would rather not run on your Mac. Jobs and VMs →

Services and environments

VMs that keep running after your terminal closes. exec, attach a shell, cp files in and out. Working inside a VM →

Keys stay on your Mac

An agent’s API keys stay in your login keychain. The broker adds a key only to the requests a policy allows, so it never enters the VM. Keys on your Mac →

Agents in one command

koala create hermes --template hermes makes an agent’s VM, its key’s policy, a volume and its setup, after showing the plan. VM templates →

The images you have

OCI images from Docker Hub or a private registry, pinned by digest when a VM is created. Images →

Lean or full

Lean runs one image with a minimal init. Full runs a Linux distribution with systemd and Docker Engine. Profiles →

Deny by default

No host files, no secrets, no LAN, no other VMs, until you grant them. Checked on the Mac side. Networking →

Runs as you

A per-user launchd manager keeps track of your VMs. Nothing system-wide, no root daemon. Getting started →

04 · Defaults

What a VM can reach

Resource	Default	When you grant it
Internet	Public addresses only	Can be switched off
Files on your Mac	None	Folders you share; read-only unless you ask for read-write
Secrets	None	Named secrets, to one VM, as a file or an environment variable
API keys	None	A broker grant: the key stays on your Mac, added only to the requests a policy allows
Services on your Mac	None	One address and specific ports
Your LAN	None	A specific prefix and ports
Other VMs	Never	Not available in v0.1
Published ports	None	On `127.0.0.1`, or on the LAN when you ask

Koala treats everything inside a VM as untrusted, and trusts you, the logged-in macOS user. VMs do not keep running after you log out or restart your Mac.

Read the user guideEvery command, flag and spec field, with what is tested.

How Koala worksThe processes, the boundaries, and the trust model.