Docker Persistence Model in Desktop Commander MCP: How Named Volumes Isolate Workspaces

Desktop Commander MCP uses four named Docker volumes—dc-system, dc-home, dc-workspace, and dc-packages—to persist user data, configuration, and dependencies across container runs while keeping each workspace isolated.

Desktop Commander MCP executes commands inside ephemeral Docker containers, yet preserves your work between sessions through a robust Docker persistence model. According to the wonderwhy-er/DesktopCommanderMCP source code, the system mounts named volumes that survive container destruction, ensuring your installed packages, system configuration, and project files remain intact even as individual containers are created and destroyed.

The Four Named Volumes That Power Persistence

The installer scripts (install-docker.sh and install-docker.ps1) create four essential named volumes, each serving a distinct isolation purpose within the Desktop Commander MCP architecture.

dc-system: Global System Files

The dc-system volume stores OS-level tools and system-wide configuration files. Mounted at /usr/src/app/system inside the container, this volume persists global utilities and system state using the {{desktop-commander.paths|volume|into}} template reference found in server.yaml.

dc-home: User Home Directory

The dc-home volume mirrors the user's home directory, providing the container access to $HOME contents. Mounted at /home/desktop-commander, this volume preserves shell configuration, SSH keys, and user-specific settings across container restarts.

dc-workspace: Project Isolation

The dc-workspace volume holds current project files and any workspaces users create. Mounted at /workspace, this volume enables different workspaces to mount different host directories while sharing the same underlying system volumes for consistency.

dc-packages: Dependency Caching

The dc-packages volume caches node_modules and other dependency folders at /usr/src/app/node_modules. By preserving installed packages across runs, this volume eliminates redundant npm installations and accelerates container startup times.

How the Docker Persistence Model Works

The implementation follows a four-stage lifecycle defined in install-docker.sh, ensuring data integrity while maintaining container freshness.

Volume Creation

At lines 214-229 in install-docker.sh, the installer checks each volume name and creates missing ones using docker volume create <name>. This provisioning step ensures the four essential volumes exist before any container launches, preventing data loss on first run.

Container Launch with Volume Mounts

Every docker run command attaches persistent volumes via -v flags, as implemented at lines 244-247 in install-docker.sh. The runtime mounts all four volumes to their designated paths inside every fresh container, creating the persistence layer.

Data Isolation Strategy

Because volumes are named and attached at fixed mount points, data written inside the container persists after the container exits. Different workspaces mount distinct host directories into dc-workspace while sharing dc-system and dc-packages, creating an efficient isolation layer that separates project code from shared infrastructure.

Safety and Lifecycle Independence

Volumes remain untouched even when containers are removed with docker rm. The src/utils/system-info.ts file explicitly documents that "Files created outside mounted volumes will be lost," reinforcing that only these four named volumes guarantee persistence. The scripts provide cleanup helpers (docker volume rm dc-*) for full environment resets when necessary.

Implementation Examples

Automated Installation

The bash installer automatically creates required volumes during setup:

curl -sSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/main/install-docker.sh | bash

Manual Container Execution

To run commands with explicit volume persistence:

docker run -it \
  -v dc-system:/usr/src/app/system \
  -v dc-home:/home/desktop-commander \
  -v dc-workspace:/workspace \
  -v dc-packages:/usr/src/app/node_modules \
  mcp/desktop-commander:latest <your-command>

Windows PowerShell Setup

The PowerShell installer (install-docker.ps1) implements identical volume logic for Windows environments, creating the same four named volumes through Docker Desktop:

.\install-docker.ps1

MCP Runtime Configuration

The server.yaml file uses template syntax to inject volume mounts dynamically:

volumes:
  - '{{desktop-commander.paths|volume|into}}'

Summary

• Four named volumes (dc-system, dc-home, dc-workspace, dc-packages) provide the backbone of the Desktop Commander MCP persistence model
• install-docker.sh (lines 214-229) handles automated volume creation during setup, while lines 244-247 manage the mount logic
• Container runs mount these volumes at fixed paths to ensure data survives container destruction while maintaining ephemeral compute environments
• Workspace isolation allows different projects to share system files and cached packages while keeping code separate through selective host directory mounting
• Safety guarantees ensure volumes persist independently of container lifecycle, with explicit warnings in src/utils/system-info.ts about data loss outside mounted volumes

Frequently Asked Questions

What happens to data written outside the four named volumes?

Data written outside /usr/src/app/system, /home/desktop-commander, /workspace, or /usr/src/app/node_modules is ephemeral and destroyed when the container exits. The src/utils/system-info.ts file explicitly warns that only content within these mounted paths persists across runs, making adherence to these paths critical for data retention.

How do I completely reset my Desktop Commander MCP environment?

Run docker volume rm dc-system dc-home dc-workspace dc-packages to delete all persistent data. The installer scripts provide cleanup helpers for this purpose, allowing you to start fresh while preserving the ability to recreate volumes automatically on next run via the standard installation process.

Can multiple workspaces share the same system packages?

Yes. The dc-packages volume caches node_modules and dependencies at /usr/src/app/node_modules, while dc-system stores global tools. Multiple workspace containers can mount these same named volumes simultaneously, sharing cached dependencies while keeping project files isolated in their respective dc-workspace mounts.

Why does Desktop Commander MCP use named volumes instead of bind mounts?

Named volumes provide better abstraction and lifecycle management than bind mounts. They allow the system to initialize empty volumes automatically on first run via docker volume create, remain independent of specific host directory structures, and survive container removal intact, as implemented in the install-docker.sh volume creation logic at lines 214-229.

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