With the arrival of next-generation developer CLI agents like Claude Code and Cline, developer productivity has reached unprecedented heights. These agents don't just recommend code snippets; they execute bash commands, edit files, manage git trees, and run test suites directly on your system.

However, this raw capability introduces major security hazards.

If a terminal-access AI agent is given direct, unconstrained access to your host machine:

• A single logic hallucination or a malicious prompt-injection could execute rm -rf / or delete database volumes.
• The agent could leak sensitive host environment variables, .env files, or cloud credentials.
• Malicious dependencies downloaded by the agent during a test run could run arbitrary scripts, scan your local network, or open reverse shells.

To harness the power of agentic coding without endangering host systems, you must build a robust security boundary. This article explores how to architect and implement ephemeral, resource-bounded Docker sandboxes to run coding agents securely, inspired by real-world implementations in the NanoClaw Agentic Platform.

🏗️ Architectural Overview: The Sandbox Boundary

The core security principle is simple: assume the agent is untrusted.

Instead of running agent processes on your primary workspace, every task is isolated inside a custom-configured, ephemeral Docker container. The host system acts strictly as an orchestrator, managing the container lifecycle, capturing output streams, and destroying the sandbox on exit.

🛠️ Configuring the Sandbox: Volumes, Networks, and CPU Bounds

To achieve strict containment while keeping the agent functional, the orchestrator configures the container execution parameters using precise Docker flags. Let's break down the core constraints:

1. Hard Memory and CPU Caps

Runaway recursive loops or memory-leaking test suites can starve host resources. Enforcing hard limits ensures the VM remains stable:

• --memory=4g: Prevents the container from consuming all host RAM and triggering Out-Of-Memory (OOM) failures.
• --cpus=2: Limits CPU core utilization, preventing single-threaded recursive loops from pinning the host CPU at 100%.

2. Read-Only SSH Key Mounting

If the agent needs to pull from private repositories, it requires SSH keys. However, giving the agent write access to your primary SSH keys is a massive risk. We solve this by mounting the keys strictly in read-only mode:

-v /home/azureuser/.ssh/id_ed25519:/home/coder/.ssh/id_ed25519:ro

By appending the :ro flag, the agent can authenticate with remote git servers, but any attempt to overwrite, delete, or alter the host keys will be blocked by the Docker filesystem daemon.

3. Loopback Network Routing

To allow the container to access host-level tools (such as local model gateways or databases) without exposing the entire host network, we inject a gateway mapping:

--add-host=host.docker.internal:host-gateway

This maps host.docker.internal to the host's bridge IP address, permitting targeted communication with designated host services while blocking arbitrary network probes.

🐍 Implement the Orchestration Engine in TypeScript

Below is the production-grade Node.js / TypeScript launcher used to orchestrate ephemeral containers. It spawns the sandbox, streams execution stdout/stderr in real-time, enforces a strict timeout threshold, and ensures the container is completely removed on exit.

import { spawn } from 'child_process';
import { logger } from './logger.js';

export interface SandboxOptions {
  sessionId: string;
  workspacePath: string;
  taskPrompt: string;
  apiKey: string;
  baseUrl: string;
  tool: 'claude' | 'cline';
  onProgress?: (chunk: string) => void;
}

/**
 * Manages the ephemeral lifecycle of an isolated coding container.
 */
