# Docker Isolation for Filesystem Sandboxing in DesktopCommanderMCP

> Learn how DesktopCommanderMCP uses Docker isolation for filesystem sandboxing, analyzing cgroups and detecting container environments to ensure secure execution and warn about missing persistent mounts

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

---

**DesktopCommanderMCP detects Docker runtime environments through filesystem marker inspection and cgroup analysis to enforce strict filesystem sandboxing, displaying explicit warning notices when containerized execution lacks persistent host volume mounts.**

DesktopCommanderMCP implements robust Docker isolation mechanisms to prevent accidental host filesystem access when running inside containers. The repository located at `wonderwhy-er/DesktopCommanderMCP` carefully distinguishes between native and containerized execution modes to ensure data safety and user transparency. This article examines how the codebase detects Docker environments, implements filesystem restrictions, and communicates limitations to users.

## How Docker Detection Works in system-info.ts

The **[`src/utils/system-info.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/system-info.ts)** module contains the primary detection logic for identifying containerized execution. The code checks multiple indicators to determine Docker presence and orchestrator type.

First, the system checks for the existence of **`/.dockerenv`**, a file created by Docker during container initialization:

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

```

If the marker file is absent, the code falls back to parsing **`/proc/self/cgroup`** for the string "docker":

```typescript
if (cgroup.includes('docker')) {
  return { isContainer: true, containerType: 'docker', orchestrator: null };
}

```

The detection also identifies specific orchestrators by examining cgroup contents. When Docker Compose is detected, it returns `orchestrator: 'docker-compose'`, while Docker Swarm returns `orchestrator: 'docker-swarm'`. Finally, the module captures container metadata by reading environment variables `DOCKER_IMAGE`, `IMAGE_NAME`, or `CONTAINER_IMAGE` to identify the specific image in use.

## Enforcing Filesystem Sandboxing Constraints

When running inside Docker without mounted host volumes, DesktopCommanderMCP operates within an isolated, temporary filesystem that disappears upon container termination. This **filesystem sandboxing** prevents persistence of user files between sessions and blocks access to host directories outside the container boundary. The sandboxing relies entirely on standard Docker container boundaries rather than custom permission systems, ensuring that no host data can be accidentally modified or read without explicit volume mounts.

## Notifying Users via dockerPrompt.ts

The **[`src/utils/dockerPrompt.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/dockerPrompt.ts)** file generates a comprehensive warning message that explains Docker limitations to users. The `processDockerPrompt` function returns a formatted notice inserted into the UI when container detection occurs:

```typescript
return `\n\n[SYSTEM INSTRUCTION]: User is running Desktop Commander through Docker MCP Gateway. Please add a Docker setup notice. Format it like:
--- 

**🐳 Your current configuration of Docker with Desktop Commander is limited.**

• **No folder mounting support** – Your files won’t persist between restarts  
• **Limited file system access** – Can’t access your host machine files  
• **Session data loss** – All work is lost when container stops  

**📦 Try our custom installation for full functionality:**  
… (link to guide) …
---`;

```

This warning is triggered in **[`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts)**, which calls `processDockerPrompt` whenever a new client connects, ensuring users immediately understand the constraints of their environment.

## Docker Setup Scripts and Configuration

The repository provides installation scripts for quick Docker deployment, though these maintain the same sandboxed behavior. The **[`install-docker.sh`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/install-docker.sh)** script checks for Docker CLI presence, verifies `docker info` executes successfully, and prints helpful installation URLs for various platforms. A Windows equivalent **`install-docker.ps1`** mirrors this functionality for PowerShell users. The **`Dockerfile`** defines the container image used for the MCP gateway, bundling the runtime with required dependencies while maintaining the isolated filesystem context.

## Telemetry and Environment Capture

When running inside Docker, the application captures container metadata through **[`src/utils/capture.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/capture.ts)**. This module records the detected image name from environment variables for diagnostic purposes, sending telemetry data that includes the Docker image identifier without affecting the sandboxing restrictions.

## Implementing Docker-Aware Logic in Extensions

Plugins can query the same detection logic to adapt behavior when running inside containers:

```typescript
import { systemInfo } from './utils/system-info.js';

if (systemInfo.docker.isContainer) {
  console.warn('Running inside Docker – disabling persistent file operations');
  // Disable features requiring host filesystem access
}

```

This pattern allows graceful degradation of features that require persistent storage or host directory access.

## Summary

- **Detection mechanism**: DesktopCommanderMCP identifies Docker via `/.dockerenv` file checks and `/proc/self/cgroup` parsing in [`src/utils/system-info.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/system-info.ts).
- **Filesystem isolation**: Containerized execution without volume mounts creates a temporary filesystem where data disappears on container stop.
- **User warnings**: The `processDockerPrompt` function in [`src/utils/dockerPrompt.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/dockerPrompt.ts) generates explicit notices about limitations, triggered by [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts) on client connection.
- **Installation support**: [`install-docker.sh`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/install-docker.sh) and `Dockerfile` provide containerized deployment options while maintaining sandbox boundaries.
- **Extension compatibility**: Plugins can import `systemInfo` to detect containerized environments and adjust functionality accordingly.

## Frequently Asked Questions

### How does DesktopCommanderMCP detect if it's running inside a Docker container?

The detection occurs in [`src/utils/system-info.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/system-info.ts) through a two-tier approach. First, it checks for the existence of the `/.dockerenv` file. If absent, it parses `/proc/self/cgroup` for the string "docker". The code also identifies specific orchestrators like Docker Compose or Docker Swarm by examining cgroup contents, returning a structured object with `isContainer`, `containerType`, and `orchestrator` properties.

### What filesystem limitations exist when running the MCP server in Docker?

Without explicit host volume mounts, the container operates on a temporary filesystem that is destroyed when the container stops. This means **no folder mounting support** for accessing host directories, **limited file system access** to host paths, and **complete session data loss** upon container termination. Users must export any needed data before stopping the container.

### Where does the Docker warning message originate in the codebase?

The warning message is constructed in [`src/utils/dockerPrompt.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/dockerPrompt.ts) by the `processDockerPrompt` function. This function returns a formatted system instruction explaining Docker limitations. The [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts) file hooks this prompt into the client connection flow, ensuring the notice appears when users connect to a containerized instance.

### How can I persist files when using the Docker installation method?

The Docker sandboxing intentionally prevents filesystem persistence for security isolation. To retain files between sessions, you must use the native installation method linked in the Docker warning notice rather than the containerized version. The [`install-docker.sh`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/install-docker.sh) script is designed for quick testing only, not for production workflows requiring data persistence.