Caker

Virtualization platform for macOS

View project on GitHub

Development

Code organization

  • Sources/cakectl/Commands/ – CLI command handlers
  • Sources/caked/Commands/ and Sources/caked/Handlers/ – daemon command and runtime handlers
  • Sources/cakedlib/ – shared utilities, config, and core abstractions

VM image catalog (Caker.app wizard, and build/launch --alias)

Caker.app’s VM creation wizard (Sources/caker/Views/VirtualMachineWizard.swift) offers preconfigured ISO, IPSW, and cloud (qcow2) image choices. That list is no longer hardcoded in Swift enums — it’s driven by a bundled JSON resource, decoded at runtime. The catalog now lives in CakedLib (it used to be caker-only), so caked build/cakectl build (and launch) can also resolve a catalog id via a single --alias <id> option (--alias macos12, --alias ubuntu2604, …) — run caked aliases/cakectl aliases to list every known id. See Sources/Grpc/options/BuildOptions.swift and CLAUDE.md’s “VM image catalog, --alias, and the aliases command” section for that half of the picture.

  • Sources/cakedlib/Resources/VMImages.json – the catalog, keyed by architecture at the top level: {"arm64": {...}, "amd64": {...}}, each node holding three arrays — iso, ipsw, cloud — of already-resolved {id, label, url} entries (no {arch} template to substitute at runtime). An image that doesn’t exist for a given architecture is simply absent from that array — e.g. the Fedora 41 Workstation ISO, never published for aarch64, only appears under amd64.
  • Sources/cakedlib/VMImageCatalog.swift – VMImageCatalog/VMImageArchCatalog/VMImageEntry (all public), the matching Codable model. VMImageCatalog.current (and the availableISOImages/availableIPSWImages/availableCloudImages shortcuts) picks the arm64 or amd64 node based on the running architecture via #if arch(arm64).

iso and cloud entries also carry optional minCPU/minMemoryMiB fields, absent from ipsw entries (macOS installs apply their own fixed floor independently of this catalog). Current convention: 2 CPU / 2048 MiB for “Server” ISOs and cloud images (headless by nature), 4 CPU / 4096 MiB for “Desktop” ISOs. VMImageEntry.applyMinimumResources(to:) (VirtualMachineWizard.swift) applies this floor via max(...) whenever an image is selected or the image source switches to .iso/.qcow2 — it never lowers a value the user already raised above the minimum.

To add or update an entry, edit VMImages.json — no Swift changes needed. Tests/CakerTests/VMImageCatalogURLTests.swift HEAD-requests every ISO/cloud URL from both architectures (bounded to 8 concurrent requests) so stale links get caught by swift test instead of silently breaking the wizard; dedicated tests also assert Fedora 41 Workstation stays absent from the arm64 node, and that every entry follows the minCPU/minMemoryMiB convention above.

Loading sources

VMImageCatalog.shared resolves the catalog in this order, on first use:

  1. <CAKE_HOME>/VMImages.json, if present and valid — either dropped there by hand (to pin or customize the list) or already cached by a previous GitHub refresh. An invalid file here is skipped (falls through to the next step) rather than crashing the app, since unlike the bundled resource it’s user-supplied state, not a packaging invariant.
  2. The bundled VMImages.json resource, following the same Bundle.module/native-target fallback already used by PackerLiteTemplateResolver for CakedLib’s other bundled resources: Bundle.module for swift build/swift test builds, falling back to a Bundle(for:)-plus-.bundle-lookup dance for Caker.xcodeproj/CakerAppStore.xcodeproj, which mirror CakedLib as a native Xcode target with no generated Bundle.module accessor. Any new file added under Sources/cakedlib/Resources/ therefore also needs to be added by hand to both .xcodeproj files (file reference + the CakedLib/Caker/caked.app targets’ Resources build phases, as applicable) to stay available in Xcode-built binaries.

Separately, VMImageCatalog.refreshFromGitHub() downloads the current VMImages.json from the main branch on GitHub, caches it to <CAKE_HOME>/VMImages.json, and updates VMImageCatalog.shared in place. MainApp.init() fires this in a background task (best-effort, errors ignored) at app launch — since the wizard’s views re-read VMImageCatalog.shared on every render rather than caching it in @State, an already-running session picks up the refreshed catalog as soon as the download completes, no restart needed.

That holds in .app mode. Connected to a caked (service or remote mode), the wizard lists that caked’s catalog instead, fetched with the Aliases RPC (the one behind cakectl aliases, which also returns each entry’s URL and minimum resources) every time the wizard opens, so the pickers offer what that caked’s host can build (its architecture, its own <CAKE_HOME>/VMImages.json). If the RPC fails, or the caked is too old to send URLs, the wizard keeps its own catalog. On its side, caked re-reads <CAKE_HOME>/VMImages.json whenever the file changes (VMImageCatalog.reloadIfChanged()), so a GitHub refresh done by Caker.app is picked up without restarting the service.

The web UI does the same through GET /1.0/vm-images (a Caker extension of the REST API, like /1.0/remotes): the create-instance dialog lists the catalog of the caked serving it. Until the reply arrives, or when the endpoint is missing (an older caked), it uses src/data/vmImages.ts, the copy npm run sync-vm-images bakes in at build time.

Compose template library

