Skip to content

Add experimental macOS guest backend with Linux as default - #45

Merged
mkagenius merged 4 commits into
mainfrom
feat/macos-vm
Nov 21, 2026
Merged

mkagenius merged 4 commits into
mainfrom
feat/macos-vm

Conversation

@mkagenius

@mkagenius mkagenius commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

CodeRunner currently runs Linux guests through Apple's container CLI. This adds an experimental macOS guest backend using Tart and Apple Virtualization.framework, serving the existing REST and MCP APIs from inside the guest.

Linux remains the default. macOS is explicitly selected with ./install.sh --guest macos; no separate primary CLI is introduced.

Changes

  • Add macOS VM creation, provisioning, start/stop, status, SSH, GUI launch, and smoke-test commands.
  • Provision a pinned Python runtime, hash-locked packages, Jupyter, CodeRunner, and Chromium as a guest service that starts on boot.
  • Use per-VM credentials, pinned SSH host keys, a localhost-only API tunnel on port 8223, and no host filesystem mounts.
  • Support NAT and host-only networking, with DHCP address refresh after network changes.
  • Resolve skill paths and Python's working directory against the guest workspace.
  • Document setup, limitations, and the supplied screenshot of successful MCP execution.

Validation

Tested locally on an Apple M1 Pro with macOS 27.2, running a macOS 15.7.7 arm64 guest with 2 CPUs and 4 GiB RAM.

  • 22 unit tests pass; Ruff, ShellCheck, shell syntax, and whitespace checks pass.
  • Live REST and MCP Python execution and Chromium navigation pass.
  • Unauthenticated execution returns 401; the guest API is unreachable directly on its network address.
  • Named sessions retain Python state.
  • Files survive a VM reboot while Python memory resets; services resume without desktop login.
  • Host-only networking blocks the tested direct outbound connection while API execution remains available.
  • Guest reports kern.hv_vmm_present=1, confirming execution inside the VM.

Limits

This is a local development pilot with an external Tart dependency, not a hardened multitenant service. The guest runtime does not include every Linux image package or Linux-specific utility. Clipboard sharing is disabled, and the generated desktop login password currently needs manual entry. See macos/README.md for the full setup and boundaries.

Run CodeRunner inside a Tart-managed macOS guest with private credentials,
a localhost SSH tunnel, persistent storage, and optional host-only networking.
Keep the existing Linux installer path intact.

Validated on an M1 Pro with macOS 15.7.7 guest: REST and MCP execution, Chromium,
authentication, session state, reboot persistence, and offline networking.
@mkagenius
mkagenius marked this pull request as ready for review November 20, 2026 20:27
@mkagenius
mkagenius merged commit b04df6e into main Nov 21, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants