Skip to main content

​
Overview

The Vibe macOS app (apps/mac-host/) is a Swift application built on AppKit and SwiftUI. It manages the Alpine Linux VM lifecycle, project registration, package verification, and the embedded WebView that displays app UIs.

​
Key components

​
VM lifecycle

The app maintains a single persistent Alpine Linux VM shared across all open projects. The VM is started on first project open and kept running as long as any project is active.
  • VM start is handled by VMManager using Apple’s VZVirtualMachine API
  • The VM boots from a kernel + initrd bundled in the app’s Resources/ directory
  • A persistent data disk is attached for package cache and state storage

​
Project lifecycle

For each .vibeapp the user opens:
  1. PackageVerifier checks the Ed25519 signature → assigns trust state
  2. PackageExtractor extracts the archive to the package cache
  3. ProjectLifecycleManager registers the project via the EnsureProject RPC
  4. Services are opened (OpenProject) and started (StartProject) via vsock RPC
  5. A WKWebView is connected to the primary service port

​
State snapshots

Auto-save runs every 30 seconds (configurable via state.autosaveDebounceSeconds). Up to 100 snapshots are kept per project (configurable via state.retention.maxSnapshots). Snapshots are triggered via the SaveSnapshot RPC and stored in the project’s state directory on the data disk.

​
Scheme handler

VibeSchemeHandler handles vibe:// URLs for internal routing — used for host-to-WebView communication, capability prompt responses, and secret injection UI.

​
Build

Or from the repo root: