Secure Code Sandbox MCP Server for Docker Containers

Overview

The Secure Code Sandbox MCP Server implements a Model Context Protocol (MCP) endpoint that executes untrusted or model-generated code inside isolated Docker container sandboxes. It provides a controlled runtime environment with resource limits, network isolation, and lifecycle management so that AI agents or external tools can run arbitrary code without compromising the host system. The server is meant for teams that need to evaluate or run ephemeral workloads produced by models in a repeatable, auditable, and safe way.

The server acts as a mediator between callers (for example, model agents or developer tools) and Docker-based sandboxes. Typical flows include creating a sandbox session, staging files or input, running commands inside a container, streaming logs and outputs back to the caller, and collecting artifacts. Configuration options let operators restrict images, limit CPU/memory, set timeouts, and require authentication tokens so the service can be deployed inside a secure CI/infra network.

Features

• Docker-backed sandbox execution with ephemeral containers
• Per-session resource limits: CPU, memory, disk, process count, and timeout
• Network isolation and optional allow/deny networking policies
• File staging and artifact retrieval for inputs and outputs
• Streaming logs and command output (stdout/stderr) to clients
• Simple token-based authentication and configurable access controls
• Image allowlist and sandbox image templates for reproducible environments
• Health, metrics, and structured audit logs for monitoring and compliance
• Configurable via environment variables or YAML/JSON config files
• Designed for integration with MCP-compatible agents and tools

Installation / Configuration

Clone and build the project locally, or pull a published image (if available).

Basic build and run (local development):

git clone https://github.com/Automata-Labs-team/code-sandbox-mcp.git
cd code-sandbox-mcp

# Build the image
docker build -t code-sandbox-mcp .

# Run the server (bind port 8080, pass env configuration)
docker run --rm -p 8080:8080 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  --env-file .env \
  code-sandbox-mcp

Example .env (key variables):

MCP_PORT=8080
MCP_AUTH_TOKEN=replace-with-secret-token
SANDBOX_IMAGE_ALLOWLIST=python:3.11,ubuntu:22.04,node:20
MAX_CONTAINER_CPU=1.0            # CPU quota
MAX_CONTAINER_MEMORY=512m        # memory limit
CONTAINER_TIMEOUT_SECONDS=60     # per-command timeout
DISABLE_NETWORK=true             # disable container network by default

Example YAML config (alternative to env vars):

server:
  port: 8080
auth:
  token: "replace-with-secret-token"
sandbox:
  imageAllowlist:
    - "python:3.11"
    - "ubuntu:22.04"
  maxCpu: 1.0
  maxMemory: "512m"
  timeoutSeconds: 60
  disableNetwork: true
logging:
  level: info

Security notes:

• The server requires access to the Docker socket to create containers. Run on a dedicated host or isolate with additional kernel-level measures (gVisor, kata-containers) if you need stronger containment.
• Use a strong secret for MCP_AUTH_TOKEN or integrate with a reverse proxy / mTLS for authentication.
• Keep the image allowlist minimal and prefer minimal runtime images.

Available Resources

• Sandbox images: pre-approved container images (provided as config allowlist)
• Example sandboxes: small project templates for Python, Node, Rust, etc.
• REST/WebSocket endpoints: session lifecycle, execute command, stream logs, download artifacts
• Health and metrics endpoints: /health, /metrics for Prometheus scraping
• Audit logs: structured JSON logs for each session and executed command
• GitHub repo with sample clients and integration examples: https://github.com/Automata-Labs-team/code-sandbox-mcp

Common environment/configuration options:

Use Cases

1. Evaluate model-generated Python safely

   • Flow: create session → upload script → run python script.py → stream output → collect artifacts.
   • Example (conceptual):

     # Create session
     curl -X POST -H "Authorization: Bearer $MCP_AUTH_TOKEN" \
       -H "Content-Type: application/json" \
       -d '{"image":"python:3.11","timeout":30}' \
       http://localhost:8080/sessions
     
     # Upload file (script.py)
     curl -X PUT -H "Authorization: Bearer $MCP_AUTH_TOKEN" \
       --data-binary @script.py \
       http://localhost:8080/sessions/<session-id>/files/script.py
     
     # Execute
     curl -X POST -H "Authorization: Bearer $MCP_AUTH_TOKEN" \
       -H "Content-Type: application/json" \
       -d '{"command":["python","script.py"]}' \
       http://localhost:8080/sessions/<session-id>/exec
     

2. Run compiled code or tests generated by an LLM

   • Use an Ubuntu or build-image; run gcc or cargo build inside the sandbox, then execute the result. Artifacts can be downloaded after execution.

3. Safe exploratory tooling and CI for model outputs

   • Integrate with CI pipelines to run unit tests or fuzzing on code produced by models without exposing the build host. Limit network and CPU to contain potential abuse.

4. Teaching and interactive notebooks

   • Provide per-student sandboxes that reset after each session. Use image templates for consistent learning environments.

Next steps

• Review the project’s GitHub for API docs and example clients.
• Harden deployment: run on a dedicated VM, enable kernel sandboxing layers, and integrate with your observability stack.
• Tune image allowlist and resource limits