Koala 0.1.0-preview.9 (preview)

Koala 0.1.0-preview.9 (preview)

This is a preview release. Koala runs Linux VMs for development and CI on
Apple silicon Macs. Its security work is not complete:

• Done:
  • testing against a VM whose root user is hostile (S02);
  • the secret-free host broker: API keys stay on your Mac, and a VM gets
    only the requests a policy allows (S03);
  • koala-net, the per-VM network policy helper, and koala-broker run
    in the App Sandbox.
• Not done: endurance and crash qualification, and the density checks (S04,
  R03).

Use it with workloads and on machines you trust.

Changes since 0.1.0-preview.8

New: VM templates for agents

A template sets an agent up in one command: its VM, the broker policies
that keep its API keys on your Mac, its volumes, and the setup to run in
the VM once it is up.

koala template list                     # the templates
koala template inspect hermes           # what one makes, and its parameters
koala create hermes --template hermes   # make it

• It shows the whole plan first, including what the VM can reach, and
  asks before changing anything. --yes skips the question.
• Parameters change a template's model, provider, port and more:
  --set model=gpt-4.1 --set port=9000. --cpus, --memory and --disk
  work too.
• The built-in template is hermes, the Hermes agent with its model key
  on your Mac and no internet in the VM.
• Your own templates are JSON files: start from koala template inspect hermes --json, and use --template ./my-agent.json.
• If a step fails, koala says what was made, how to finish by hand, and
  how to remove it.

See "VM templates for agents" in the guide.

New: koala template update

Templates can now be updated between releases. koala template update
downloads the latest VM and policy templates from this repository, only
when you run it.

• They are kept only if their index is signed with the key that signs
  Koala's releases, and isn't older than the one you have. If any check
  fails, nothing changes.
• A downloaded template is used when its version is higher than the one
  built into your koala. Today's published templates are the same as this
  release's.

New examples

The examples/ folder of this repository now has:

• hermes: the Hermes template, to read or change;
• openclaw: a script that runs OpenClaw's gateway in a VM, with its
  model key on your Mac. It is written from OpenClaw's documentation and is
  not tested on Koala yet;
• x-agent: as in preview.7.

The guide's sidebar now lists every example, and the broker page.

Installing and upgrading

• brew upgrade koala, then koala system install. If VMs are running,
  add --stop-vms.
• macOS may ask once whether the new manager may use your stored registry
  logins and secrets: click Always Allow.

What's included

• The koala CLI, the per-user manager, the network helper, the image
  extractor and the credential broker, for Apple silicon Macs with macOS 26
  or later.
• The lean runtime, which koala system install downloads from
  ghcr.io/kunalkushwaha/koala-runtime@sha256:a7aa01254e6adb20e4435e5c748f9b2459445f1c6730b9f4b995b8520cc5b5ec and verifies against the release key below.
• The full profile (systemd and Docker inside the VM) is not included
  in this preview.

Install

With Homebrew:

brew install kunalkushwaha/koala/koala
koala system install

From the archive:

tar -xzf koala-0.1.0-preview.9-darwin-arm64.tar.gz
koala-0.1.0-preview.9/bin/koala system install

An archive downloaded with a web browser carries the quarantine attribute,
which stops macOS from running Koala's binaries: they are ad-hoc signed, not
signed with an Apple Developer ID or notarized. Homebrew is the recommended
path. If you use the archive, check its checksum first, then remove the
attribute from the extracted folder:

shasum -a 256 koala-0.1.0-preview.9-darwin-arm64.tar.gz   # must print 4c413b1f89d486d6a18905e445bbcb918cfcf1ac644421c44c8183303266e577
xattr -dr com.apple.quarantine koala-0.1.0-preview.9

Koala never removes the attribute itself. Keep the extracted folder: the
koala command runs from it.

Verify

• Archive sha256: 4c413b1f89d486d6a18905e445bbcb918cfcf1ac644421c44c8183303266e577
• Runtime release key: koala-release-1, public key sha256 8ca4ec5b8b366912a3398cc54c0eaa788012a91e86ba2007c96ecd07258a6288

Uninstall

koala system uninstall                # keeps VMs, volumes, images and runtimes
koala system uninstall --purge --yes  # deletes them, and Koala's keychain items
brew uninstall koala                  # with Homebrew, afterwards

Koala is licensed under the Apache License, Version 2.0. NOTICE lists the
third-party software in the binaries.

Koala 0.1.0-preview.10 (preview)

Koala 0.1.0-preview.10 (preview)

This is a preview release. Koala runs Linux VMs for development and CI on
Apple silicon Macs. Its security work is not complete:

• Done:
  • testing against a VM whose root user is hostile (S02);
  • the secret-free host broker: API keys stay on your Mac, and a VM gets
    only the requests a policy allows (S03);
  • koala-net, the per-VM network policy helper, and koala-broker run
    in the App Sandbox.
• Not done: endurance and crash qualification, and the density checks (S04,
  R03).

Use it with workloads and on machines you trust.

Changes since 0.1.0-preview.9

Template listings that are easy to read

