Windows and macOS sessions: QEMU VMs the agent runs inside

A Windows session

A session's Environment (the first dropdown under the prompt of the New session form, also in Advanced… → Sandbox) is Docker · Linux by default: the box described everywhere in this guide. QEMU · Windows puts the agent on Windows instead: a Windows virtual machine, sbx-win-<session id>, runs under QEMU with KVM in a second container next to a Linux box, the agent itself runs inside the VM, and the box's desktop shows that VM full-screen over RDP. Everything that looks at the desktop looks at Windows: the Desktop pane, Take control, the agent's screenshots, clicks, typing and drags, the recordings, verification videos. The header and the sidebar mark such sessions with a Windows badge. QEMU · macOS does the same with a Mac, over VNC; see A macOS session.

The agent lives in Windows: Claude Code, Codex, Cursor or Devin runs inside the VM as its user agent (an administrator), started over SSH by the Linux box, with C:\workspace as its Workspace; the repositories are cloned there (C:\workspace\<name>), with the session's Git accounts answering git inside the VM; the MCP servers you enabled for the session start in Windows too, so what they see — paths, environment variables, processes, localhost — is Windows; and the Terminal pane is a PowerShell in the VM, in C:\workspace. The Linux box stays as the plumbing: it shows the desktop over RDP and takes the agent's screenshots, clicks and typing on it, records the desktop, holds the connection to Sessionboxer and keeps a mirror of the Workspace that Pull to folder, the files linked in the chat and uploads go through (the mirror refreshes from the VM whenever it is read). The Windows base disk has Node.js, Git, uv/uvx and the four agents installed; gh is not there, plain git push/pull work. Provider logins reach the VM only for the seconds an agent start takes, on the session's own disk; the guest password (generated at install time, kept in config.json) is used by the box to reach the VM, never shown to the agent. The Code pane says VS Code is not available for Windows sessions yet: edit through the agent, the Terminal or the desktop.

Before the first Windows session, install the base disk once: Global settings → Environment → Windows VMs → Install. Pick the edition (Windows 11 Pro by default; 11 LTSC and Enterprise, 10 Pro and LTSC, Server 2022 and 2025 are the others), the RAM and CPUs each VM gets (4 GB and 2 by default, on top of the box's) and the disk size (64 GB, sparse: it only takes what Windows writes, ~10 GB after install). Sessionboxer then runs an unattended installation in a container based on dockur/windows: it downloads Microsoft's installation media for that edition (about 6 GB), installs it, creates the agent account, and runs a setup script of its own (screen never blanks or locks, no automatic update reboots, OpenSSH Server, Node.js 22, Git, uv, Claude Code, Codex, Cursor and the Devin CLI with their ACP adapters, C:\workspace, file extensions and hidden files shown), then shuts the VM down. Thirty to fifty minutes, longer on a slow connection; the status and the installer's log are on that settings page, Cancel aborts and cleans up, and a failure shows the log's tail. The result is a sbx-windows-base Docker volume. Every Windows session then boots its own copy-on-write overlay of that disk in seconds — a session's disk costs what it writes; Delete on the settings page removes the base once no Windows session (running or stopped) uses it, and Install again replaces it (same rule). Windows runs unactivated (a watermark, some personalisation locked) until you activate it with your own licence inside the guest; Sessionboxer ships no licence and the media are Microsoft's public downloads, under their terms.

Where it works: a Linux host with KVM — bare metal, a VM with nested virtualisation, or WSL2 with KVM enabled — running Docker Engine, with your user able to use /dev/kvm (ls -l /dev/kvm; the kvm group). Docker Desktop on macOS cannot (its VM has no KVM); on Windows only with nested virtualisation exposed to WSL2. docker compose mode works when the host has /dev/kvm, since the VM containers are siblings of the Control Plane's. The option says why it is unavailable when it is.

What Windows sessions cannot do yet: snapshots, forks and rebuilds (the VM's disk is outside the box's image; the controls say so), Docker inside the Sandbox, VS Code (the Code pane says so) and gh in the VM. A base disk installed before the agent moved into the VM (Sessionboxer 1.3) lacks the tools: Delete it and Install again. Stop shuts Windows down cleanly (a couple of minutes at most) and Resume boots it again, the desktop reconnecting by itself; Delete removes the VM and its disk with the session.

A macOS session

QEMU · macOS works like a Windows session with a Mac in the VM: a macOS virtual machine, sbx-mac-<session id>, runs under QEMU with KVM, booted by OpenCore in a container based on dockur/macos, next to a Linux box whose desktop shows the VM's screen full-screen over VNC (QEMU's own, so it is there from the first frame). The agent runs inside the Mac, as on Windows: Claude Code, Codex, Cursor or Devin is started over SSH in the VM as the user agent, its stdio MCP servers run there (localhost is the Mac's), repositories are cloned into /Users/agent/workspace/<name> with the Mac's git (your connected GitHub/Bitbucket account answers its credential requests from the box, nothing is stored in the VM), the Terminal pane is a zsh login shell in the VM, and file paths in the chat are /Users/agent/workspace/… (click them like /workspace/… ones). The Desktop pane, Take control, the agent's screenshots, clicks, typing and drags, the recordings and the verification videos all look at the Mac; the Linux box keeps those, the LLM inspector, sync (Pull the box's changes) and the raw-file downloads, reading a mirror of the Mac's Workspace it refreshes on demand. Sessions carry an Apple badge in the header and the sidebar. The guest account is agent, logged in automatically, with the password Sessionboxer generated at install time (Sessions log in with an SSH key installed at provisioning). Keyboard shortcuts are the Mac's: the Super/Windows key of the box's keyboard is ⌘. mac <command> and mac-scp still exist inside the Linux box (docker exec -it sbx-<session id> bash) but are no longer needed.

