A quiet workshop for your files.
Ask in plain language. Atelier reads and edits files in your workspace
and runs code inside a contained sandbox — every change gated and audited.
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 researchdocs/architecture/runtime-architecture.md— current process/protocol mapdocs/status/implementation-status.md— milestone ladder + historical implementation logdocs/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
| What | Need |
|---|---|
| Real VM | macOS (Apple Silicon) + VZ — broker must be codesigned; or Windows 11 + HCS (Hyper-V Administrators or elevated) |
| VM image | Docker (OrbStack on macOS; WSL2 on Windows), mke2fs, qemu-img |
| Host broker + guest daemon | Go 1.25+ |
| Desktop app + codegen | Node ≥ 22.12 |
| In-guest agent | Python ≥ 3.12 + uv (partisan/OpenHands) |
| Model calls | ANTHROPIC_API_KEY in the environment that launches the app |
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 devIn 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 vm0The 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-] detachesThis 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-isscripts/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.