How to Set Up Docker Isolation for Complete Desktop Commander MCP Sandboxing

Desktop Commander MCP supports full Docker sandboxing via four persistent volumes and an automated installer script that configures Claude Desktop to run the MCP server inside isolated containers.

The wonderwhy-er/DesktopCommanderMCP repository provides a complete Docker-based isolation strategy that runs the entire MCP server inside containers, preventing direct filesystem access to your host machine while maintaining tool persistence across sessions. This approach leverages a custom Dockerfile and the install-docker.sh script to create a sanitized environment where all commands execute in ephemeral containers with dedicated persistent storage.

Understanding the Docker Sandbox Architecture

The sandboxing model uses a layered approach: a lightweight container image provides the runtime, while named volumes preserve user data and installed tooling between container restarts.

The Container Image Build Process

According to the repository's Dockerfile, the image construction follows a security-hardened pipeline:

1. Base image: Uses node:lts-alpine for minimal attack surface
2. Dependency installation: Runs npm install --ignore-scripts to prevent arbitrary code execution during package installation
3. Native binary rebuild: Rebuilds the @vscode/ripgrep binary required for fast recursive searches
4. Build process: Copies source and executes npm run build
5. Entry point: Sets the container command to node dist/index.js

This configuration ensures the MCP server starts fresh with exactly the dependencies defined in package.json, without relying on host-installed Node.js versions.

Persistent Volume Strategy

The install-docker.sh script establishes four named Docker volumes that survive container destruction. These volumes separate system files from user data while maintaining state between ephemeral container runs:

Volume	Mount Point	Purpose
dc-system	/usr	System packages, binaries, and libraries
dc-home	/root	User configurations, dotfiles, SSH keys, and Git settings
dc-workspace	/workspace	Development projects and source code
dc-packages	/var	Package caches (npm, pip, etc.)

Because containers launch with the --rm flag, each command executes in a fresh container instance. The named volumes attach to every instance, ensuring installed tools and configurations persist while the runtime environment remains clean.

Installing the Docker Sandbox

Prerequisites

Before installation, verify that Docker Desktop is running and the daemon is accessible from your terminal. The installer requires Docker Engine version 20.10 or later to support the volume mounting syntax used in the configuration.

Running the Automated Installer

Execute the installer directly from the repository to bootstrap the entire sandbox:

bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh)

The script performs the following operations automatically:

1. Validates Docker availability and daemon connectivity
2. Pulls the latest image (mcp/desktop-commander:latest)
3. Creates the four persistent volumes if they do not exist
4. Prompts for host folder paths to mount inside the container
5. Generates the Claude Desktop configuration JSON
6. Executes a persistence verification test

Volume Persistence Model

The combination of --rm containers with named volumes creates a "fresh container, persistent data" architecture. When Claude Desktop launches the MCP server, Docker creates a new container from the image, attaches the existing volumes, and removes the container immediately after the session ends. Your installed packages in /usr, Git configuration in /root, and project files in /workspace remain intact because they reside on Docker-managed volume storage rather than in the container's ephemeral filesystem.

Configuring Claude Desktop for Docker Isolation

After installation, the install-docker.sh script modifies your Claude Desktop configuration file to launch the MCP server via Docker rather than directly executing Node.js. The generated configuration in your claude_desktop_config.json follows this structure:

{
  "mcpServers": {
    "desktop-commander": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "dc-system:/usr",
        "-v", "dc-home:/root",
        "-v", "dc-workspace:/workspace",
        "-v", "dc-packages:/var",
        "-v", "/Users/you/Projects:/home/Projects",
        "mcp/desktop-commander:latest"
      ]
    }
  }
}

The -i flag ensures interactive mode for stdio communication, while --rm guarantees cleanup after each Claude Desktop session.

Folder Mounting Strategy

When the installer prompts for folder paths, it maps host directories into the container's /home directory while preserving the original absolute structure. For example, mounting /Users/alice/Projects creates the path /home/Projects inside the container. This approach prevents the container from accessing your entire home directory while explicitly allowing access to specific project folders.

To manually add additional mounts after installation, edit the args array in your Claude Desktop configuration to include:

"-v", "/path/on/host:/home/directory-name"

Place these entries before the image name in the arguments list.

Managing the Sandbox Lifecycle

Checking Sandbox Status

Verify that volumes exist and are properly attached by running the installer with the --status flag:

bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh) --status

This outputs the status of all four volumes (dc-system, dc-home, dc-workspace, dc-packages) and confirms the container uses the --rm flag for ephemeral execution.

Resetting to Clean State

To destroy all persistent data and restore a pristine sandbox environment:

bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh) --reset

This command removes the named volumes but preserves any host-folder mounts defined in your configuration. Use this when package installations corrupt the environment or when switching between unrelated projects that require conflicting global dependencies.

Manual Docker Commands

For debugging or testing without Claude Desktop, invoke the container directly:

docker run -i --rm \
  -v dc-system:/usr \
  -v dc-home:/root \
  -v dc-workspace:/workspace \
  -v dc-packages:/var \
  mcp/desktop-commander:latest node -e "console.log('Sandbox operational')"

This executes a one-off command inside the isolated environment with full access to persisted tools and configurations.

Summary

• Docker isolation for Desktop Commander MCP uses a node:lts-alpine base image built via the repository's Dockerfile, which installs dependencies with --ignore-scripts for security
• Four persistent volumes (dc-system, dc-home, dc-workspace, dc-packages) preserve state across ephemeral containers launched with --rm
• Automated setup via install-docker.sh handles volume creation, folder mounting, and Claude Desktop configuration generation
• Host folder access is granted through explicit volume mounts under /home inside the container, preventing unrestricted filesystem access
• Lifecycle management uses --status to verify setup and --reset to destroy persistent data while maintaining the container image

Frequently Asked Questions

What are the four persistent volumes used for?

The dc-system volume stores installed binaries and libraries in /usr, dc-home maintains user configurations and SSH keys in /root, dc-workspace holds your development projects in /workspace, and dc-packages caches package managers' download directories in /var. This separation prevents data loss when containers are destroyed after each command execution.

How does folder mounting work with Docker isolation?

The install-docker.sh script maps host directories you specify to paths under /home inside the container while preserving the directory structure. For example, /Users/alice/Documents becomes /home/Documents in the container. This mapping is added to the Docker args array in your Claude Desktop configuration, allowing the MCP server to read and write specific host folders without accessing the entire filesystem.

Can I run Desktop Commander MCP without persistent volumes?

Yes, but every container restart would lose all installed tools, configurations, and cached data. The volumes defined in install-docker.sh are essential for maintaining a usable development environment across Claude Desktop sessions. Without them, you would need to reinstall system packages and reconfigure Git settings every time the MCP server starts.

How do I troubleshoot Docker sandbox connectivity issues?

First, verify volume status using the --status flag on the installer script. Check that Docker Desktop is running and that the mcp/desktop-commander:latest image exists via docker images. If Claude Desktop fails to start the MCP server, examine the args array in your configuration for syntax errors in volume mounting paths. Ensure that host paths in -v arguments exist before Claude attempts to start the container.

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