export async function launchSecureSandbox(opts: SandboxOptions): Promise<string> {
  const {
    sessionId,
    workspacePath,
    taskPrompt,
    apiKey,
    baseUrl,
    tool,
    onProgress,
  } = opts;

  // Create a clean, deterministic container name
  const containerName = `nanoclaw-sandbox-${sessionId.replace(/[^a-zA-Z0-9]/g, '-')}`;

  logger.info({ sessionId, containerName, tool }, 'Provisioning secure sandbox...');

  // Configure Docker run arguments with strict security boundaries
  const dockerArgs = [
    'run',
    '--name', containerName,
    '--rm', // Automatically destroy container metadata and filesystem on exit
    '-v', `${workspacePath}:/workspace`, // Bind source code directory
    '-v', '/home/azureuser/.ssh/id_ed25519:/home/coder/.ssh/id_ed25519:ro', // Read-only SSH keys
    '-e', `AGENT_TYPE=${tool}`,
    '-e', `OPENAI_API_KEY=${apiKey}`,
    '-e', `OPENAI_BASE_URL=${baseUrl}`,
    '-e', `ANTHROPIC_API_KEY=${apiKey}`,
    '-e', `ANTHROPIC_BASE_URL=${baseUrl}`,
    '--add-host=host.docker.internal:host-gateway', // Secure host loopback
    '--memory=4g', // Hard RAM limit
    '--cpus=2',    // Hard CPU core limit
    'nanoclaw-agent-image:latest', // Custom-built sandbox image
    taskPrompt
  ];

  return new Promise((resolve, reject) => {
    let logBuffer = '';
    
    // Spawn the Docker process asynchronously
    const proc = spawn('docker', dockerArgs);

    proc.stdout.on('data', (data) => {
      const chunk = data.toString();
      logBuffer += chunk;
      if (onProgress) onProgress(chunk);
    });

    proc.stderr.on('data', (data) => {
      const chunk = data.toString();
      logBuffer += chunk;
      if (onProgress) onProgress(chunk);
    });

    // Enforce a hard 30-minute timeout for runaway loops
    const sandboxTimeout = setTimeout(() => {
      logger.warn({ containerName }, 'Sandbox execution exceeded limit. Terminating...');
      proc.kill();
      reject(new Error('Sandbox execution timed out after 30 minutes.'));
    }, 1800000); // 30 minutes

    proc.on('close', (code) => {
      clearTimeout(sandboxTimeout);
      if (code === 0) {
        logger.info({ containerName }, 'Sandbox exited successfully.');
        resolve(logBuffer);
      } else {
        const errorDetails = `Container crashed with code ${code}.\nLogs tail:\n${logBuffer.slice(-500)}`;
        logger.error({ containerName, code }, errorDetails);
        reject(new Error(errorDetails));
      }
    });

    proc.on('error', (err) => {
      clearTimeout(sandboxTimeout);
      logger.error({ error: err, containerName }, 'Failed to spawn Docker process.');
      reject(err);
    });
  });
}

🐳 Designing the Dockerfile: Locking Down the Sandbox

A standard Docker container running as root still presents escape vectors. To lock down the container itself, we must build a custom image that drops privileges and creates a safe user context.

Here is the secure Dockerfile structure:

FROM node:20-slim

# Install git, ssh-client, and build essentials for compiling modules
RUN apt-get update && apt-get install -y \
    git \
    openssh-client \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# Create a non-root group and user
RUN groupadd -g 1001 coder && \
    useradd -u 1001 -g coder -m -s /bin/bash coder

# Establish workspace boundaries
WORKDIR /workspace
RUN chown -R coder:coder /workspace

# Install the agent CLI globally under non-root permissions
USER coder
RUN npm install -g @anthropic-ai/claude-code @cline/cli

# Pre-configure SSH keys directory for read-only keys mounting
RUN mkdir -p /home/coder/.ssh && chmod 700 /home/coder/.ssh

# Copy entrypoint execution wrapper
COPY entrypoint.sh /usr/local/bin/entrypoint.sh
ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]

The Magic of --rm

Notice the --rm flag inside our TypeScript runner. When the agent container process terminates—either successfully, by crash, or due to timeout—the --rm flag tells the Docker daemon to instantly delete the container's active write layers, container metadata, and anonymous volumes.

Any malicious files downloaded, background processes spawned, or altered binaries are deleted from the disk, returning the host system to a completely clean slate for the next task session.

📈 Summary of Benefits

Implementing ephemeral sandboxing creates a robust three-tier defense:

1. Host Preservation: System crashes or file deletions are confined entirely to /workspace, preserving the host OS and databases.
2. Resource Starvation Prevention: CPU and RAM bounds protect your development servers or cloud VMs from grinding to a halt during runaway test failures.
3. Clean-Slate Guarantee: The combination of non-root Docker privileges and the --rm teardown lifecycle ensures that no persistent backdoors, scrapers, or viruses survive past the session lifespan.

By isolating your AI agents, you can safely deploy highly autonomous developer workflows with absolute peace of mind.