How the Docker Installation Option in DesktopCommanderMCP Achieves Filesystem Isolation

DesktopCommanderMCP achieves filesystem isolation by detecting Docker container execution and injecting system prompts that restrict LLM access, while running the container without host volume mounts to prevent directory traversal.

The Docker installation option in DesktopCommanderMCP creates a secure sandbox for AI operations by implementing a multi-layered isolation strategy. This approach ensures that when the application runs as the Docker MCP Gateway client, the underlying large language model (LLM) cannot access, modify, or exfiltrate files from the host machine. The system combines runtime detection, configuration-based gating, and explicit messaging to enforce these boundaries.

Detection of the Docker MCP Gateway Client

The isolation mechanism begins with precise detection of the execution environment. DesktopCommanderMCP distinguishes between standard installations and Docker deployments through client configuration analysis and container runtime inspection.

Client Configuration Verification

In src/utils/dockerPrompt.ts, the shouldPromptForDockerInfo() function determines whether the current session operates inside the Docker MCP Gateway. The function queries the configuration manager to retrieve the active client profile:

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

This check returns true only when currentClient.name equals 'docker', ensuring that isolation logic activates exclusively for Docker deployments. The function also implements first-run gating by examining usage statistics via usageTracker.getStats(), restricting the isolation notice to the first two tool calls to prevent repetitive interruptions.

Container Runtime Detection

Complementary client-side detection resides in src/utils/system-info.ts, where the application inspects the operating environment for Docker indicators. The code checks for the presence of /.dockerenv or Docker-specific cgroup entries:

if (fs.existsSync('/.dockerenv')) {
  return { isContainer: true, containerType: 'docker', orchestrator: null };
}

This verification identifies whether the process runs inside a container and records any existing mount points. When no mount points are detected, the system classifies the environment as a fully isolated container, triggering the restricted filesystem policies.

Enforcing Filesystem Boundaries

Once the Docker environment is confirmed, DesktopCommanderMCP implements active enforcement through LLM prompt engineering and system messaging. This creates a software-defined perimeter that limits the AI's operational scope.

Isolation Message Construction

The getDockerInfoMessage() function in src/utils/dockerPrompt.ts generates a system instruction that explicitly communicates filesystem limitations to the LLM. The message informs the model about three critical constraints: no folder mounting support, limited file-system access, and session data loss upon container termination. This transparency ensures the AI understands its sandboxed context before processing user requests.

Prompt Injection Strategy

The processDockerPrompt() function appends the isolation notice to LLM responses whenever the detection conditions are satisfied. Located in src/utils/dockerPrompt.ts (lines 31-59), this function intercepts tool outputs and prepends the filesystem restriction warnings:

if (await shouldPromptForDockerInfo()) {
  const message = getDockerInfoMessage();
  result = await processDockerPrompt(result, toolName);
}

This injection occurs at the application layer, ensuring that every interaction acknowledges the containerized boundaries without requiring modifications to the underlying AI model.

Default Container Configuration

The physical isolation relies on the Docker image's default launch parameters. The standard DesktopCommanderMCP Docker installation executes without any host volume mounts, creating a completely ephemeral filesystem that exists only for the container's lifecycle. This architectural decision means:

• The container cannot read host directory structures
• File modifications persist only within the container overlay
• No mechanism exists for the LLM to exfiltrate data to mounted host paths

The src/utils/system-info.ts detection logic (lines 88-99) confirms this state by validating the absence of mount points, treating the environment as a truly isolated execution context.

Custom Installation and Volume Escapes

Users requiring persistent host filesystem access must explicitly opt into the custom Docker installation method. The install-docker.sh script provides options for creating mounted volumes that bridge the container and host environments. This deliberate escalation requires user intervention, ensuring that filesystem isolation remains the secure default while accommodating advanced use cases that demand host directory access.

Summary

• Client Detection: The system verifies Docker execution by checking configManager.getValue('currentClient') for the 'docker' name and inspecting /.dockerenv in src/utils/system-info.ts.
• First-Run Gating: Isolation prompts appear only during the initial two tool calls via usageTracker.getStats() to minimize user friction.
• Prompt Injection: The processDockerPrompt() function in src/utils/dockerPrompt.ts appends filesystem restriction notices to all LLM interactions.
• Physical Isolation: Default Docker deployments run without host volume mounts, creating an ephemeral filesystem completely separated from the host machine.
• Explicit Escalation: Full filesystem access requires the custom Docker installation with explicitly defined volume mounts.

Frequently Asked Questions

How does DesktopCommanderMCP detect it is running inside Docker?

The application uses two complementary methods: it checks the currentClient configuration for the name 'docker' in src/utils/dockerPrompt.ts, and it inspects the filesystem for /.dockerenv or Docker cgroup entries in src/utils/system-info.ts. Both conditions must align to trigger the full isolation protocol.

Can the LLM access my host files in the default Docker installation?

No. The default Docker installation option runs the container without any host volume mounts, creating complete filesystem isolation. The LLM can only interact with files inside the container's ephemeral storage, which is destroyed when the container stops.

Why do I only see the isolation warning once or twice?

The shouldPromptForDockerInfo() function implements usage tracking through usageTracker.getStats(), returning true only when totalToolCalls equals 0 or 1. This prevents repetitive warnings while ensuring users understand the sandboxed environment during initial interactions.

How do I enable host filesystem access in Docker?

You must use the custom Docker installation method outlined in install-docker.sh, which allows explicit configuration of host volume mounts. This requires intentional user action to breach the default isolation boundaries, maintaining security for standard deployments.

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