koala policy templates is now a table, one row per template:

NAME       VERSION  SERVICE            KEY            DEFAULT GROUPS
anthropic  v1       api.anthropic.com  header         messages, models
openai     v1       api.openai.com     bearer token   chat, models
telegram   v1       api.telegram.org   URL path       updates, messages
…

• koala policy templates NAME shows one template: what it is for,
  the service, how the key is sent, its groups, and the command that uses
  it.
• koala template list shows both kinds of templates, grouped: VM
  templates (koala create NAME --template T), then policy templates
  (koala policy create NAME --template T).
• Scripts: the --json output is unchanged. koala template list --json adds policyTemplates, and koala policy templates NAME --json
  gives one template.

Nothing else changes: the manager, the network helper and the runtime
are as in preview.9.

Installing and upgrading

• brew upgrade koala, then koala system install. If VMs are running,
  add --stop-vms.
• macOS may ask once whether the new manager may use your stored registry
  logins and secrets: click Always Allow.

What's included

• The koala CLI, the per-user manager, the network helper, the image
  extractor and the credential broker, for Apple silicon Macs with macOS 26
  or later.
• The lean runtime, which koala system install downloads from
  ghcr.io/kunalkushwaha/koala-runtime@sha256:a7aa01254e6adb20e4435e5c748f9b2459445f1c6730b9f4b995b8520cc5b5ec and verifies against the release key below.
• The full profile (systemd and Docker inside the VM) is not included
  in this preview.

Install

With Homebrew:

brew install kunalkushwaha/koala/koala
koala system install

From the archive:

tar -xzf koala-0.1.0-preview.10-darwin-arm64.tar.gz
koala-0.1.0-preview.10/bin/koala system install

An archive downloaded with a web browser carries the quarantine attribute,
which stops macOS from running Koala's binaries: they are ad-hoc signed, not
signed with an Apple Developer ID or notarized. Homebrew is the recommended
path. If you use the archive, check its checksum first, then remove the
attribute from the extracted folder:

shasum -a 256 koala-0.1.0-preview.10-darwin-arm64.tar.gz   # must print 58cadb1982464f1886ded9f1cb2075d88043fd9e517d7ceac3b797ed60fc9a6e
xattr -dr com.apple.quarantine koala-0.1.0-preview.10

Koala never removes the attribute itself. Keep the extracted folder: the
koala command runs from it.

Verify

• Archive sha256: 58cadb1982464f1886ded9f1cb2075d88043fd9e517d7ceac3b797ed60fc9a6e
• Runtime release key: koala-release-1, public key sha256 8ca4ec5b8b366912a3398cc54c0eaa788012a91e86ba2007c96ecd07258a6288

Uninstall

koala system uninstall                # keeps VMs, volumes, images and runtimes
koala system uninstall --purge --yes  # deletes them, and Koala's keychain items
brew uninstall koala                  # with Homebrew, afterwards

Koala is licensed under the Apache License, Version 2.0. NOTICE lists the
third-party software in the binaries.

Koala 0.1.0-preview.8 (preview)

Koala 0.1.0-preview.8 (preview)

This is a preview release. Koala runs Linux VMs for development and CI on
Apple silicon Macs. Its security work is not complete:

• Done:
  • testing against a VM whose root user is hostile (S02);
  • the secret-free host broker: API keys stay on your Mac, and a VM gets
    only the requests a policy allows (S03);
  • koala-net, the per-VM network policy helper, and koala-broker run
    in the App Sandbox.
• Not done: endurance and crash qualification, and the density checks (S04,
  R03).

Use it with workloads and on machines you trust.

Changes since 0.1.0-preview.7

Fixes

• A burst of connections from a VM is no longer refused. A VM's
  network helper sets up at most 32 outgoing connections at a time. Beyond
  that, a new TCP connection used to be refused at once. So a package
  manager, parallel downloads or a busy web page could see some of their
  connections fail. Now such a connection waits for a free slot, and goes
  through. In testing, 64 and 128 connections opened at once from a VM all
  succeeded; with preview.7, 14 and 67 of them were refused.
• The network helper's network stack is updated (gVisor, and
  gvisor-tap-vsock 0.9.0). The newer gVisor fixes, at its source, the
  deadlock that preview.7 worked around. The helper passed the same
  hostile-guest tests as before.
• The broker's Groq example was wrong. Groq's API is under
  /openai/v1, so --origin https://api.groq.com with the openai
  template can't reach it. "Write your own policy" in the broker guide now
  shows how to set up Groq. koala help policy create and koala policy templates no longer suggest it.

Also tested: a VM's network comes back by itself when the Mac wakes, after
a night with the lid closed, with no restart.

Changes in behaviour

• A connection that finds all 32 setups busy waits up to 10 seconds for
  one to finish. If none does (for example, the VM keeps dialling
  addresses that never answer), the connection isn't refused. Its first
  packet is dropped, and the VM's TCP retries it, as it would with a busy
  server. A program with a short connect timeout sees a timeout instead of
  "connection refused".

Installing and upgrading

