# Claude Desktop `--doctor` Diagnostic Command: Usage, Checks, and Implementation

> Use claude-desktop --doctor to run a diagnostic check ensuring package integrity, sandbox permissions, and display server config before launching the UI. Fix issues fast.

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

---

**Run `claude-desktop --doctor` to execute a comprehensive health check that verifies package integrity, sandbox permissions, display server configuration, andCowork isolation backends before launching the Electron UI.**

The `--doctor` diagnostic command is a built-in troubleshooting tool in the unofficial Claude Desktop Linux port maintained by `aaddrick/claude-desktop-debian`. This flag triggers a series of pure Bash health checks defined in [`scripts/launcher-common.sh`](https://github.com/aaddrick/claude-desktop-debian/blob/main/scripts/launcher-common.sh) that validate the host environment without actually starting the Electron application, making it safe to run from any terminal when debugging startup failures.

## How to Run the Diagnostic

You can invoke the diagnostic from any installed package format. The launcher wrappers detect the `--doctor` flag early and route execution to the `run_doctor` function before any packaging-specific logic runs.

### Debian Package Installation

```bash
claude-desktop --doctor

```

### AppImage Distribution

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

```

### RPM Package Installation

```bash
claude-desktop --doctor

```

### Scripting the Exit Status

The command returns **0** when all checks pass, or a non-zero integer representing the count of failed checks. Use this in automation scripts:

```bash
if claude-desktop --doctor; then
    echo "System ready for Claude Desktop"
else
    echo "One or more diagnostic checks failed"
fi

```

## Core System Checks

The `run_doctor` function in [`scripts/launcher-common.sh`](https://github.com/aaddrick/claude-desktop-debian/blob/main/scripts/launcher-common.sh) organizes validation into three logical sections. The first section verifies the base installation and runtime environment.

### Package and Binary Verification

- **Installed package version** – Queries the Debian package database using `dpkg-query` to report the installed version of `claude-desktop`.
- **Electron binary integrity** – Confirms the bundled Electron binary exists and reads its version file from the installation directory.
- **Chrome sandbox permissions** – Validates that the `chrome-sandbox` binary exists with mode `4755` (setuid) and is owned by `root`, which is required for secure renderer process isolation.

### Display and Session Checks

- **Display server detection** – Distinguishes between Wayland and X11 sessions, reporting the current mode and whether `CLAUDE_USE_WAYLAND` forces native Wayland mode.
- **SingletonLock validation** – Detects stale lock files in `~/.config/Claude/` left by previous crashes that would prevent a new instance from starting.

### Configuration and Dependencies

- **MCP (Model Context Protocol) config** – Validates JSON syntax in the MCP configuration file and reports the number of configured servers.
- **Node.js runtime** – Checks for a system Node.js installation, preferring version 20 or newer for optimal MCP server compatibility.
- **Desktop integration** – Confirms the presence of `/usr/share/applications/claude-desktop.desktop` for proper menu integration.
- **Resource monitoring** – Reports free disk space on the configuration partition and warns if the launcher log file at `~/.cache/claude-desktop-debian/launcher.log` exceeds 10 MiB.

## Cowork Mode and Isolation Checks

The second section of `run_doctor` validates the **Cowork** isolation backends that sandbox Claude's AI processes from the host system.

### Backend Detection

The diagnostic first determines the Linux distribution by reading `/etc/os-release`, then identifies which isolation backend will be used based on available system resources and the `COWORK_VM_BACKEND` environment variable.

### Bubblewrap Verification

When bubblewrap is the selected backend:

- **Binary presence** – Confirms `bwrap` exists in the system PATH.
- **Sandbox probe** – Attempts to run `bwrap --ro-bind / / true` to verify functional user namespaces.
- **AppArmor detection** – If the probe fails on Ubuntu 24.04 or newer, the diagnostic hints at AppArmor user-namespace restrictions that commonly block bubblewrap.

### KVM Virtualization Checks

When KVM is the selected backend:

- **Device permissions** – Validates access to `/dev/kvm`.
- **Required tools** – Checks for `qemu-system-x86_64`, `socat`, and `virtiofsd` in the system PATH.
- **Kernel modules** – Verifies the presence of `/dev/vhost-vsock` for vsock communication between host and VM.
- **VM image status** – Reports the size of the downloaded root filesystem image if present.

### Configuration and Process Validation

- **Custom bwrap mounts** – Reads `~/.config/Claude/claude_desktop_linux_config.json` (if present) and displays configured read-only, read-write, and disabled mount points.
- **Orphaned cowork daemon** – Detects stray [`cowork-vm-service.js`](https://github.com/aaddrick/claude-desktop-debian/blob/main/cowork-vm-service.js) processes running without an active UI, which can indicate a previous crash that requires cleanup.

## Interpreting the Diagnostic Output

The `run_doctor` function formats all output using color-coded status indicators. Understanding this output helps identify whether your system is ready to run Claude Desktop.

### Output Format

Each check reports as either:

- **PASS** – Green indicator showing the check succeeded.
- **FAIL** – Red indicator showing a critical failure that may prevent startup.
- **WARN** – Yellow indicator showing a non-critical issue or missing optional component.

### Exit Code Behavior

The function returns the literal count of failed checks as the exit status. An exit code of **0** indicates perfect health, while an exit code of **3** indicates three specific checks failed. This behavior allows scripts to react programmatically to specific failure counts.

### Common Failure Patterns

When troubleshooting startup issues, look for these specific patterns in the `--doctor` output:

- **SingletonLock FAIL** – Indicates a stale lock file from a previous crash. Delete `~/.config/Claude/SingletonLock` to resolve.
- **Chrome sandbox FAIL** – The setuid sandbox lacks proper permissions. Run `sudo chmod 4755 /opt/claude-desktop/chrome-sandbox` to fix.
- **Bubblewrap probe FAIL** – Usually indicates AppArmor restrictions on Ubuntu 24.04+. The diagnostic will suggest checking AppArmor profiles.

## Summary

The Claude Desktop `--doctor` diagnostic command provides a comprehensive, non-destructive health check for Linux installations. Key takeaways include:

- **Invocation** – Run `claude-desktop --doctor` from any terminal to execute all checks without starting the Electron UI.
- **Implementation** – All logic resides in [`scripts/launcher-common.sh`](https://github.com/aaddrick/claude-desktop-debian/blob/main/scripts/launcher-common.sh) within the `run_doctor` function, using pure Bash and standard Linux utilities.
- **Coverage** – Validates package integrity, display server configuration, Chrome sandbox permissions, MCP configuration, Node.js availability, and Cowork isolation backends (bubblewrap or KVM).
- **Diagnostics** – Reports colored PASS/FAIL/WARN status for each check and returns a non-zero exit code equal to the failure count for scripting integration.
- **Troubleshooting** – Identifies common startup blockers including stale SingletonLock files, AppArmor bubblewrap restrictions, and missing KVM virtualization tools.

## Frequently Asked Questions

### What does the `--doctor` flag check in Claude Desktop?

The `--doctor` flag runs a comprehensive diagnostic suite that verifies your Linux system can safely launch Claude Desktop. According to the `aaddrick/claude-desktop-debian` source code, it checks package installation integrity, Chrome sandbox permissions, display server configuration (Wayland vs. X11), Node.js availability for MCP servers, and the selected Cowork isolation backend (bubblewrap or KVM). The diagnostic outputs colored PASS/FAIL indicators for each check without actually launching the Electron application.

### How do I fix a "Chrome sandbox" failure in the diagnostic output?

A Chrome sandbox failure indicates the setuid binary lacks proper permissions for secure renderer process isolation. To resolve this, ensure the `chrome-sandbox` file in your Claude Desktop installation directory (typically `/opt/claude-desktop/`) has mode `4755` and is owned by root. Run `sudo chmod 4755 /opt/claude-desktop/chrome-sandbox` and `sudo chown root:root /opt/claude-desktop/chrome-sandbox`, then rerun `claude-desktop --doctor` to verify the check passes.

### Why does the bubblewrap check fail on Ubuntu 24.04?

The bubblewrap check typically fails on Ubuntu 24.04 and newer due to AppArmor restrictions on user namespaces. While the bubblewrap binary exists, the kernel prevents it from creating the sandbox environment required for Cowork mode. The diagnostic hints at this AppArmor constraint when the `bwrap --ro-bind / / true` probe fails. To resolve this, you must either adjust AppArmor profiles to permit unprivileged user namespaces or switch to the KVM backend by setting `COWORK_VM_BACKEND=kvm` if your system supports virtualization.

### Can I use the `--doctor` output in automation scripts?

Yes, the `--doctor` command is designed for scripting integration. The `run_doctor` function in [`scripts/launcher-common.sh`](https://github.com/aaddrick/claude-desktop-debian/blob/main/scripts/launcher-common.sh) returns an exit code equal to the number of failed checks, where zero indicates all checks passed. You can use standard shell conditional logic to react programmatically to the results. For example, `if claude-desktop --doctor; then echo "Deployment ready"; else echo "Configuration issue detected"; fi` will branch based on the diagnostic outcome without parsing the colored text output.