Before the first macOS session, install the base disk once — and this one needs you at the screen for a while: Apple ships no unattended installer, so Global settings → Environment → macOS VMs → Install boots Apple's own Recovery in a VM and shows its screen right there on the settings page, with the steps next to it. Pick the release first (macOS 15 Sequoia by default; 14 Sonoma, 13 Ventura, 12 Monterey and 11 Big Sur are the others), the RAM and CPUs each VM gets (4 GB and 2 by default, on top of the box's) and the disk size (64 GB, sparse). Sessionboxer downloads the Recovery image for that release from Apple (about 700 MB), builds an OpenCore boot disk with a machine identity and boots the VM; then, in the screen: erase the VirtIO disk in Disk Utility as Macintosh HD (APFS), run Reinstall macOS (the installer downloads the release from Apple, about 13 GB, and restarts the VM a few times — up to an hour), and in Setup Assistant skip Migration and the Apple Account, create the account agent with the password shown on the page, and turn Remote Login on in System Settings → General → Sharing. From there Sessionboxer takes over: as soon as the VM answers on SSH it turns off sleep and the screen saver, sets auto-login, installs the agent's toolchain — Node 22, git through Apple's Command Line Tools (softwareupdate, the slow part), uv, Claude Code, the Claude and Codex ACP adapters, the Devin and Cursor CLIs, all pinned to the same versions as the Windows base — and its SSH key, all with progress in the log on the page (10–30 minutes), then shuts the VM down, and the base is ready. A base installed before the tools were part of it says so on the page: Reprovision boots it once more, unattended, and runs only that step (no Recovery, no Setup Assistant; delete the macOS sessions first, their disks build on the base). Reprovision also brings a base up to date when the tool versions change. The status, the log and the screen stay on that page; Cancel stops the VM, and if it powers off before the end (the installer's own restarts do not count) the install ends the same way: the state is an error that keeps the disk as it is, Install again continues with it (Recovery boots the half-installed disk) and Delete removes it. The result is a sbx-macos-base Docker volume (about 20 GB used). Every macOS session boots its own copy-on-write overlay of that disk in seconds, with the same machine identity; Delete on the settings page removes the base once no macOS session (running or stopped) uses it, and Install again replaces it (same rule).

Where it works: a Linux host with KVM and a CPU with AVX2 (macOS 11 and later need it), running Docker Engine, as for Windows: bare metal, a VM with nested virtualisation, or WSL2 with KVM enabled; not Docker Desktop on macOS. The option says why it is unavailable when it is. A VM takes its RAM on top of the box's, plus about 1.5 GB for QEMU.

About the licence. Apple's macOS software licence allows running macOS in a virtual machine on Apple-branded hardware only. dockur/macos, and therefore this environment, runs it on any Linux/KVM host; Sessionboxer ships no macOS bits and downloads nothing of Apple's itself (Recovery and the installer come from Apple's servers through dockur, as they would on a Mac), but using QEMU · macOS on non-Apple hardware is your decision under Apple's terms.

What macOS sessions cannot do yet: the same as Windows ones — VS Code (edit through the agent, the Terminal or the desktop), snapshots, forks and rebuilds, Docker inside the Sandbox, a shared folder — plus clipboard between the box and the guest (QEMU's VNC carries screen and input only). Homebrew is not in the VM; the agent installs what it needs with npm, uv or official installers. Stop shuts the Mac down cleanly and Resume boots it again to the desktop, the view reconnecting by itself; Delete removes the VM and its disk with the session.