How to Run Cline in a Docker Sandbox & Dev Container

According to a June 2026 VentureBeat Pulse Research survey, only 30% of enterprises isolate their highest-risk AI agents in sandboxes, despite 54% of organizations having already experienced a confirmed AI agent security incident or near-miss VentureBeat Pulse Research Survey (June 2026). This 24-point gap between adoption and security highlights a significant vulnerability in local development workflows. When developers run autonomous agents directly on their host machines, they grant these tools access to their primary filesystems, terminal shells, and local network ports.

Cline is designed to accelerate software creation by executing tasks autonomously. The agent can read existing source files, write new modules, inspect directories, and run commands inside the VS Code terminal. This level of autonomy is highly effective, but it operates with the same system permissions as the human developer. If Cline receives an incorrect command, interprets instructions incorrectly, or attempts to install a compromised npm package containing malicious code, it can easily destroy local projects. A single hallucinated command can delete database directories, wipe repository files, or exfiltrate environment files to external servers.

Running agents inside a containerized sandbox is the most effective way to address these risks. Isolating Cline's operations inside a container scopes its filesystem visibility and terminal shell permissions, preventing accidental modifications to the host operating system. Standardizing this isolation across teams ensures that even if an agent runs a destructive command, the impact is confined to disposable container resources rather than primary developer workstations.

For example, if an agent is tasked with fixing a bug and decides to install a new package, it may inadvertently pull down a typo-squatted module from a public registry. This module could execute an installation script that searches the local environment for AWS credentials or git configuration secrets. Without a sandbox, those credentials are immediately exposed. A Docker container limits this exposure by ensuring the agent only sees mock credentials or the specific variables configured for that environment.

VS Code Dev Containers provide a standardized way to define, build, and run containerized development sandboxes. By using a devcontainer.json configuration, teams can ensure that the Cline extension is installed and run inside a secured Docker container rather than on the developer's host machine. This setup isolates filesystem changes and scopes all terminal commands to the container environment VS Code Dev Containers Documentation.

To configure a sandbox for Cline, create a devcontainer.json file inside a .devcontainer directory at the root of your project. This configuration must specify the base image, list the required VS Code extensions, mount persistent volumes, and set container permissions.

Below is a complete devcontainer.json configuration designed for running Cline securely:

{
  "name": "Cline Sandbox Container",
  "image": "mcr.microsoft.com/devcontainers/typescript-node:1-22-bookworm",
  "customizations": {
    "vscode": {
      "extensions": [
        "saoudrizwan.claude-dev"
      ]
    }
  },
  "mounts": [
    "source=cline-workspace-storage,target=/home/vscode/.vscode-server/data/User/globalStorage/saoudrizwan.claude-dev,type=volume"
  ],
  "runArgs": [
    "--cap-add=SYS_ADMIN"
  ],
  "postCreateCommand": "sudo chown -R vscode:vscode /home/vscode/.vscode-server/data/User/globalStorage/saoudrizwan.claude-dev"
}

This configuration contains several key settings:

The image property defines the container base. Using a Debian bookworm-based image ensures a stable and compatible runtime environment.

The customizations.vscode.extensions array lists the extension ID saoudrizwan.claude-dev, which is the identifier for Cline in the VS Code marketplace. Listing this extension ensures that VS Code automatically installs Cline inside the container server during build Cline GitHub Repository.

The mounts property is critical for data persistence. By default, dev containers are ephemeral. Rebuilding a container destroys the filesystem and deletes all files that are not stored in the mounted workspace. Cline saves its task logs, database history, and model preferences inside the globalStorage directory of the VS Code Server. Mapping a named Docker volume (cline-workspace-storage) to this path ensures your task history is preserved when rebuilding the container.

The runArgs property includes --cap-add=SYS_ADMIN. Cline includes a built-in browser tool that uses Puppeteer to read and interact with web pages. Chrome requires specific kernel capabilities to initialize its sandbox. Adding this flag grants the container the system administration privileges needed to run the browser tool without errors.

The postCreateCommand property runs a script after the container is built. Docker volumes are often initialized with root user ownership. If your container runs as the non-root vscode user, the server will lack permission to write to the volume, causing Cline to fail when saving logs. Running the chown command adjusts ownership, allowing the vscode user full write permissions.

While Dev Containers isolate the agent from the host filesystem, the container still has access to all files inside the mounted project workspace. If your project contains local environment configuration files, access tokens, or private keys, Cline can read and transmit them. To protect sensitive project files, you must configure a .clineignore file Cline GitHub Repository.

A .clineignore file works similarly to a .gitignore file. It defines matching patterns for files and directories that Cline is prohibited from reading or modifying. The extension intercepts all filesystem queries and blocks access to any matched paths.

Here is a recommended .clineignore configuration for a secure development workspace:

