Make bubblewrap (bwrap) the default cowork isolation backend

[aaddrick]

Summary

Change the default cowork isolation backend from KVM to bubblewrap (bwrap). KVM remains available as an opt-in via COWORK_VM_BACKEND=kvm.

Motivation

Community experience over the past few weeks has consistently favored bwrap over KVM for cowork isolation:

• Simpler dependency chain — bwrap is a single binary available in every major distro's repos. KVM requires QEMU + virtiofsd + vsock kernel modules + hardware virtualization support. Each layer has produced its own category of issues: KvmBackend: guest readiness timeout — VM boots but sdk-daemon never connects via vsock #322 (QEMU 6.2 vsock compat), CoWork KVM: virtiofsd exposes entire $HOME to guest VM — isolate with bind mounts #306 (virtiofsd exposing $HOME), virtiofsd not found even though it is installed #293 (virtiofsd not found), Cowork fails to start the VM due to missing qcow2 files #288 (missing qcow2 files), Title: Cowork VM download fails with EXDEV on Fedora (tmpfs /tmp) #289 (tmpfs EXDEV on Fedora).
• Faster startup — namespace sandbox vs booting a full VM guest is a noticeable UX difference.
• Community signal — Contributors who have tried both prefer bwrap. @cbonnissent tested both and chose bwrap (CoWork KVM: virtiofsd exposes entire $HOME to guest VM — isolate with bind mounts #306 comment). @ecrevisseMiroir built the bwrap sandbox hardening in fix: bwrap backend mounts at guest paths and uses minimal sandbox root #309. @dhonta got KVM working but needed the virtio-9p fallback (feat: add virtio-9p fallback when virtiofsd fails in KVM backend #308).
• bwrap is already hardened — PR fix: bwrap backend mounts at guest paths and uses minimal sandbox root #309 gave it a proper tmpfs-based minimal sandbox root, and fix: echo request id in RPC responses for persistent connections #313 fixed RPC response matching for persistent connections.

Changes Required

1. Flip detection order in detectBackend()

scripts/cowork-vm-service.js:1809 — Currently: KVM → bwrap → host. Change to: bwrap → KVM → host. Swap the two try blocks.

2. Mirror detection order in --doctor

scripts/launcher-common.sh:527-538 — The --doctor backend display mirrors detectBackend(). Flip the if/elif so bwrap is checked first.

3. De-emphasize KVM dependency warnings in --doctor

scripts/launcher-common.sh:495-513 — Currently warns about missing QEMU, socat, virtiofsd, vsock even when bwrap is available and will be used. These become noise for bwrap-default users. Options:

• Only show KVM dep warnings when COWORK_VM_BACKEND=kvm is set
• Group under a "KVM (optional)" section
• Lower severity (info instead of warn)

4. Update README backend table

README.md:13-16 — Swap labels: bwrap becomes "(recommended)", KVM becomes "(opt-in)".

5. Update handover docs

docs/cowork-linux-handover.md — Multiple references to detection order and backend priority need updating.

Related Issues & PRs

• fix: bwrap backend mounts at guest paths and uses minimal sandbox root #309 — bwrap sandbox hardening (merged, foundation for this change)
• fix: echo request id in RPC responses for persistent connections #313 — RPC response ID fix for persistent connections (merged)
• CoWork KVM: virtiofsd exposes entire $HOME to guest VM — isolate with bind mounts #306 — virtiofsd exposes $HOME in KVM mode (open, less urgent if KVM is opt-in)
• KvmBackend: guest readiness timeout — VM boots but sdk-daemon never connects via vsock #322 — KVM vsock timeout on QEMU 6.2 (open, less urgent if KVM is opt-in)
• virtiofsd not found even though it is installed #293 — virtiofsd not found (closed, illustrates KVM dependency pain)
• Cowork fails to start the VM due to missing qcow2 files #288 — missing qcow2 files (closed, illustrates KVM setup complexity)
• fix(doctor): detect virtiofsd outside PATH + document COWORK_VM_BACKEND #324 — documents COWORK_VM_BACKEND env var (open PR, good to land alongside)
• fix: kill orphaned cowork-vm-service daemon on startup #325 — kill orphaned daemon on startup (open PR, complementary)
• fix(doctor): detect virtiofsd installed outside PATH on Debian #287 — detect virtiofsd outside PATH (open PR, lower priority if KVM is opt-in)

Notes

• KVM is not being removed — it stays as a fully functional opt-in backend via COWORK_VM_BACKEND=kvm
• No new code needed for bwrap itself — it's already implemented and hardened
• No changes to build.sh — both backends are already built and packaged
• Total scope: ~4 files, mostly reordering existing logic and updating docs

---

Written by Claude Opus 4.6 via Claude Code

[github-actions]

Good scoping on this. Bwrap is already fully implemented and hardened via #309 and #313, so this is really just a default-flip with a few documentation updates. The dependency story is much friendlier for most users, and the startup time difference is noticeable.

The change touches about four places: reorder detectBackend() so bwrap comes first, update --doctor output to reflect the new default, update the README install instructions, and update any handover docs that reference KVM as the primary path. KVM stays fully supported, just opt-in via COWORK_VM_BACKEND=kvm.

The community feedback in #306, #322, and #293 lines up with this direction. Most users don't have KVM available or don't need it, and landing on a failed KVM check before falling back to bwrap adds confusion during onboarding.

---

This is an automated triage comment. A maintainer will review this issue and may provide further guidance.

Written by Claude Sonnet via Claude Code

[aaddrick]

PR #327 merged this. Bwrap is now the default cowork isolation backend.

#327

---

Written by Claude Opus 4.6 via Claude Code