The Complete Production SOP: How to Deploy and Run Docker Ephemeral Sandboxes for Untrusted Code Execution in Autonomous AI Agents
Step-by-step SOP to isolate untrusted agent code execution inside hardened Docker containers for Codex, Claude Code, Cursor, and Windsurf.
Technical Overview & Architectural Context
Autonomous coding agents like Claude Code, Codex, and Cursor frequently generate and execute ad-hoc validation scripts, untrusted unit tests, or dynamic package scripts. Without strict container isolation, agents routinely pollute host environments, spawn orphan processes, execute infinite loops that exhaust host CPU/RAM, or inadvertently access sensitive host tokens and environment variables mounted within ~/.config or ~/.ssh. Deploying the 'Docker Ephemeral Sandboxes for Untrusted Code Execution' (agent-sandbox-docker-isolation) skill forces agents to channel all runtime validation through hardened, single-use OCI containers. The skill programmatically enforces non-negotiable security flags including read-only root filesystems (--read-only), complete capability stripping (--cap-drop ALL), network isolation (--network none), capped in-memory scratch spaces (--tmpfs /tmp:rw,noexec,nosuid,size=64m), and deterministic execution timeouts, ensuring untrusted code can never escape or persist.
Prerequisites & Environment Requirements
Verified Search Intents & Long-Tail Queries Solved
This operational tutorial is engineered to provide deterministic solutions for these developer search queries:
Step-by-Step Execution Playbook
Install SKILL.md into Agent Registry Directory
Create the local agent skill definition file and link it to your active project workspace.
Autonomous runtimes such as Claude Code, Cursor, and Codex automatically scan directory trees like `.agents/skills` or `.cursor/skills` for frontmatter-declared capabilities. Placing `agent-sandbox-docker-isolation` in your workspace informs the agent to invoke hardened Docker runs whenever tests or scripts are generated.
mkdir -p .agents/skills/agent-sandbox-docker-isolation && cat << 'EOF' > .agents/skills/agent-sandbox-docker-isolation/SKILL.md
---
name: "agent-sandbox-docker-isolation"
description: "Isolate code generation and execution agents inside secure, ephemeral Docker containers."
metadata:
author: "Docker"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "run agent code in docker sandbox"
- "isolate untrusted code execution"
- "configure secure container sandbox"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: false
net_access: false
---
# Docker Ephemeral Sandboxes for Untrusted Code Execution
Run untrusted scripts only in ephemeral containers via:
docker run --rm --network none --cap-drop ALL --read-only \
--tmpfs /tmp:rw,noexec,nosuid,size=64m \
--memory 512m --cpus 1.0 \
-v "$(pwd)":/workspace:ro \
-w /workspace alpine:latest timeout 30s <command>
EOF---
name: "agent-sandbox-docker-isolation"
description: "Isolate code generation and execution agents inside secure, ephemeral Docker containers."
metadata:
author: "Docker"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "run agent code in docker sandbox"
- "isolate untrusted code execution"
- "configure secure container sandbox"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: false
net_access: false
---Use minimal base images like alpine variants to keep container boot times below 200ms and avoid bloating agent execution token budgets.
Do not omit `--rm`; failing to clean up dead containers will exhaust system inode tables and Docker daemon disk space over long agent loops.
Establish Host Isolation and Wrapper Scripts
Deploy a deterministic wrapper script that binds resource limits and security boundaries.
To prevent agents from mutating required security flags, expose a wrapper binary `run-sandboxed.sh` in the workspace scripts directory. The agent is directed by the skill rules to invoke this specific binary rather than raw, unvalidated Docker commands.
mkdir -p scripts && cat << 'EOF' > scripts/run-sandboxed.sh
#!/usr/bin/env bash
set -euo pipefail
IMAGE="${1:-node:20-alpine}"
shift
exec timeout 30s docker run \
--rm \
--network none \
--cap-drop ALL \
--security-opt no-new-privileges:true \
--read-only \
--tmpfs /tmp:rw,noexec,nosuid,size=64m \
--memory 512m \
--cpus 1.0 \
--pids-limit 64 \
-v "$(pwd):/app:ro" \
-w /app \
"$IMAGE" "$@"
EOF
chmod +x scripts/run-sandboxed.sh#!/usr/bin/env bash
set -euo pipefail
IMAGE="${1:-node:20-alpine}"
shift
exec timeout 30s docker run \
--rm \
--network none \
--cap-drop ALL \
--security-opt no-new-privileges:true \
--read-only \
--tmpfs /tmp:rw,noexec,nosuid,size=64m \
--memory 512m \
--cpus 1.0 \
--pids-limit 64 \
-v "$(pwd):/app:ro" \
-w /app \
"$IMAGE" "$@"Setting `--pids-limit 64` prevents fork bombs inside the container from starving host kernel process tables.
Mounting the workspace as read-only (`:ro`) protects source code from being deleted or overwritten during arbitrary test runs.
Trigger Intent Matching in Agent Prompts
Invoke the skill using natural language triggers that match the SKILL.md declaration.
Autonomous coding assistants evaluate user prompts against registered triggers. Using phrases like 'isolate untrusted code execution' or 'run agent code in docker sandbox' activates the container enforcement guidelines directly into the active inference context.
git add .agents/skills/agent-sandbox-docker-isolation scripts/run-sandboxed.sh && git commit -m 'chore: add docker isolation skill and sandbox runner'Explicitly state expected timeout thresholds in your prompt if untrusted tasks involve compilation, allowing the agent to tune container arguments safely.
Ensure the current user belongs to the `docker` group or has access to rootless Docker, or the agent will hang prompting for sudo credentials.
Self-Healing Output Verification & Exit Code Inspection
Force the agent to inspect exit codes and output logs before reporting completion.
Once untrusted execution concludes, the agent must check exit status 0. If execution fails due to memory caps or timeout, the agent must self-correct by optimizing code efficiency instead of loosening sandbox constraints.
./scripts/run-sandboxed.sh python:3.11-alpine python3 -c 'print("Sandbox verification successful")'if ./scripts/run-sandboxed.sh node:20-alpine node -e 'console.log("Node check OK")'; then
echo "Docker Sandbox verified successfully."
else
echo "Sandbox execution failed. Check resource caps and permissions."
exit 1
fiRedirect stdout and stderr separately in agent pipelines to parse failure reasons without parsing verbose container orchestration noise.
Never bypass `--network none` when tests claim they need internet; supply mock stubs instead.
Real-World Scenario: Executing Dynamic User-Supplied Data Transformation Scripts
“We have an untrusted user script uploaded as data_transform.py. Run agent code in docker sandbox to test this script with input.json and verify it returns valid schema output without touching the host filesystem.”
Runtime Troubleshooting & Failure Modes
Root Cause: The untrusted script attempted to write intermediate cache files or logs to a path outside mounted write-enabled tmpfs volumes.
Direct intermediate file output to /tmp or add a dedicated tmpfs mount: --tmpfs /workspace/cache:rw,noexec,size=32mRoot Cause: The agent invoked a language runtime inside an incompatible or uninstalled base container image.
Explicitly define the matching OCI image tag: use python:3.11-alpine for Python scripts and node:20-alpine for JavaScript/TypeScript scripts.Frequently Asked Questions (Docker Ephemeral Sandboxes for Untrusted Code Execution SOP)
Q:Can I use Docker Ephemeral Sandboxes for Untrusted Code Execution across Codex, Claude Code, and Cursor simultaneously?
Yes. The agent-sandbox-docker-isolation skill adheres to the open standard SKILL.md specification. Once installed in your repo root under `.agents/skills/` or `.cursor/skills/`, all major AI coding engines detect and respect its isolation constraints.
Q:How does Docker Ephemeral Sandboxes for Untrusted Code Execution prevent context window overflow during long agent sessions?
By offloading the execution policy to a static wrapper and concise procedural rules, the agent only retains exit codes and parsed test results in its context window instead of accumulating raw container logs or shell environment variables.
Q:Does this skill require escalated root or container permissions?
No. The skill defaults to `--cap-drop ALL`, non-root execution where configured, and drops privileges via `--security-opt no-new-privileges:true`. It achieves a security score of 98/100 and does not require running containers in privileged mode.
Ready to equip your autonomous agent with Docker Ephemeral Sandboxes for Untrusted Code Execution?
Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.