# Override Cowork VM Backend Selection with Environment Variable in Claude Desktop

> Force Claude Desktop's VM backend selection using COWORK_VM_BACKEND environment variable. Choose kvm bwrap or host bypassing auto-detection.

- Repository: [Aaddrick/claude-desktop-debian](https://github.com/aaddrick/claude-desktop-debian)
- Tags: how-to-guide
- Published: 2026-04-19

---

**Set `COWORK_VM_BACKEND` to `kvm`, `bwrap`, or `host` to force Claude Desktop's isolation backend, bypassing auto-detection.**

The `aaddrick/claude-desktop-debian` project implements a Linux "Cowork" isolation layer that automatically selects the best available virtualization backend. Operators can override this auto-detection by setting the `COWORK_VM_BACKEND` environment variable, forcing the application to use a specific isolation strategy regardless of system capabilities.

## How the Backend Override Works

### Backend Options Overview

Claude Desktop supports three distinct isolation backends selectable via environment variable:

| Backend | Isolation Level | Environment Value |
|---------|----------------|-------------------|
| **KVM** | Full QEMU/KVM virtual machine | `kvm` |
| **Bubblewrap** | Namespace sandbox (default) | `bwrap` |
| **Host-direct** | No isolation, runs directly on host | `host` |

When `COWORK_VM_BACKEND` is present in the environment, both the daemon and launcher skip the normal probing sequence and instantiate the specified backend class immediately.

### Detection Logic in the Daemon

In [`scripts/cowork-vm-service.js`](https://github.com/aaddrick/claude-desktop-debian/blob/main/scripts/cowork-vm-service.js), the daemon reads the override at line 47 and routes to the appropriate backend class:

```javascript
const BACKEND_OVERRIDE = process.env.COWORK_VM_BACKEND || null;

function detectBackend(emitEvent) {
    const override = BACKEND_OVERRIDE;
    if (override) {
        log(`Backend override: ${override}`);
        switch (override.toLowerCase()) {
        case 'kvm':   return new KvmBackend(emitEvent);
        case 'bwrap': return new BwrapBackend(emitEvent);
        case 'host':  return new HostBackend(emitEvent);
        default:
            logError(`Unknown backend override "${override}", falling back to auto-detect`);
        }
    }
    /* … auto-detect path … */
}

```

If the supplied value does not match `kvm`, `bwrap`, or `host`, the system logs an error and proceeds to auto-detection rather than failing.

### Launcher Verification

The launcher script [`scripts/launcher-common.sh`](https://github.com/aaddrick/claude-desktop-debian/blob/main/scripts/launcher-common.sh) (lines 12300-12340) mirrors this logic to report the active backend during diagnostic runs:

```bash
if [[ -n ${COWORK_VM_BACKEND-} ]]; then
    case ${COWORK_VM_BACKEND,,} in
        kvm)   cowork_backend='KVM (full VM isolation, via override)' ;;
        bwrap) cowork_backend='bubblewrap (namespace sandbox, via override)' ;;
        host)  cowork_backend='host-direct (no isolation, via override)' ;;
    esac
else
    # …auto-detect fallback logic…

fi
_info "Cowork isolation: $cowork_backend"

```

## Practical Usage Examples

### Force KVM Virtualization

To run Claude Desktop with full VM isolation regardless of default settings:

```bash
export COWORK_VM_BACKEND=kvm
./claude-desktop.AppImage

```

### Use Bubblewrap Sandboxing

Explicitly select the namespace sandbox when KVM is available but undesirable:

```bash
export COWORK_VM_BACKEND=bwrap
./claude-desktop.AppImage

```

### Run Without Isolation

Enable host-direct mode for debugging scenarios where isolation interferes with development:

```bash
export COWORK_VM_BACKEND=host
./claude-desktop.AppImage

```

### Verify Active Backend

Check which backend is actually loaded using the diagnostic flag:

```bash
./claude-desktop.AppImage --doctor

```

Look for the line indicating the override status:

```

Cowork isolation: KVM (full VM isolation, via override)

```

## Implementation Details

The following files in the `aaddrick/claude-desktop-debian` repository implement the backend selection logic:

| File | Purpose |
|------|---------|
| [`scripts/cowork-vm-service.js`](https://github.com/aaddrick/claude-desktop-debian/blob/main/scripts/cowork-vm-service.js) | Daemon backend detection and instantiation |
| [`scripts/launcher-common.sh`](https://github.com/aaddrick/claude-desktop-debian/blob/main/scripts/launcher-common.sh) | Launcher diagnostic reporting and backend identification |
| [`docs/cowork-linux-handover.md`](https://github.com/aaddrick/claude-desktop-debian/blob/main/docs/cowork-linux-handover.md) | High-level architecture documentation |
| [`docs/learnings/cowork-vm-daemon.md`](https://github.com/aaddrick/claude-desktop-debian/blob/main/docs/learnings/cowork-vm-daemon.md) | Detailed daemon implementation notes |

## Summary

- Set `COWORK_VM_BACKEND` to `kvm`, `bwrap`, or `host` to override automatic backend selection in Claude Desktop.
- The daemon in [`scripts/cowork-vm-service.js`](https://github.com/aaddrick/claude-desktop-debian/blob/main/scripts/cowork-vm-service.js) checks this variable at startup and instantiates the matching backend class directly.
- The launcher in [`scripts/launcher-common.sh`](https://github.com/aaddrick/claude-desktop-debian/blob/main/scripts/launcher-common.sh) reports the override status during `--doctor` diagnostic runs.
- Invalid values trigger a logged error and fallback to auto-detection rather than preventing startup.

## Frequently Asked Questions

### What happens if I set `COWORK_VM_BACKEND` to an invalid value?

If you specify a value other than `kvm`, `bwrap`, or `host`, the daemon logs an error message and proceeds with normal auto-detection. The application will not crash; it simply ignores the invalid override and selects the best available backend based on system capabilities.

### Can I mix `COWORK_VM_BACKEND` with other environment variables?

Yes. The backend override operates independently of other configuration variables. For example, you can combine `COWORK_VM_BACKEND=kvm` with resource limit variables or display settings. The backend selection logic only examines the `COWORK_VM_BACKEND` value when deciding which isolation class to instantiate.

### Why does the `--doctor` flag show "via override" next to the backend name?

The launcher script appends "(via override)" to the backend description whenever `COWORK_VM_BACKEND` is present in the environment. This indicator confirms that the current isolation mode results from your explicit environment setting rather than the default auto-detection logic that probes for available virtualization tools.