.env
.env.*
*.pem
id_rsa*
.aws/
.gcloud/
.git/
.github/
node_modules/
npm-debug.log
.devcontainer/
Dockerfile
docker-compose.yml

Placing this file in the root of your workspace blocks Cline from reading API credentials stored in your .env files or reading your private SSH keys. Additionally, ignoring .devcontainer and Dockerfile prevents the agent from modifying the sandbox configuration to escalate its own privileges.

Developers must remember that standard Docker container isolation shares the host machine's kernel. Although the container scopes filesystem access, it does not provide absolute kernel-level boundaries. If you run untrusted scripts or require high-security isolation, you should run the Docker daemon in rootless mode. Using rootless containers ensures that even if an attacker manages to escape the container sandbox, they will not obtain administrative access on the host operating system.

Isolating Cline inside a local Dev Container provides a safe environment for development, but it keeps the agent's output locked inside a single developer's host machine. When teams need to share files, review code, or collaborate on agent outputs, relying solely on local container storage creates significant friction.

Developers often attempt to address this by using local bind mounts to sync container directories with their host systems, mounting Amazon S3 buckets, or using consumer cloud storage like Google Drive or Dropbox. These alternatives present major limitations. They do not track detailed file version history, lack integrated search capabilities over the agent's output, and make it difficult for team members to collaborate on files.

An intelligent workspace platform like Fastio solves these collaboration challenges. Fastio provides shared workspaces where agents and humans collaborate on the same files, shares, and workflows. Instead of locking files inside local volumes, teams can connect their agents directly to Fastio.

Fastio supports agentic workflows by exposing a consolidated Model Context Protocol toolset via Streamable HTTP at /mcp and legacy SSE at /sse, which is documented at the Fastio developer documentation. Connecting Cline to this remote endpoint gives it direct access to the workspace.

Once you enable Intelligence Mode on a workspace, all files uploaded by Cline are automatically indexed for RAG chat and semantic search. Team members can query documents using Hybrid Search Metadata Views, which combines exact full-text matching with semantic retrieval to find specific passages, database schema files, or code documentation.

Additionally, Fastio tracks every edit using per-file version history. If Cline overwrites a file or writes broken code, developers can view the history and restore previous versions with a single click. When Cline completes a task, it can transfer organization ownership to a human reviewer using a claim link. The human reviewer then takes control of the billing and administrative settings. Fastio operates on a credit-based pricing model with paid plans starting at $29/mo for Starter, $99/mo for Business, and $299/mo for Growth Fastio Pricing Page. Every organization starts with a 14-day free trial that requires a credit card to activate, providing a reliable environment for your development workflows Fastio Product Features.

Build and hand off agent workspaces securely

Connect Cline to a shared workspace featuring automated indexing, version history, and ownership handoff tools. Start your 14-day free trial to set up your team workspace.

Start 14-Day Trial

Running Cline in a container sandbox requires proper configuration of the container runtime, permissions, and network settings. If you encounter issues during setup, use the following troubleshooting steps to resolve them.

If Cline's built-in browser tool fails to launch, the container is likely missing the system libraries required by Chromium. By default, minimal base images do not include these packages. You can resolve this by adding the required dependencies to your Dockerfile:

FROM mcr.microsoft.com/devcontainers/typescript-node:1-22-bookworm

RUN apt-get update && apt-get install -y \
  libnss3 \
  libatk1.0-0 \
  libatk-bridge2.0-0 \
  libcups2 \
  libdrm2 \
  libxkbcommon0 \
  libxcomposite1 \
  libxdamage1 \
  libxrandr2 \
  libgbm1 \
  libasound2 \
  && rm -rf /var/lib/apt/lists/*

After updating the Dockerfile, rebuild the container to install the packages. Also verify that your devcontainer.json contains the --cap-add=SYS_ADMIN option in the runArgs array, which is necessary for Chrome sandboxing to operate.

If your task history and settings disappear every time you reload the container, your volume mount is configured incorrectly. Check the paths in your devcontainer.json mounts array. The target path must match the home directory of the active container user. If the remoteUser is vscode, the path must be /home/vscode/.vscode-server/data/User/globalStorage/saoudrizwan.claude-dev. If the container runs as root, update the target to /root/.vscode-server/data/User/globalStorage/saoudrizwan.claude-dev.

If Cline throws write permission errors in the workspace, you must adjust the folder permissions. When you mount a local folder into the container, the file permissions on the host system may not align with the vscode user inside the container. You can resolve this by running chown -R vscode:vscode inside the terminal or adding the command to the postCreateCommand hook.

If Cline fails to connect to LLM APIs, verify the container's network settings. Docker containers running behind corporate firewalls or VPNs often require explicit proxy environment variables. Ensure that the HTTP_PROXY, HTTPS_PROXY, and NO_PROXY variables are passed into the container using the containerEnv property in your devcontainer.json file.