• brew upgrade koala, then koala system install. If VMs are running,
  add --stop-vms.
• macOS may ask once whether the new manager may use your stored registry
  logins and secrets: click Always Allow.

What's included

• The koala CLI, the per-user manager, the network helper, the image
  extractor and the credential broker, for Apple silicon Macs with macOS 26
  or later.
• The lean runtime, which koala system install downloads from
  ghcr.io/kunalkushwaha/koala-runtime@sha256:a7aa01254e6adb20e4435e5c748f9b2459445f1c6730b9f4b995b8520cc5b5ec and verifies against the release key below.
• The full profile (systemd and Docker inside the VM) is not included
  in this preview.

Install

With Homebrew:

brew install kunalkushwaha/koala/koala
koala system install

From the archive:

tar -xzf koala-0.1.0-preview.8-darwin-arm64.tar.gz
koala-0.1.0-preview.8/bin/koala system install

An archive downloaded with a web browser carries the quarantine attribute,
which stops macOS from running Koala's binaries: they are ad-hoc signed, not
signed with an Apple Developer ID or notarized. Homebrew is the recommended
path. If you use the archive, check its checksum first, then remove the
attribute from the extracted folder:

shasum -a 256 koala-0.1.0-preview.8-darwin-arm64.tar.gz   # must print bb2185a1fce53880d981fb74d673c5dc562256eb9cc0d853e2b85f17b03ab1e5
xattr -dr com.apple.quarantine koala-0.1.0-preview.8

Koala never removes the attribute itself. Keep the extracted folder: the
koala command runs from it.

Verify

• Archive sha256: bb2185a1fce53880d981fb74d673c5dc562256eb9cc0d853e2b85f17b03ab1e5
• Runtime release key: koala-release-1, public key sha256 8ca4ec5b8b366912a3398cc54c0eaa788012a91e86ba2007c96ecd07258a6288

Uninstall

koala system uninstall                # keeps VMs, volumes, images and runtimes
koala system uninstall --purge --yes  # deletes them, and Koala's keychain items
brew uninstall koala                  # with Homebrew, afterwards

Koala is licensed under the Apache License, Version 2.0. NOTICE lists the
third-party software in the binaries.

Koala 0.1.0-preview.7 (preview)

Koala 0.1.0-preview.7 (preview)

This is a preview release. Koala runs Linux VMs for development and CI on
Apple silicon Macs. Its security work is not complete:

• Done:
  • testing against a VM whose root user is hostile (S02);
  • the secret-free host broker: API keys stay on your Mac, and a VM gets
    only the requests a policy allows (S03);
  • koala-net, the per-VM network policy helper, and koala-broker run
    in the App Sandbox.
• Not done: endurance and crash qualification, and the density checks (S04,
  R03).

Use it with workloads and on machines you trust.

Changes since 0.1.0-preview.6

New: broker templates for chat bots and GitHub

A bot's token, or a GitHub App's key, can now stay on your Mac, as model keys
can since preview.6.

koala policy create telegram-bot --template telegram   # asks for the bot token
koala policy create slack-bot --template slack
koala policy create discord-bot --template discord
koala create bot --image docker.io/library/python:3.12-alpine --no-internet \
  --broker tg=telegram-bot --wait

• The app in the VM gets a placeholder token and the broker's address. See
  "Chat platforms" in the broker guide for each template's variables.

• GitHub: the broker holds a GitHub App's private key, and uses
  short-lived tokens limited to the repositories (--repo OWNER/NAME) and
  permissions you choose. The VM never sees the key or the tokens.

  koala policy create gh --template github --app-id 123456 \
    --installation-id 7890123 --repo acme/app --value-stdin < app.private-key.pem

  git and gh aren't covered yet: they need a token in the VM.

New example: an X agent

examples/x-agent in this repository shows a different kind of agent:

• a normal browser, Chromium, in a VM, which you sign in to through a live
  view on your Mac;
• an agent beside it that reads X, drafts replies and posts with a model,
  either Ollama on your Mac or a provider through the broker;
• nothing is posted until you approve it.

See "Example: an X agent" in the guide.

Fixes

• koala stop lets a VM's program finish. Stopping a lean VM used to
  kill everything in it at once, so a browser lost its last cookies, and a
  database or agent lost writes still in memory. It now sends SIGTERM to
  the VM's program and waits up to 10 seconds before stopping the VM.
• Browsers no longer starve a VM's network. A burst of UDP packets,
  such as a browser's HTTP/3 (QUIC) traffic, could deadlock part of the
  network helper. The VM then refused most new connections, and web apps
  failed with errors such as X's "Something went wrong".

Changes in behaviour

• koala stop on a VM whose program ignores SIGTERM now takes about
  10 seconds; it used to be immediate.
• A shell script as the VM's command should pass the signal on to the
  programs it starts. See "How koala stop stops a lean VM", under
  "Lifecycle commands" in the guide's "Jobs and VMs" page.

Installing and upgrading

• brew upgrade koala, then koala system install. If VMs are running,
  add --stop-vms.
