# How the Docker Installation Option in DesktopCommanderMCP Achieves Filesystem Isolation

> Learn how DesktopCommanderMCP uses Docker to isolate filesystems by preventing host volume mounts and restricting LLM access through system prompts for enhanced security.

- Repository: [Eduard Ruzga/DesktopCommanderMCP](https://github.com/wonderwhy-er/DesktopCommanderMCP)
- Tags: internals
- Published: 2026-08-08

---

**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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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:

```typescript
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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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:

```typescript
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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/dockerPrompt.ts) (lines 31-59), this function intercepts tool outputs and prepends the filesystem restriction warnings:

```typescript
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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/dockerPrompt.ts), and it inspects the filesystem for `/.dockerenv` or Docker cgroup entries in [`src/utils/system-info.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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.