A desktop AI workspace inspired by Anthropic's Claude Cowork, with its own twists: cross-OS (Apple Virtualization.framework on macOS, HCS on Windows), a persistent multi-session model (one VM, N concurrent agent loops), and hibernate/resume to bound memory.

A Go host service boots a Linux utility VM, a Python/OpenHands agent loop runs the agent inside that VM, and an Electron/React app is the UI. The older TypeScript agent remains as a reference path. The agent works on local files safely by containment — the VM is the cage, not per-click consent.

• docs/README.md — docs map, including current references, plans, and research
• docs/architecture/runtime-architecture.md — current process/protocol map
• docs/status/implementation-status.md — milestone ladder + historical implementation log
• docs/security/sandbox-escape-benchmark-2026.md — Atelier's guest cage cross-checked against SANDBOXESCAPEBENCH (arXiv:2603.02277)
• CLAUDE.md — build/run/test commands, conventions, repo layout

Renderer (React, sandboxed)
 │ Electron IPC
Main process (Node) — Session Manager (per-session lifecycle, hibernate/resume)
 │ Named pipe / unix socket — JSON-RPC 2.0
Go host service — broker (policy + audit) + VZ driver (macOS) / HCS driver (Windows)
 │ hvsocket — control / exec / files / net
Linux utility VM — one cage, N sessions: each /sessions/<id> mount + its own agent loop
 · tools act on the guest fs; only the model call exits via the egress allowlist

npm run build:all # clean build + verify -> build/debug/
npm run build:all -- --config=release # stripped + self-contained -> build/release/

scripts/build-all.mjs (zero-dep Node) is the single source of truth for the build. It detects your OS and runs the whole chain from zero — git submodule → protocol codegen → host broker (codesigned on macOS) → VM image → packaged desktop → verify — writing every artifact into one tree, build/<config>/:

build/<config>/
 atelierd(.exe), atelierctl(.exe) # Go broker + dev CLI (broker codesigned on macOS)
 image/<target>/ # vmlinuz, initrd, rootfs.raw|vhd, *.origin, manifest.txt
 desktop/ # packaged Electron app

By default this skips the heavy rootfs/kernel/initrd image (it changes rarely) and only rebuilds the small runner volume next to a reused image — pass --image to build the whole bundle. Other flags: --deep (also wipe node_modules + image cache for a true from-zero), --no-verify, and --only=host|image|desktop to build a single phase (--only=image always builds the full image). Then run as below.

The same orchestrator drives each component — no per-OS build scripts:

node scripts/build-all.mjs --only=host # protocol + broker/atelierctl (codesigned on macOS)
node scripts/build-all.mjs --only=image # VM image bundle (Docker; via WSL on Windows)
node scripts/build-all.mjs --only=desktop # packaged desktop app

(image/build.sh still runs standalone for image-only hacking; by default it writes to image/bundle/<target>/. The orchestrator redirects it into build/<config>/image/ via ATELIER_OUT_BASE.)

# macOS (Apple Silicon) — broker needs no root (codesigned with the VZ entitlement)
build/debug/atelierd # broker -> /tmp/atelierd.sock
ATELIER_BUNDLE_DIR=build/debug/image/darwin-arm64-vz npm run dev # desktop (ANTHROPIC_API_KEY set)
# Windows — broker must run elevated
build\debug\atelierd.exe
$env:ATELIER_BUNDLE_DIR="build\debug\image\windows-amd64-hyperv"; npm run dev

In the app: Work → New work → pick a folder. The app boots vm0, mounts the folder, opens egress to the model API, and launches the in-guest agent. Tasks stream in; deliverables land in your folder. Idle sessions hibernate and resume on selection.

B=build/debug/image/darwin-arm64-vz # the bundle dir (use atelierctl from build/debug/)
atelierctl createVM -id vm0 -kernel $B/vmlinuz -initrd $B/initrd -rootfs $B/rootfs.raw
atelierctl startVM -id vm0
atelierctl attachWorkspace -id vm0 -path /path/to/folder
atelierctl setEgressPolicy -allow <model-api-host>
atelierctl agent -id vm0 -- "read orders.csv, write summary.csv"
atelierctl stopVM -id vm0

The guest has no inbound network path (vsock-only, egress default-deny, no sshd by design). For an interactive root shell into the VM to debug the guest OS itself, a debug build adds a second virtio console (/dev/hvc1) with a root shell on it; attach over its unix socket. No env var — the socket appears at boot.

atelierd -addr /tmp/atelierd.sock & # then createVM/startVM as above
atelierctl console -id vm0 # interactive shell; Ctrl-] detaches

This shell runs as root, outside the agent's bwrap/seccomp cage, so it is gated at build time: the host code is behind the debugconsole Go build tag and the init.sh block is stripped from the release rootfs — a --config=release build contains neither, so it can never ship in production (Windows/HCS analog TBD).

npm run e2e:host # build (debug) if needed, boot a VM, drive every broker door
npm run e2e:host -- --config=release # against build/release/
npm run e2e:host -- --skip-build # reuse build/<config>/ as-is

scripts/e2e-host.mjs spawns the real broker, boots vm0, and exercises all 12 protocol doors plus the in-guest agent loop through atelierctl — both share models (legacy /workspace + Files door and concurrent /sessions/<tag>), the egress jail, and host↔guest file bridging both ways. It needs the same prerequisites as a real run (VZ + codesigned broker + image bundle); the agent check also needs ANTHROPIC_API_KEY and live egress to the model API.