Skip to main content
A Mac runs Levelrail through a private Linux VM managed by Lima. This page covers readiness checks, VM controls and launchd. For joining a Mac as a node agent see macOS node agent.
Experimental. Set APP_VM_EXPERIMENTAL=on to use the vm commands. The checks and launchd commands below were unit tested with fakes. They have not been run against a real VM from a published release.

Quick start

doctor macos works offline and exits 1 when a check fails. It reports:

VM controls

CPU, memory and disk are settings stored in a host file. The environment only seeds them at vm init.
Memory is capped to a share of host memory (APP_VM_MEMORY_MAX_PERCENT, default 50). A changed value applies at the next vm stop and vm start.

Keep it running with launchd

Units are per-user, in ~/Library/LaunchAgents, labelled com.levelrail.agent or com.levelrail.control-plane. Logs go to ~/Library/Logs/Levelrail. The respawn gap is APP_LAUNCHD_THROTTLE_SECONDS (default 30). Enrol the agent once in the foreground first. Tokens and secrets are refused in --env; keep them in the service env file.

Install

install-cli.sh picks the darwin binary for arm64 or amd64 and verifies it against checksums.txt, and against the release signature when cosign is present.

Supported and not supported

  • Supported: Apple silicon and Intel, macOS 13 or newer, Lima with the vz driver, a node agent under launchd.
  • Not supported: running the control plane natively on macOS, Docker Desktop managed by Levelrail, host folder mounts into the VM, Windows or Linux hosts for these commands.
  • Binaries are not notarized by Apple.
Last modified on November 22, 2026