• macOS may ask once whether the new manager may use your stored registry
  logins and secrets: click Always Allow.

What's included

• The koala CLI, the per-user manager, the network helper, the image
  extractor and the credential broker, for Apple silicon Macs with macOS 26
  or later.
• The lean runtime, which koala system install downloads from
  ghcr.io/kunalkushwaha/koala-runtime@sha256:a7aa01254e6adb20e4435e5c748f9b2459445f1c6730b9f4b995b8520cc5b5ec and verifies against the release key below.
• The full profile (systemd and Docker inside the VM) is not included
  in this preview.

Install

With Homebrew:

brew install kunalkushwaha/koala/koala
koala system install

From the archive:

tar -xzf koala-0.1.0-preview.7-darwin-arm64.tar.gz
koala-0.1.0-preview.7/bin/koala system install

An archive downloaded with a web browser carries the quarantine attribute,
which stops macOS from running Koala's binaries: they are ad-hoc signed, not
signed with an Apple Developer ID or notarized. Homebrew is the recommended
path. If you use the archive, check its checksum first, then remove the
attribute from the extracted folder:

shasum -a 256 koala-0.1.0-preview.7-darwin-arm64.tar.gz   # must print 03237e9bb565de72b9f6647c2b928dc471e3a193657a329fdfbd4ae5c32cc6a3
xattr -dr com.apple.quarantine koala-0.1.0-preview.7

Koala never removes the attribute itself. Keep the extracted folder: the
koala command runs from it.

Verify

• Archive sha256: 03237e9bb565de72b9f6647c2b928dc471e3a193657a329fdfbd4ae5c32cc6a3
• Runtime release key: koala-release-1, public key sha256 8ca4ec5b8b366912a3398cc54c0eaa788012a91e86ba2007c96ecd07258a6288

Uninstall

koala system uninstall                # keeps VMs, volumes, images and runtimes
koala system uninstall --purge --yes  # deletes them, and Koala's keychain items
brew uninstall koala                  # with Homebrew, afterwards

Koala is licensed under the Apache License, Version 2.0. NOTICE lists the
third-party software in the binaries.

Koala 0.1.0-preview.6 (preview)

Koala 0.1.0-preview.6 (preview)

This is a preview release. Koala runs Linux VMs for development and CI on
Apple silicon Macs. Its security work is not complete:

• Done:
  • testing against a VM whose root user is hostile (S02);
  • the secret-free host broker: API keys stay on your Mac, and a VM gets
    only the requests a policy allows (S03);
  • koala-net, the per-VM network policy helper, and koala-broker run
    in the App Sandbox.
• Not done: endurance and crash qualification, and the density checks (S04,
  R03).

Use it with workloads and on machines you trust.

Changes since 0.1.0-preview.5

New: keep API keys on your Mac (the credential broker)

A VM can now use an API key without ever holding it. The key stays in your
login keychain. A sandboxed koala-broker on your Mac adds it to the
requests you allow, for the one service you allow, and this works with the
VM's internet access turned off.

koala policy create openai-main --template openai --model gpt-4.1-mini
koala create agent --image docker.io/library/alpine:3 --no-internet \
  --broker openai=openai-main --wait

• koala policy templates lists the built-in templates: OpenAI (and
  services with the same API, via --origin) and Anthropic.
• koala policy create asks for the key and stores the policy.
  inspect, list, status, disable, enable, upgrade and rm
  manage it.
• Requests outside the policy are refused: other paths, other models,
  oversized bodies, responses that echo the key. Limits apply per VM.
• See "Keys on your Mac" in the guide, and the Hermes example, which now
  runs with its model key on your Mac and internet off.

New: create and change VMs without writing JSON

• koala create takes:
  • the process: -- ARGS, --env, --user, --workdir and
    --entrypoint;
  • the network: --no-internet, --broker and --host-service;
  • secrets: --secret-env and --secret-file.
• Before creating, it prints everything the VM will be able to reach.
• koala edit VM opens a stopped VM's definition in your editor, checks
  it, and applies it.

Readable output

koala inspect, stats, execution inspect, secret inspect,
credential inspect, policy inspect and system info now describe
things in words. For example, inspect shows the image, command, internet
setting, grants, ports, volumes, shares and secrets, and why a VM failed.
--json is unchanged.

Fixes

• Images whose user is a name (USER root, node, app:app) now run
  in lean VMs without "user": "0". HOME is set from the image's user.
• A start that fails says why, in koala start and koala inspect.
• koala exec and koala stop on a service VM no longer fail at
  random with CONFLICT.
• Starting VMs after memory pressure: starts were refused until the
  manager restarted. Admission now follows the current memory-pressure
  level.
• koala logs --serial now keeps the console output of a run that
  fails within its first second.
• preview.5's known issue is fixed: after the manager crashes or is
  killed, running VMs keep their network. Published ports come back on the
  same host port, with no VM restart.

Changes in behaviour

• The human-readable output of the commands above has changed. Scripts
  should use --json.
• koala create and koala update print more lines before submitting: the
  internet setting, each grant and each secret.

