D9010 VmApp architecture

For: anyone who wants to understand how D9010 VmApp works and why it is built this way. To build an app, read Building apps instead. To change the platform, read Contributing after this. The normative contract is Specification; this document explains it, and doesn't replace it.

1. The idea in one picture#

┌───────────────────────────── your Mac (host) ──────────────────────────────┐
│                                                                            │
│  D9010 VmApp Launcher (Electron) ── trusted, the same for every app        │
│   ├─ Library, permission sheet, inspector       (loader's own UI)          │
│   ├─ App windows: sandboxed Chromium renderers  (the app's UI: HTML/CSS/JS)│
│   │     no Node · no network · only window.vmapp                           │
│   └─ hostlib: packages, grants, one AppSession per running app             │
│           │ spawns                         ▲ bridge (JSON lines, Unix sock)│
│           ▼                                │                               │
│      vmapp-vm (native, ~0.8 MB) ── one per running app ────────────────────┼──┐
│           │ Apple Virtualization.framework                                 │  │
└───────────┼────────────────────────────────────────────────────────────────┘  │
            ▼                                                                   │
   ┌──────────────────── Linux VM (one per app, ~0.4 s to start) ─────────────┐ │
   │ /init = vmapp-init                                                       │ │
   │ /      = shared runtime image (read-only): native | node22 | dotnet8     │ │
   │ /app   = the app's core files (read-only)                                │ │
   │ /data  = the app's private data          ◄── host folder per app         │ │
   │ /host/f-<name>, pick-N, save-N           ◄── only what the user granted  │ │
   │                                                                          │ │
   │ the app's core (its "main process"), uid 1000 ◄──── vsock ───────────────┼─┘
   │ no network device (granted hosts only, via the proxy: see below)         │
   └──────────────────────────────────────────────────────────────────────────┘

An app is split exactly where Electron splits it:

• The UI (renderer) runs on the host, so it gets native rendering, fonts, input, accessibility and HiDPI.
• The core (main process) runs in a VM, so everything powerful it does (files, processes, CPU) is confined.

The only connection between the two is a message bridge that passes through the loader.

2. Layers, from the bottom up#

The untrusted layers (5 and 8) never talk to each other directly, and never touch the host except through layers the platform owns.

3. What happens when you click Launch#

Loader            hostlib/AppSession        vmapp-vm               VM: vmapp-init           App core
  │ Launch            │                        │                        │                       │
  │──grants?─────────►│ (permission sheet if needed; saved in grants/<id>.json)                  │
  │                   │──spawn(args)──────────►│                        │                       │
  │                   │                        │─boot kernel+initramfs─►│ mount runtime as /rt  │
  │                   │                        │  disks: runtime, core   │ extract core.cpio→/app│
  │                   │                        │  virtiofs: appdata,f-*  │ mount /host,/data     │
  │                   │                        │◄──────hello (vsock 1023)│                       │
  │                   │                        │──start{command,env}────►│ fork→chroot→uid 1000 ─►│ exec
  │                   │◄─ready line {socket}───│                        │                       │ listen $VMAPP_SOCKET
  │                   │──connect bridge (Unix sock → vsock 1024 → core socket)──────────────────►│
  │                   │──init {app, folders, data}──────────────────────────────────────────────►│
  │                   │◄─ready──────────────────────────────────────────────────────────────────│
  │                   │◄─request window.create {entry:index.html}───────────────────────────────│
  │◄─create window────│                                                                         │
  │  vmapp-ui://<id>/index.html (hash-checked, CSP)                                             │
  │                   │──reply {win:1}──────────────────────────────────────────────────────────►│

Measured on an M-series Mac: from spawn to the window's first message is under a second. A minimal app ran a full launch → window → calls → quit cycle in 0.64 s.

4. How a click in the UI reaches the core#

App UI (renderer)        preload-app.js (loader)    Loader main / AppSession          App core (VM)
window.vmapp.invoke('notes:list')
   │──ipc──────────────────►│──ipc────────────────────►│ (window → app lookup by webContents id)
   │                        │                          │──{"t":"invoke","id":7,"win":1,"channel":"notes:list"}──►│ ipcMain.handle
   │                        │                          │◄─{"t":"result","id":7,"result":[…]}──────────────────────│
   │◄─Promise resolves──────│◄─────────────────────────│   (also shown in the bridge inspector)

The other directions:

• window.vmapp.send works the same way, with no reply.
• webContents.send in the core becomes {"t":"emit"}, which the loader delivers to that one window.
• Requests from the core (window.create, dialog.open, …) go to the loader. The loader enforces the manifest's permissions and shows native dialogs. If a dialog grants a folder, it tells vmapp-vm to add a share to the running VM, and the folder appears as /host/pick-N.

5. Files and folders: how access is enforced#

Write-only never shares the destination. The core writes into an empty staging folder, and the host moves each finished file out: a file is finished once it has stopped changing for about a second, or when it is renamed from *.partial. The core can never see what the destination already contains.

The network (SPEC §8.3) follows the same idea: the host decides, and the VM has no device to go around it.

core ──HTTPS_PROXY──► 127.0.0.1:3128 (vmapp-init) ──vsock 1022: "open api.example.com:443?"──► vmapp-vm
                                       ▲                                                        │ rules, DNS, address check,
                                       └────────── vsock 1025: one per connection, raw bytes ◄──┘ connect to the checked address

• The core's HTTP client reaches a small HTTP proxy inside the VM through environment variables. For each connection the proxy asks the host over one vsock control connection, which the host opens only when the app has a grant.
• vmapp-vm checks the host and port against the user's grants, resolves the name itself, refuses it if any answer is a private or local address, connects, and opens a fresh vsock connection for the bytes. TLS passes through a CONNECT tunnel untouched.
• It reports each connection (host, port, bytes, time) to the loader as a net event. Revoking a host closes its open connections immediately.

The GPU (SPEC §8.6) reuses that tunnel for one more thing, a host service. Linux has no Metal, so the VM is not given a GPU API; it is given llama.cpp's RPC protocol, forwarded to a Metal server on the Mac.

core ── 127.0.0.1:50052 ──► vmapp-init ──vsock 1022: "service-open gpu"──► vmapp-vm ──► 127.0.0.1:PORT ──► rpc-server (Metal)
 ($VMAPP_GPU_RPC)                       ◄── vsock 1025: raw bytes ◄──────────┘          (sandbox-exec, one per app run)

• Only an app that asked for gpu and was allowed gets any of it. The loader (not the app, not the guest) starts the server, inside a deny-by-default macOS sandbox, on a loopback port it picked, and hands that endpoint to vmapp-vm on its command line.
• The guest names a service; vmapp-vm maps the name to the one endpoint it was started with. The guest never supplies an address.
• Everything stops together: the app, a revoke, the panic shortcut and the loader quitting end the server and its tunnels.

6. Lifecycle and process ownership#

• The loader owns every AppSession, and each session owns exactly one vmapp-vm child, which owns exactly one VM.
• The core exits → the VM powers off → vmapp-vm prints stopped → the session closes the app's windows.
• The user presses Stop → before-quit goes to the core, which gets 3 s → shutdown → write-only files are delivered.
• The loader quits → it stops every session.
• The loader crashes or is killed → each vmapp-vm sees its parent die (kqueue, plus EOF on stdin) and shuts its VM down. A VM can't outlive the loader.

7. Why it is built this way: choices and rejected alternatives#

Why D9010 VmApp? compares D9010 VmApp with Electron and with Electron + container backends in detail, including where those are still better.

8. Component map (where the code is)#