Sources/cakedlib/ComposeLibrary.swift loads the library of compose.yml templates like VMImageCatalog loads VMImages.json, except that a template is a file: the Sources/cakedlib/Resources/compose-library/ folder holds one <id>.yml per template and an index.json listing their ids. <CAKE_HOME>/compose-library/ (the synced copy, written by a sync: it then holds index.json) takes precedence over the bundled folder; a template that can’t be read there is skipped without discarding the others. ComposeLibrary.refreshFromGitHub() (compose library sync, the “Sync” button of ComposeLibraryView) downloads index.json and then each <id>.yml from the main branch; until the folder is published there, the 404 is reported and the bundled copy is used. A downloaded library is refused as a whole when one template is invalid (valid and unique ids, YAML that decodes to a ComposeFile, at least one service); every id of the index becomes a file name, so it is validated before anything touches the disk.

To add or change a template, edit Sources/cakedlib/Resources/compose-library/<id>.yml (a compose.yml whose first lines are # library-id/name/category/summary/tags comments, removed from the text clone writes), add its id to index.json (it is what sync downloads) and check it:

swift test --filter ComposeLibraryTests

The test also checks that index.json lists exactly the files of the folder.

ComposeLibraryTests runs every service of every template through toBuildOptions, which catches invalid YAML or a field compose up can’t honour. A template names its peers by their compose DNS name (<service>.<project>.compose.internal): the project must be its own, which the test also checks (clone --name renames those references).

A template that serves something must forward its ports to the host with ports: (and sockets: for a unix socket, like docker-host’s Docker socket): without it the service is only reachable from the VM network. The forwards of docker-host, k3s and ubuntu-dev are pinned by ComposeLibraryTests.

Build options

Environment variables read by Package.swift:

Variable Effect
APPSTORE=1 App Store build: sandboxed, no Sparkle, no DHCP server.
USE_DHCP_SERVER=1 Includes the per-network DHCP server (off by default; the debug and release signed-build scripts turn it on).
USE_AUTHORIZATION_HELPER=1 Compiles and ships the privileged AuthorizationHelper (off by default; signed debug and release builds only). caked authorization enable or disable registers it (through Caker.app). The DHCP server can be turned off in Settings > Advanced (local.use-dhcp-server).
BECOME_PARANOID=1 Defines the BECOME_PARANOID flag: sudo rule pinned by SHA-256, caked and its bundle owned by root, a helper that only runs a root-owned caked, network PID directory pinned by descriptor against symlink swaps. Off by default.

BECOME_PARANOID=1 also drives .ci/create-pkg.sh: the package’s postinstall then pins the digest and refreshes it for every user. For a strict package, use the same variable for both steps:

BECOME_PARANOID=1 swift build
BECOME_PARANOID=1 .ci/create-pkg.sh

The Xcode projects do not use Package.swift: add BECOME_PARANOID to their compilation conditions by hand. See Architecture.

Tests

Primary test locations:

  • Tests/CakerTests/
  • Caker/CakerTests/
  • integration/tests/

Contribution workflow

  1. Create a branch from main.
  2. Implement focused changes.
  3. Run relevant tests and build checks.
  4. Open a pull request with clear context.

Contributor guide:

Web UI

Caker includes a React-based web UI located in the webui/ directory. It is built with Vite, TypeScript, and Bootstrap 5.

Requirements

  • Node.js ≥ 18
  • npm ≥ 9

Install dependencies

cd webui
npm install

Development mode

Start the Vite dev server with a proxy to a locally running caked:

cd webui
npm run dev

The dev server listens on http://localhost:5173. API calls to /1.0 are proxied to http://127.0.0.1:8080 by default. Override the target with the VITE_API_TARGET environment variable:

VITE_API_TARGET=http://127.0.0.1:9090 npm run dev

Production build

cd webui
npm run build

The output is written to webui/dist/. Pass this directory to caked with the --web-ui flag:

caked service --rest --web-ui /path/to/caker/webui/dist

The UI is then served at http://<host>:<port>/ui.

Deploying from a zip archive

--web-ui also accepts a .zip archive. caked extracts it automatically at startup to a temporary directory:

cd webui && npm run build && zip -r ../webui-dist.zip dist/
caked service --rest --web-ui /path/to/webui-dist.zip

If the archive contains a single top-level directory (e.g. dist/), caked descends into it automatically so the index file is resolved correctly.

Project structure

webui/
  index.html            # HTML entry point
  vite.config.ts        # Vite configuration (base /ui/, proxy /1.0)
  tsconfig.json         # TypeScript configuration
  src/
    main.tsx            # React entry point (Bootstrap CSS/JS imported here)
    App.tsx             # HashRouter + routes
    types/lxd.ts        # TypeScript interfaces matching the REST API
    api/                # axios API client modules
    components/         # Shared UI components (Layout, StatusBadge, …)
    pages/              # One component per page
  dist/                 # Production output (after npm run build)

Useful scripts

  • Scripts/build-signed-debug.sh - Build debug version with signing
  • Scripts/build-signed-release.sh - Build release version with signing
  • Scripts/build-signed-snapshot.sh - Build package and dmg with signing
  • Scripts/act.sh - Local GitHub Actions testing
  • Scripts/run-signed-caked.sh - Run signed daemon
  • Scripts/run-signed-cakectl.sh - Run signed CLI

Development Environment

Requirements

  • macOS (required for Virtualization framework)
  • Xcode with Swift toolchain
  • Signing certificates and provisioning profiles
  • Optional: GitHub CLI for pull request management

Getting Started

  1. Clone the repository
  2. Run ./Scripts/build-signed-debug.sh to build
  3. Use the run scripts to test components
  4. Run tests via Xcode or command line

Code Style

  • Follow Swift conventions
  • Use clear, descriptive naming
  • Add documentation for public APIs
  • Include tests for new functionality