msb-omarchy

This project is an independent, unofficial testbed for display and GPU support in microsandbox microVMs on Apple Silicon. microsandbox runs Linux microVMs but has no display path; this project carries one in a fork of its runtime: a 2D virtio-gpu scanout shown in a native macOS window, virtio-input, a text clipboard over vsock, and virtio-snd through CoreAudio. The workload is a full Omarchy desktop (Hyprland + Quattro), chosen because a real compositor surfaces problems a test pattern would not. GPU status: the guest renders with Mesa's llvmpipe on the CPU and virtio-gpu carries finished frames to the host. Nothing is hardware-accelerated yet; Venus (guest Vulkan on the Mac GPU via MoltenVK) is described as the next experiment. What it provides: - A persistent desktop VM: create once, close and reopen the window, or stop and resume with files and settings preserved. - Native Mac integration: macOS display window, keyboard and pointer input, text clipboard sync, and audio output. - A desktop tuned for software rendering: two display profiles (light 1600x900, standard 1920x1080), larger text, opaque windows, and disabled animations, blur and shadows. A glFlush-to-glFinish shim makes the compositor wait for llvmpipe before each commit. - Applications from first boot: Chromium, Nautilus, Foot, CJK fonts and Fcitx5 Pinyin, with working default browser and file-manager associations. - Explicit file sharing: a writable Shared directory mounted at ~/Shared, reachable from the top bar and file-manager sidebar. - An isolated runtime with checksummed runtime and firmware downloads and project-local VM state. - Recorded validation: launcher and release tests, guest image checks, Mac smoke tests, screenshots and measurements tied to the tested image. Quick start requires an Apple Silicon Mac with Hypervisor.framework, Git, Python 3.9+, Homebrew, and host libraries (slp/krun/virglrenderer, molten-vk, libepoxy). Commands: bin/setup downloads and verifies the pinned runtime and firmware; bin/doctor checks host support; bin/run creates the desktop and opens its native window. The first run downloads a published guest image of roughly 6 GB. Each VM defaults to 4 vCPUs, 4G RAM and a 16G writable disk. The checkout must be at a short path because runtime socket paths must fit in 104 bytes. Daily operations include bin/run (create, resume or reopen), bin/run --no-display, bin/pause, bin/stop, bin/msb list, bin/screenshot, and bin/doctor. Multiple named desktops can run concurrently with distinct VNC ports. Reset is explicit via bin/reset --name work --yes. The Mac Command key maps to Super inside Omarchy; shortcuts include Command+Enter for a terminal, Command+K for shortcuts, Command+Shift+Enter for the browser, Command+Shift+F for the file manager, and Ctrl+Space to switch English/Chinese Pinyin input. VNC is available at vnc://127.0.0.1:5901 for the default desktop; the guest listener has no authentication and is forwarded only to loopback. Clipboard images are not supported. Configuration variables include NAME, PROFILE, CPUS, MEMORY, ROOT_DISK, SHARED_DIR, VNC_PORT, TAG, MSB_GPU_DISPLAY, plus advanced overrides MSB, MSB_LIBKRUNFW_PATH and MSB_HOME. Validation commands include bin/check, bin/smoke --profile light, bin/smoke --profile standard, bin/frame-check and bin/publish --check. Diagnostics include bin/measure-display and bin/display-shot, which attach to the single display.sock viewer slot and close any existing native viewer for that VM. Findings recorded by the project include: with NO_VIRGL the virtio-gpu device rejects every 2D command on macOS so the host never receives a frame, and the fork adds a 2D-only mode; Hyprland decides whether to wait for rendering from the DRM driver name, so on virtio-gpu it scans out half-drawn llvmpipe frames, fixed by a glFlush-to-glFinish shim; a desktop VM can be paused and resumed in about 30 ms but not checkpointed because virtio-gpu and virtio-snd cannot quiesce; and msb built locally against the macOS 27 SDK cannot take HVF checkpoints. Upstream status: display changes were proposed to microsandbox and msb_krun in August 2026 and withdrawn unreviewed on 2026-09-23 as too large to review and far behind. The fork is kept as a test vehicle rather than proposed as a whole. The project is not affiliated with or endorsed by microsandbox, libkrun, Omarchy or Hyprland. It complements omarchy-microsandbox, an Omarchy plugin for managing VMs; here the Omarchy desktop itself runs inside the VM. Licensed under MIT, with included runtime and guest software retaining their upstream licenses.