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.
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.
/ WHAT MACUS START DOES
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.
Confirms Apple Silicon virtualization support and the executable’s virtualization entitlement before anything changes.
Downloads the pinned Alpine Linux appliance and checks it against the digest built into Macus.
Registers two per-user launchd services: the Swift runtime that owns the VM, and the Macus server.
Creates the VM, initializes ZFS storage and Incus, and waits for live readiness, not just a running process.
Adds the standard incus client as remote “macus” and enrolls its certificate with the server.
/ ARCHITECTURE
Clients only ever talk to the Macus server. It authenticates the caller before reaching the private sockets that lead into the Linux guest.
127.0.0.1:8443/1.0Native Incus API/runtimeVM lifecycle/mcpsearch · execute/ BUILT FOR AGENTS
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.
macus server token issue --principal agent \
--scope incus.read --scope runtime.read \
--expires-in 7d --output /Users/you/agent.tokenincus.readInspect servers, projects, instances, images, networks and storageincus.writeCreate and change instances, images and snapshotsincus.execRun one bounded command in a named instanceincus.deleteDelete workloads (confirmed)runtime.readRead VM status, progress, health and capabilitiesruntime.writeStart, stop and restart the Linux appliance/ DAY TO DAY
Use the incus client you already know. Instances, images, profiles, projects, networks and storage all behave as native Incus, including exec over WebSockets.
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.
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
Signed downloads and the Homebrew tap are being prepared. You can build from source today.
A Developer ID–signed, notarized macOS download is being prepared. It will appear here and on the GitHub releases page.
Watch releasesPrebuilt ARM64 bottles from the Upmaru tap. The formula is published once its bottles pass acceptance.
brew install upmaru/tap/macusNeeds Xcode with Swift 6.4. Builds and ad-hoc signs the entitled executable into ~/.local.
git clone --branch develop \
https://github.com/upmaru/macus.git
cd macus
Packaging/install-local.sh
export PATH="$HOME/.local/bin:$PATH"
macus start/ AFTER INSTALLING
The first start downloads the appliance and boots Linux. Later starts reuse what is already there.
macus start
incus launch images:debian/13 macus:dev
incus list macus: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
Every change is specified before it’s built. Follow the plans in the Macus repository.
/ MACUS FAQ
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.
No. Macus is headless and uses Apple’s Virtualization.framework directly. Everything goes through the macus and incus commands, or the local HTTPS endpoint.
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.
No. macus start hands both services to launchd, so they keep running. Use macus runtime stop to shut down the Linux guest.
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.
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
The same Incus operations and agent interface, from your laptop to the cloud.