How Docker Installation Provides Filesystem Isolation and Persistence in Desktop Commander MCP

Desktop Commander MCP uses Docker containers to isolate the application runtime from the host OS while mounting named volumes that persist data across container restarts.

Desktop Commander MCP leverages Docker installation to provide filesystem isolation and persistence, creating a secure sandbox environment that separates process execution from the host system while maintaining state through Docker volumes. This architecture ensures that your development environment remains clean and reproducible, with critical data surviving container teardowns.

Container-Based Process Isolation

The foundation of Desktop Commander's security model is running the entire MCP (Mini-Control-Plane) inside a Docker container. In Dockerfile, the build starts from a minimal Node.js LTS Alpine image and copies only the application source, ensuring no host files leak into the container filesystem.

# /Dockerfile

FROM node:lts-alpine
ENV MCP_CLIENT_DOCKER=true
WORKDIR /usr/src/app
COPY package*.json ./
RUN npm install --ignore-scripts
RUN npm rebuild @vscode/ripgrep
COPY . .
RUN npm run build
CMD [ "node", "dist/index.js" ]

This configuration guarantees that processes, network namespaces, and the filesystem remain separate from the host OS. When the container runs with the --rm flag, the execution environment is destroyed after each command, ensuring a fresh state for every operation while the underlying data persists elsewhere.

Persistent Volume Architecture

Desktop Commander implements four essential persistent volumes that survive container teardown. In install-docker.sh (lines 18-31), the installer creates these named volumes if they do not exist:

• dc-system → mounted to /usr
• dc-home → mounted to /root
• dc-workspace → mounted to /workspace
• dc-packages → mounted to /var

The build_docker_args() function (lines 36-65) assembles the Docker run command with these volume bindings:

#!/usr/bin/env bash

# /install-docker.sh (excerpt)

ESSENTIAL_VOLUMES=(
  "dc-system:/usr"
  "dc-home:/root"
  "dc-workspace:/workspace"
  "dc-packages:/var"
)

# Create volumes if missing

for volume in "${ESSENTIAL_VOLUMES[@]}"; do
  name=$(echo "$volume" | cut -d':' -f1)
  docker volume inspect "$name" >/dev/null 2>&1 || docker volume create "$name"
done

# Build run arguments

DOCKER_ARGS=("run" "-i" "--rm")
for volume in "${ESSENTIAL_VOLUMES[@]}"; do
  DOCKER_ARGS+=("-v" "$volume")
done

This design ensures that installed npm packages, user SSH keys, configuration files, and project data stored under /workspace persist between container restarts, even though the container itself is ephemeral.

Optional Host Directory Binding

While isolation is maintained for system directories, Desktop Commander allows optional host folder mounting for live development workflows. During installation, install-docker.sh prompts users to select host directories (defaulting to $HOME) and binds them to container paths:

# /install-docker.sh (excerpt)

FOLDERS=("$HOME")
for folder in "${FOLDERS[@]}"; do
  DOCKER_ARGS+=("-v" "$folder:/home$(basename "$folder")")
done

This enables editing source files on the host while executing commands inside the isolated container, bridging the gap between security and developer ergonomics.

Detecting Docker Gateway Limitations

Desktop Commander distinguishes between the full Docker installation and the minimal "Docker MCP Gateway" (which lacks persistent volumes). In src/utils/dockerPrompt.ts (lines 12-20), the shouldPromptForDockerInfo() function detects when running through the gateway:

// /src/utils/dockerPrompt.ts
export async function shouldPromptForDockerInfo(): Promise<boolean> {
  const currentClient = await configManager.getValue('currentClient');
  if (currentClient?.name !== 'docker') return false;
  const stats = await usageTracker.getStats();
  return stats.totalToolCalls === 0 || stats.totalToolCalls === 1;
}

When detected, the system injects a message (lines 25-30) warning that "No folder mounting support – your files won't persist between restarts" and directs users to the full installer script for proper filesystem isolation and persistence.

Persistence Verification

The installation script includes a test_persistence() function that validates volume functionality by writing test files to /workspace and /root, then verifying they survive container exit. This ensures that the Docker installation provides filesystem isolation and persistence correctly before the user begins operations.

Summary

• Container isolation runs the application in a clean Node.js environment defined in Dockerfile, separate from host processes.
• Four named volumes (dc-system, dc-home, dc-workspace, dc-packages) mount to /usr, /root, /workspace, and /var to retain data across container restarts.
• Optional host binds allow live editing of host files while maintaining system isolation.
• Gateway detection in dockerPrompt.ts identifies limited Docker environments and warns users about lack of persistence.
• Verification tests confirm volumes function correctly before use.

Frequently Asked Questions

What happens to my files when the Desktop Commander container stops?

Your files persist because Desktop Commander stores data in Docker named volumes rather than the container's writable layer. When the container stops or is removed with --rm, the volumes (dc-workspace, dc-home, etc.) remain on the host Docker daemon. The next container start mounts these same volumes, restoring access to installed packages, SSH keys, and project files stored in /workspace or /root.

Can I access my host project files from inside the Desktop Commander container?

Yes, through optional host directory mounting. During Docker installation via install-docker.sh, the script prompts you to select host folders (defaulting to $HOME). These directories bind-mount into the container, allowing you to edit files on your host machine while executing commands in the isolated environment. This maintains filesystem isolation for system directories while enabling access to your development projects.

What is the difference between the Docker MCP Gateway and the full Docker installation?

The Docker MCP Gateway is a minimal container environment that lacks persistent volume mounts and folder binding support. According to src/utils/dockerPrompt.ts, Desktop Commander detects gateway usage by checking configManager.getValue('currentClient') for the Docker client type. When detected, it displays a warning that files won't persist between restarts. The full Docker installation, configured via install-docker.sh, creates the four essential volumes and supports optional host mounts, providing full filesystem isolation and persistence.

How does Desktop Commander verify that persistence is working?

The install-docker.sh script includes a test_persistence() function that runs a temporary container to write test files to /workspace and /root. After the container exits, the script verifies these files exist in the named volumes. This confirms that the Docker installation provides filesystem isolation and persistence correctly before completing the setup process.

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