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

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 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

claude-desktop --doctor

AppImage Distribution

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

RPM Package Installation

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:

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 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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}