Installing and upgrading

• brew upgrade koala, then koala system install. If VMs are running,
  add --stop-vms.
• macOS may ask once whether the new manager may use your stored registry
  logins and secrets: click Always Allow.

What's included

• The koala CLI, the per-user manager, the network helper, the image
  extractor and the credential broker, for Apple silicon Macs with macOS 26
  or later.
• The lean runtime, which koala system install downloads from
  ghcr.io/kunalkushwaha/koala-runtime@sha256:a7aa01254e6adb20e4435e5c748f9b2459445f1c6730b9f4b995b8520cc5b5ec and verifies against the release key below.
• The full profile (systemd and Docker inside the VM) is not included
  in this preview.

Install

With Homebrew:

brew install kunalkushwaha/koala/koala
koala system install

From the archive:

tar -xzf koala-0.1.0-preview.6-darwin-arm64.tar.gz
koala-0.1.0-preview.6/bin/koala system install

An archive downloaded with a web browser carries the quarantine attribute,
which stops macOS from running Koala's binaries: they are ad-hoc signed, not
signed with an Apple Developer ID or notarized. Homebrew is the recommended
path. If you use the archive, check its checksum first, then remove the
attribute from the extracted folder:

shasum -a 256 koala-0.1.0-preview.6-darwin-arm64.tar.gz   # must print 95efc70661876dce849f0575cfcb1c8e43e62347b3cd24ea9016a59c0c1e7e37
xattr -dr com.apple.quarantine koala-0.1.0-preview.6

Koala never removes the attribute itself. Keep the extracted folder: the
koala command runs from it.

Verify

• Archive sha256: 95efc70661876dce849f0575cfcb1c8e43e62347b3cd24ea9016a59c0c1e7e37
• Runtime release key: koala-release-1, public key sha256 8ca4ec5b8b366912a3398cc54c0eaa788012a91e86ba2007c96ecd07258a6288

Uninstall

koala system uninstall                # keeps VMs, volumes, images and runtimes
koala system uninstall --purge --yes  # deletes them, and Koala's keychain items
brew uninstall koala                  # with Homebrew, afterwards

Koala is licensed under the Apache License, Version 2.0. NOTICE lists the
third-party software in the binaries.

Koala 0.1.0-preview.5 (preview)

Koala 0.1.0-preview.5 (preview)

This is a preview release. Koala runs Linux VMs for development and CI on
Apple silicon Macs. Its security work is not complete:

• Done: testing against a VM whose root user is hostile (S02), and koala-net,
  the per-VM network policy helper, runs in the App Sandbox.
• Not done: the secret-free host broker, endurance and crash qualification,
  and the density checks (S03, S04, R03).

Use it with workloads and on machines you trust.

Changes since 0.1.0-preview.4

Fix: koala system install crashed on a new Mac

