PREVIEW · DISTRIBUTION COMING SOON

Linux compute
on your Mac.
One command.

A Linux Incus host for Apple Silicon.

Macus boots a real Linux VM with Apple’s Virtualization.framework, runs Incus inside it, and gives you, and your agents, one local HTTPS endpoint.

  • Apple Silicon
  • macOS 15+
  • No GUI. No SSH.

/ WHAT MACUS START DOES

Five stages.
Zero hand-holding.

Success means live Incus readiness and a working client, not merely that a process launched. If a step fails, start tells you what it left running.

  1. 01

    Check the host

    Confirms Apple Silicon virtualization support and the executable’s virtualization entitlement before anything changes.

  2. 02

    Verify the appliance

    Downloads the pinned Alpine Linux appliance and checks it against the digest built into Macus.

  3. 03

    Activate services

    Registers two per-user launchd services: the Swift runtime that owns the VM, and the Macus server.

  4. 04

    Boot Linux + Incus

    Creates the VM, initializes ZFS storage and Incus, and waits for live readiness, not just a running process.

  5. 05

    Connect your client

    Adds the standard incus client as remote “macus” and enrolls its certificate with the server.

/ ARCHITECTURE

One endpoint in.
Private sockets behind it.

Clients only ever talk to the Macus server. It authenticates the caller before reaching the private sockets that lead into the Linux guest.

CLIENTS
incusstandard client
macusCLI
AI agentMCP client
YOUR MAC · macOS
Macus server127.0.0.1:8443
/1.0Native Incus API
/runtimeVM lifecycle
/mcpsearch · execute
Swift runtime serviceVirtualization.framework
LINUX GUEST · Alpine
Incuscontainers + VMs
ZFS poolseparate data disk
Default local setup. LAN or remote HTTPS can be enabled explicitly with your own address and certificate.

/ BUILT FOR AGENTS

Give an agent
exactly what it needs.

The /mcp endpoint advertises two tools, search and execute, over every Incus operation plus Macus’s own runtime operations. A scoped bearer token decides what an agent can see and do. Revoking it ends in-flight requests within seconds.

Issue a read-only agent token
macus server token issue --principal agent \
  --scope incus.read --scope runtime.read \
  --expires-in 7d --output /Users/you/agent.token
Read the MCP guide
TOKEN SCOPESA scope reveals and permits
  • incus.readInspect servers, projects, instances, images, networks and storage
  • incus.writeCreate and change instances, images and snapshots
  • incus.execRun one bounded command in a named instance
  • incus.deleteDelete workloads (confirmed)
  • runtime.readRead VM status, progress, health and capabilities
  • runtime.writeStart, stop and restart the Linux appliance
Native one-to-one Incus scopes are separate.
Nothing implies them. You grant them by name.

/ DAY TO DAY

It’s just Incus.
On a Mac.

Standard Incus, unmodified

Use the incus client you already know. Instances, images, profiles, projects, networks and storage all behave as native Incus, including exec over WebSockets.

Persistent by default

Workloads live on a ZFS pool on a separate data disk. They survive guest restarts, daemon restarts and package upgrades, and repeating macus start never replaces a disk.

Out of your way

launchd keeps both services running after you close the terminal. Repeating macus start reuses everything already set up, and never reboots a ready guest.

/ INSTALL

Get ready for Macus.
Prebuilt releases are on the way.

Signed downloads and the Homebrew tap are being prepared. You can build from source today.

Coming soon

Download for macOS

A Developer ID–signed, notarized macOS download is being prepared. It will appear here and on the GitHub releases page.

Watch releases
Coming soon

Homebrew

Prebuilt ARM64 bottles from the Upmaru tap. The formula is published once its bottles pass acceptance.

Install with Homebrew
brew install upmaru/tap/macus
This command works once the formula is published.
Available

Build from source

Needs Xcode with Swift 6.4. Builds and ad-hoc signs the entitled executable into ~/.local.

Build and start from source
git clone --branch develop \
  https://github.com/upmaru/macus.git
cd macus
Packaging/install-local.sh
export PATH="$HOME/.local/bin:$PATH"
macus start
Full walkthrough

/ AFTER INSTALLING

Start once, then use Incus.

The first start downloads the appliance and boots Linux. Later starts reuse what is already there.

First run
macus start
incus launch images:debian/13 macus:dev
incus list macus:

System requirements

  • Apple Silicon MacVirtualization.framework on ARM64. Intel Macs are not supported.
  • macOS 15 or laterUnsupported hosts fail before anything is downloaded or changed.
  • 4 GiB memory for the guestReserved while the Linux appliance is running.
  • Disk space for the applianceA 12 GiB writable root plus a 32 GiB sparse data disk that only uses space as workloads fill it.
  • Internet on first startTo fetch the pinned appliance image and workload images.
  • Homebrew, if incus is missingmacus start installs the official incus formula when no incus client is on your PATH. It never installs Homebrew or uses sudo.

Upgrading or uninstalling? Stop the runtime and unload its service first. Your disks and Incus configuration are kept. Upgrade and removal steps

/ WHAT’S NEXT

Shipping next.
Planned in the open.

Every change is specified before it’s built. Follow the plans in the Macus repository.

NEXTIn progress

Prebuilt appliance images

Locked, pre-qualified Linux images so first boot installs nothing, with an opt-in newer-kernel channel.

NEXTIn progress

Signed, notarized downloads

A Developer ID–signed macOS download alongside the Homebrew tap.

LATERPlanned

macus connect

Optionally register your Mac with central Opsmaru, so its Incus joins your other targets. Local use keeps working without it.

LATERPlanned

Automatic appliance upgrades

Move the Linux root image forward without touching your data disk.

/ MACUS FAQ

Good questions.

Is this Docker Desktop?

No. Macus runs Incus, which manages full system containers and virtual machines. You use the standard Incus client and API. Docker or Compose compatibility is not part of Macus.

Do I need a GUI, SSH or a separate VM app?

No. Macus is headless and uses Apple’s Virtualization.framework directly. Everything goes through the macus and incus commands, or the local HTTPS endpoint.

Can I run virtual machines inside Macus?

Containers work on every supported Mac. Incus VMs inside the appliance need nested virtualization from the host and usable KVM in the guest. Macus detects this at runtime and reports what it observed instead of guessing.

Does closing the terminal stop it?

No. macus start hands both services to launchd, so they keep running. Use macus runtime stop to shut down the Linux guest.

What happens to my workloads when I upgrade or uninstall?

They stay. Upgrades and removal never delete the runtime disks or your Incus configuration. Stop the runtime and unload its service before changing the package, then run macus start again.

Is it the same as Opsmaru?

Macus is one compute host in the Opsmaru stack. It embeds the same opsmaru_incus library and agent interface that central Opsmaru uses, and works standalone today. Registering a Mac with central Opsmaru is planned.

PART OF THE OPSMARU COMPUTE SUBSTRATE

Your Mac.
Real Linux compute.

The same Incus operations and agent interface, from your laptop to the cloud.