Caker

Virtualization platform for macOS

View project on GitHub

Architecture

Components

  • caked command line tool (Sources/caked/): core background daemon
  • cakectl command line tool (Sources/cakectl/): command-line controller
  • CakedLib common library (Sources/cakedlib/): shared library code
  • GRPCLib communication libray (Sources/grpc/): communication contracts and streaming/client interfaces
  • Caker.app (Sources/caker/): GUI source
  • LXD REST API (Sources/caked/REST/): optional LXD-compatible HTTP/HTTPS server built into caked
  • Web UI (webui/): React/Vite frontend served by caked at /ui

High-level flow

  1. cakectl sends commands to caked over gRPC
  2. caked executes lifecycle/resource operations
  3. Responses and streams are transmitted through gRPC back to clients
  4. Logs/status are returned to clients

Optionally, external LXD-compatible tooling communicates with caked through the REST API:

  1. caked starts an HTTP(S) listener alongside the gRPC server when --rest is set
  2. LXD REST clients (e.g. lxc, the web UI, or any HTTP client) call /1.0/... endpoints
  3. caked translates REST requests into the same internal operations used by gRPC

Service responsibilities

caked is responsible for:

  • lifecycle management (build, launch, start/stop/restart/suspend/delete)
  • resource allocation
  • health monitoring
  • logging and diagnostics
  • optional LXD-compatible REST API (instances, networks, images, certificates, identities, operations)
  • optional Web UI hosting

LXD REST API

When started with --rest, caked exposes an LXD-compatible REST API:

Endpoint group Description
/1.0 Server info and capabilities
/1.0/instances VM lifecycle, state, exec, console, logs
/1.0/networks Network management
/1.0/images Image listing and metadata
/1.0/operations Async operation tracking
/1.0/certificates TLS certificate management
/1.0/auth-groups Authorization groups
/1.0/identities Identity management

Default ports: 8443 (HTTPS/mTLS) or 8080 (HTTP). Override with --rest-port.

IMDS

caked also hosts, by default, an AWS-style instance metadata service for Linux VMs (IMDSCoordinator + IMDSServer in Sources/caked/IMDS/), reachable from the guest over HTTP. Reaching it at the AWS-style 169.254.169.254 address relies on a pf address-alias redirect installed automatically by a short-lived root helper, since caked normally runs unprivileged; without it, the IMDS gateway itself stays fully reachable on its own port. See IMDS for full details.

See Command Summary for full service listen flag reference.

Privileges and passwordless sudo

A few operations need root: starting a vmnet network (and its DHCP/DNS server), importing a Multipass instance that lives under /var/root, or installing /etc/paths.d/com.aldunelabs.caker. The direct-download build hands them to a privileged helper (Sources/helper, shipped as Caker.app/Contents/Helpers/AuthorizationHelper and signed with its own identity; an SMAppService daemon reached over XPC and guarded by an Authorization right) that the user approves once in System Settings > General > Login Items. The helper only accepts specific operations: startNetwork, runNetwork, setDHCPLease, imdsRedirect, importVirtualMachine (only --from=multipass, with two plain names and an allowlist of arguments) and installPriviligedFiles.

When the helper is not available, caked is run as root through sudo, thanks to a per-user sudoers rule: /etc/sudoers.d/caked-pinned-<uid>, one file per user so that several users logged in on the same Mac each have their own and never overwrite one another’s. It names that user (#<uid>), never %everyone, and the path of the bundled caked:

#501 ALL=(root:wheel) NOPASSWD:SETENV: /Applications/Caker.app/Contents/PlugIns/caked.app/Contents/MacOS/caked

It is written by the package’s postinstall (the installing user), by the helper (the calling user) and, as a last resort, by the app after an administrator prompt. The earlier /etc/sudoers.d/caked (the %everyone rule) and /etc/sudoers.d/caked-pinned (a single user) are removed. The file name has no dot, because sudo skips files that contain one.

BECOME_PARANOID mode. Built with BECOME_PARANOID=1 (see Development), the checks are stricter: the rule pins caked by its SHA-256 (sha256:<digest>), which sudo verifies on every run; it is only written when caked and every directory up to the .app are owned by root and not writable by others; and the helper only runs a root-owned caked. The digest changes with every release, so the postinstall rewrites it for each user that already has a rule, the helper does the same, and the app rewrites its own at launch when it no longer matches (for example after a Sparkle update). A copy dragged into /Applications or a DerivedData build gets no rule in this mode.

GUI activation from a terminal launch

caked’s GUI paths (Sources/caked/MainApp.swift, used by caker and by caked provision --foreground) are sometimes launched via fork/exec from a terminal or shell script rather than through Finder/LaunchServices. macOS does not automatically grant a process launched that way frontmost/active status, and SwiftUI’s App/WindowGroup scene lifecycle alone doesn’t compensate for this — the window can open fully behind other apps with no visible cue that it exists. AppDelegate works around this with a plain splash screen (NSWindow, not a SwiftUI Window/WindowGroup scene) shown at .floating level, plus three layered activation attempts (NSApp.activate(ignoringOtherApps:) in setDockIcon(), the splash window’s own .floating level, and a delayed NSApp.activate() fallback), transitioning to the real WindowGroup via EnvironmentValues().openWindow(id:) once applicationDidBecomeActive actually fires. See the comment above AppDelegate in Sources/caked/MainApp.swift for the full breakdown of each layer. This splash screen (SplashScreenView) now lives in CakedLib (Sources/cakedlib/UI/SplashScreenView.swift) and is reused as-is by VNCApp (Sources/cakedlib/UI/VNC/VNCApp.swift), the standalone VNC window cakectl provision opens — same problem, same fix, without duplicating the code.

Repository Structure

Sources/
├── caked/          # Daemon implementation
│   └── REST/       # LXD REST API server and controllers
├── caker/          # GUI app (macOS SwiftUI)
├── cakectl/        # CLI client
├── cakedlib/       # Shared libraries
├── helper/         # Privileged helper (SMAppService daemon)
└── grpc/           # gRPC definitions and generated code
scripts/            # Some useful scripts to build and other
webui/              # React/Vite web UI