On a Mac where Koala had never been built, koala system install stopped
right after pulling the runtime with Fatal error: could not load resource bundle. This happened with both Homebrew and the archive. The installed
manager would have stopped the same way when it started.
(#3)

Koala's state database setup is now built into the binaries, and every
release is checked for this before it is published, including a run that
can't see the files on the Mac that built it.

Nothing else in Koala changed. The runtime and its release key are the same
as in preview.4.

New in the guide

• Run the Hermes agent: an example that runs the gateway of the Hermes
  AI agent as a service VM, from its official image. Its tools then reach
  only what the VM is granted.

Known issue

If the manager crashes or is killed while VMs are running, the VMs keep
running, but after the manager restarts their networking is marked degraded,
and a published port can stop answering. Stop and start that VM to restore it:
koala stop VM --wait, then koala start VM --wait.

Installing and upgrading

• If preview.4 failed to install: brew upgrade koala, then
  koala system install.
• If preview.4 is installed and running: the same. If VMs are running,
  add --stop-vms. macOS may ask once whether the new manager may use your
  stored registry logins and secrets: click Always Allow.

What's included

• The koala CLI, the per-user manager, the network helper and the image
  extractor, for Apple silicon Macs with macOS 26 or later.
• The lean runtime, which koala system install downloads from
  ghcr.io/kunalkushwaha/koala-runtime@sha256:a7aa01254e6adb20e4435e5c748f9b2459445f1c6730b9f4b995b8520cc5b5ec and verifies against the release key below.
• The full profile (systemd and Docker inside the VM) is not included
  in this preview.

Install

With Homebrew:

brew install kunalkushwaha/koala/koala
koala system install

From the archive:

tar -xzf koala-0.1.0-preview.5-darwin-arm64.tar.gz
koala-0.1.0-preview.5/bin/koala system install

An archive downloaded with a web browser carries the quarantine attribute,
which stops macOS from running Koala's binaries: they are ad-hoc signed, not
signed with an Apple Developer ID or notarized. Homebrew is the recommended
path. If you use the archive, check its checksum first, then remove the
attribute from the extracted folder:

shasum -a 256 koala-0.1.0-preview.5-darwin-arm64.tar.gz   # must print c137b7168b60f85e8aa769be901dbc73854b7ff0d15581331649c62bf81fa51b
xattr -dr com.apple.quarantine koala-0.1.0-preview.5

Koala never removes the attribute itself. Keep the extracted folder: the
koala command runs from it.

Verify

• Archive sha256: c137b7168b60f85e8aa769be901dbc73854b7ff0d15581331649c62bf81fa51b
• Runtime release key: koala-release-1, public key sha256 8ca4ec5b8b366912a3398cc54c0eaa788012a91e86ba2007c96ecd07258a6288

Uninstall

koala system uninstall                # keeps VMs, volumes, images and runtimes
koala system uninstall --purge --yes  # deletes them, and Koala's keychain items
brew uninstall koala                  # with Homebrew, afterwards

Koala is licensed under the Apache License, Version 2.0. NOTICE lists the
third-party software in the binaries.

Koala 0.1.0-preview.4 (preview)

Koala 0.1.0-preview.4 (preview)

This is a preview release. Koala runs Linux VMs for development and CI on
Apple silicon Macs. Its security work is not complete:

• Done: testing against a VM whose root user is hostile (S02), and koala-net,
  the per-VM network policy helper, runs in the App Sandbox.
• Not done: the secret-free host broker, endurance and crash qualification,
  and the density checks (S03, S04, R03).

Use it with workloads and on machines you trust.

Changes since 0.1.0-preview.3

The network helper runs in the App Sandbox

koala-net, the helper that enforces each VM's network policy, now ships as
KoalaNet.app and runs in macOS's App Sandbox. Its only entitlements are the
sandbox itself and network client and server access. It cannot read your
files, your VMs' disks or Koala's own state. Before a VM gets its network, the
manager checks that the helper is sandboxed and correctly signed, and refuses
it otherwise.

One limit remains: Apple's sandbox still lets the helper open your login
keychain file. The items in it stay encrypted, and a tighter profile is
planned.

Tested against a hostile VM

Koala has now been tested against VMs whose root user is an attacker, on real
VMs, through the same signed and sandboxed processes this release ships:

• Host channels: a guest finds no host listener to connect to, cannot
  write the shared runtime images, and cannot reach Koala's sockets or secrets.
  Floods of output, serial and kernel log messages stay within fixed limits.
• Storage and credentials: a guest cannot read another VM's disk or
  volume, a volume it was not given, or a secret it was not granted. Koala's
  own tools never follow a link a guest plants in a shared folder.
• Network: spoofed and fragmented packets, IPv6, ARP, DNS rebinding and
  floods are blocked, on lean and full guests. A guest cannot reach other VMs'
  published ports or the network helper's controls.
• Everything at once: with all of these running together while VMs were
  cancelled, stopped and restarted, the manager's memory, file descriptors and
  disk use stayed bounded, and an unrelated VM kept serving.

The secret-free host broker and the endurance tests are still to come, so the
warning above still applies.

Fixes

• A registry pinned to a specific TLS certificate could not download images or
  runtimes in preview.3. It can again. Registries without a pin were not
  affected.

A small koala

koala --help and a bare koala show a small koala above the command list,
when the output goes to a terminal. Piped output, errors and --version are
unchanged.

Known issue

If the manager crashes or is killed while VMs are running, the VMs keep
running, but after the manager restarts their networking is marked degraded,
and a published port can stop answering. Stop and start that VM to restore it:
koala stop VM --wait, then koala start VM --wait.

Upgrading

brew upgrade koala, then koala system install. If VMs are running, add
--stop-vms. macOS may ask once whether the new manager may use your stored
registry logins and secrets: click Always Allow.

What's included

• The koala CLI, the per-user manager, the network helper and the image
  extractor, for Apple silicon Macs with macOS 26 or later.
• The lean runtime, which koala system install downloads from
  ghcr.io/kunalkushwaha/koala-runtime@sha256:a7aa01254e6adb20e4435e5c748f9b2459445f1c6730b9f4b995b8520cc5b5ec and verifies against the release key below.
• The full profile (systemd and Docker inside the VM) is not included
  in this preview.

Install

With Homebrew:

brew install kunalkushwaha/koala/koala
koala system install

From the archive:

tar -xzf koala-0.1.0-preview.4-darwin-arm64.tar.gz
koala-0.1.0-preview.4/bin/koala system install

An archive downloaded with a web browser carries the quarantine attribute,
which stops macOS from running Koala's binaries: they are ad-hoc signed, not
signed with an Apple Developer ID or notarized. Homebrew is the recommended
path. If you use the archive, check its checksum first, then remove the
attribute from the extracted folder:

shasum -a 256 koala-0.1.0-preview.4-darwin-arm64.tar.gz   # must print a8408140e447cb796b2c6245cb680874b37e1dd08ab86c85c5466391c8b655f2
xattr -dr com.apple.quarantine koala-0.1.0-preview.4

Koala never removes the attribute itself. Keep the extracted folder: the
koala command runs from it.

Verify

• Archive sha256: a8408140e447cb796b2c6245cb680874b37e1dd08ab86c85c5466391c8b655f2
• Runtime release key: koala-release-1, public key sha256 8ca4ec5b8b366912a3398cc54c0eaa788012a91e86ba2007c96ecd07258a6288

Uninstall

koala system uninstall                # keeps VMs, volumes, images and runtimes
koala system uninstall --purge --yes  # deletes them, and Koala's keychain items
brew uninstall koala                  # with Homebrew, afterwards

Koala is licensed under the Apache License, Version 2.0. NOTICE lists the
third-party software in the binaries.

Koala 0.1.0-preview.3 (preview)

Koala 0.1.0-preview.3 (preview)

This is a preview release. Koala runs Linux VMs for development and CI on
Apple silicon Macs. Its security proofs are not complete:

• koala-net, the per-VM network policy helper, does not yet run in the App
  Sandbox (S02).
• The isolation and density acceptance checks (S03, S04, R03) are not done.

Use it with workloads and on machines you trust.

Changes since 0.1.0-preview.2

A clearer command line

• New help. koala --help lists the commands in groups, with a
  one-line description each. koala COMMAND --help (or -h, or
  koala help COMMAND) shows a command's usage, options and examples.
  For example: koala create --help, koala volume create --help.
• Short errors. A mistyped command now prints two or three lines that
  point to the right help page, instead of the whole command list.
• Docker's names work too. koala ps and koala ls list VMs, and
  koala images lists images. koala image ls and koala volume ls are
  the same as their list commands.

Security hardening

Koala reads data from registries, from release downloads, and from the
processes and VMs it runs. This release makes sure none of it can exhaust
the Mac's memory or disk before it is checked:

• Registries: token responses and runtime-release downloads are cut off
  as soon as they pass their limit, instead of being read in full first.
  Image configs are limited to 4 MiB, and authentication challenges to
  4 KiB.
• Runtime releases: a release's index and signature must be small. They
  are checked while they are decompressed, before the signature is
  verified. Every other file stops at its signed size.
• Local channels: a VM's worker can no longer send unbounded output for
  one request, and list cursors and file-transfer paths have length limits.

Fuzz testing. Every place where Koala decodes untrusted data, 71 in all,
is listed and fuzz-tested.

• The qualification run gave each Swift decoder at least 100,000
  generated inputs and 5 minutes under AddressSanitizer. The C transfer
  helper got 100,000 inputs under AddressSanitizer and UndefinedBehavior
  Sanitizer, and the Go network-helper parsers ran 78–213 million
  executions each.
• Result: no crashes, hangs, memory growth or descriptor leaks were
  found.

Isolation testing against a malicious VM is still to come, so the warning
above still applies.

Upgrading

brew upgrade koala, then koala system install. If VMs are running, add
--stop-vms. macOS may ask once whether the new manager may use your
stored registry logins and secrets: click Always Allow.

What's included

• The koala CLI, the per-user manager, the network helper and the image
  extractor, for Apple silicon Macs with macOS 26 or later.
• The lean runtime, which koala system install downloads from
  ghcr.io/kunalkushwaha/koala-runtime@sha256:a7aa01254e6adb20e4435e5c748f9b2459445f1c6730b9f4b995b8520cc5b5ec and verifies against the release key below.
• The full profile (systemd and Docker inside the VM) is not included
  in this preview.

Install

With Homebrew:

brew install kunalkushwaha/koala/koala
koala system install

From the archive:

tar -xzf koala-0.1.0-preview.3-darwin-arm64.tar.gz
koala-0.1.0-preview.3/bin/koala system install

An archive downloaded with a web browser carries the quarantine attribute,
which stops macOS from running Koala's binaries: they are ad-hoc signed, not
signed with an Apple Developer ID or notarized. Homebrew is the recommended
path. If you use the archive, check its checksum first, then remove the
attribute from the extracted folder:

shasum -a 256 koala-0.1.0-preview.3-darwin-arm64.tar.gz   # must print 5070e08a20a84896f4c141fddc9f00c8951e7f9c46d895eeaa15eabbfa088fe0
xattr -dr com.apple.quarantine koala-0.1.0-preview.3

Koala never removes the attribute itself. Keep the extracted folder: the
koala command runs from it.

Verify

• Archive sha256: 5070e08a20a84896f4c141fddc9f00c8951e7f9c46d895eeaa15eabbfa088fe0
• Runtime release key: koala-release-1, public key sha256 8ca4ec5b8b366912a3398cc54c0eaa788012a91e86ba2007c96ecd07258a6288

Uninstall

koala system uninstall                # keeps VMs, volumes, images and runtimes
koala system uninstall --purge --yes  # deletes them, and Koala's keychain items
brew uninstall koala                  # with Homebrew, afterwards

Koala is licensed under the Apache License, Version 2.0. NOTICE lists the
third-party software in the binaries.

Koala 0.1.0-preview.2 (preview)

Koala 0.1.0-preview.2 (preview)

This is a preview release. Koala runs Linux VMs for development and CI on
Apple silicon Macs. Its security proofs are not complete:

• koala-net, the per-VM network policy helper, does not yet run in the App
  Sandbox (S02).
• The isolation and density acceptance checks (S03, S04, R03) are not done.

Use it with workloads and on machines you trust.

Changes since 0.1.0-preview.1

• Fixed: deeply nested JSON could crash the manager. A request to the
  manager's socket, a registry's token response, or file-transfer and log
  messages from a VM could stop the manager if they held deeply nested
  brackets. Koala now refuses JSON nested more than 64 levels deep with an
  error, and the manager keeps running.
• Upgrading: brew upgrade koala, then koala system install. If VMs
  are running, add --stop-vms. macOS may ask once whether the new manager
  may use your stored registry logins and secrets: click Always Allow.

What's included

• The koala CLI, the per-user manager, the network helper and the image
  extractor, for Apple silicon Macs with macOS 26 or later.
• The lean runtime, which koala system install downloads from
  ghcr.io/kunalkushwaha/koala-runtime@sha256:a7aa01254e6adb20e4435e5c748f9b2459445f1c6730b9f4b995b8520cc5b5ec and verifies against the release key below.
• The full profile (systemd and Docker inside the VM) is not included
  in this preview.

Install

With Homebrew:

brew install kunalkushwaha/koala/koala
koala system install

From the archive:

tar -xzf koala-0.1.0-preview.2-darwin-arm64.tar.gz
koala-0.1.0-preview.2/bin/koala system install

An archive downloaded with a web browser carries the quarantine attribute,
which stops macOS from running Koala's binaries: they are ad-hoc signed, not
signed with an Apple Developer ID or notarized. Homebrew is the recommended
path. If you use the archive, check its checksum first, then remove the
attribute from the extracted folder:

shasum -a 256 koala-0.1.0-preview.2-darwin-arm64.tar.gz   # must print 697e2fd50732b4b1e5cf92507d331cd2b39e1208961ef7e6cfc0ae744cbad460
xattr -dr com.apple.quarantine koala-0.1.0-preview.2

Koala never removes the attribute itself. Keep the extracted folder: the
koala command runs from it.

Verify

• Archive sha256: 697e2fd50732b4b1e5cf92507d331cd2b39e1208961ef7e6cfc0ae744cbad460
• Runtime release key: koala-release-1, public key sha256 8ca4ec5b8b366912a3398cc54c0eaa788012a91e86ba2007c96ecd07258a6288

Uninstall

koala system uninstall                # keeps VMs, volumes, images and runtimes
koala system uninstall --purge --yes  # deletes them, and Koala's keychain items
brew uninstall koala                  # with Homebrew, afterwards

Koala is licensed under the Apache License, Version 2.0. NOTICE lists the
third-party software in the binaries.

Koala 0.1.0-preview.1 (preview)

Koala 0.1.0-preview.1 (preview)

This is a preview release. Koala runs Linux VMs for development and CI on
Apple silicon Macs. Its security proofs are not complete:

• koala-net, the per-VM network policy helper, does not yet run in the App
  Sandbox (S02).
• The isolation and density acceptance checks (S03, S04, R03) are not done.

Use it with workloads and on machines you trust.

What's included

• The koala CLI, the per-user manager, the network helper and the image
  extractor, for Apple silicon Macs with macOS 26 or later.
• The lean runtime, which koala system install downloads from
  ghcr.io/kunalkushwaha/koala-runtime@sha256:a7aa01254e6adb20e4435e5c748f9b2459445f1c6730b9f4b995b8520cc5b5ec and verifies against the release key below.
• The full profile (systemd and Docker inside the VM) is not included
  in this preview.

Install

With Homebrew:

brew install kunalkushwaha/koala/koala
koala system install

From the archive:

tar -xzf koala-0.1.0-preview.1-darwin-arm64.tar.gz
koala-0.1.0-preview.1/bin/koala system install

An archive downloaded with a web browser carries the quarantine attribute,
which stops macOS from running Koala's binaries: they are ad-hoc signed, not
signed with an Apple Developer ID or notarized. Homebrew is the recommended
path. If you use the archive, check its checksum first, then remove the
attribute from the extracted folder:

shasum -a 256 koala-0.1.0-preview.1-darwin-arm64.tar.gz   # must print 31dc0a6f14f8e1f5aa3b497f5957061704103c2f12002a3a46cdb2d800b16365
xattr -dr com.apple.quarantine koala-0.1.0-preview.1

Koala never removes the attribute itself. Keep the extracted folder: the
koala command runs from it.

Verify

• Archive sha256: 31dc0a6f14f8e1f5aa3b497f5957061704103c2f12002a3a46cdb2d800b16365
• Runtime release key: koala-release-1, public key sha256 8ca4ec5b8b366912a3398cc54c0eaa788012a91e86ba2007c96ecd07258a6288

Uninstall

koala system uninstall                # keeps VMs, volumes, images and runtimes
koala system uninstall --purge --yes  # deletes them, and Koala's keychain items
brew uninstall koala                  # with Homebrew, afterwards

Koala is licensed under the Apache License, Version 2.0. NOTICE lists the
third-party software in the binaries.