Docker沙盒环境配置指南：安全隔离Claude Code开发环境

sandbox%3Adocker-sandbox-setup by aaronbassett/agent-foundry

1 周安装量

1 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/aaronbassett/agent-foundry --skill sandbox:docker-sandbox-setup

开发开发运维安全

🇨🇳中文介绍

docker-sandbox-setup

配置 Docker 容器以在隔离、安全的环境中运行 Claude Code，防止 AI 代理修改主机系统。

目的

此技能专门提供用于创建沙盒化开发环境的 Docker 配置知识。重点在于实现 Claude Code 隔离所需的最小 Docker 设置，同时保持完整的开发能力，而非提供通用的 Docker 专业知识。

核心概念

隔离策略

沙盒使用 Docker 在 Claude Code 和主机系统之间创建完全隔离：

容器边界：所有 Claude Code 操作都在容器内进行
卷挂载：主机和容器之间共享工作空间以访问文件
网络隔离：为 Web 开发进行端口转发，无直接主机网络访问
持久化缓存：包管理器和构建缓存跨重启保留

基础镜像选择

默认推荐：Ubuntu 24.04 LTS

FROM ubuntu:24.04

选择 Ubuntu 24.04 的原因：

稳定的 LTS 版本，支持周期长
使用广泛，软件包可用性高
稳定性和现代工具之间的良好平衡

替代镜像：

debian:bookworm - 最小化，镜像尺寸更小
ubuntu:25.04 - 最新功能，支持周期较短

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

自定义基础镜像

为了使用预装了常用工具的自定义基础镜像来加速沙盒创建：

何时使用自定义基础镜像：

创建具有相似工具集的多个沙盒
希望沙盒初始化更快
所有项目使用标准工具集

# my-sandbox-base.dockerfile
FROM ubuntu:24.04

# 安装常用工具
RUN apt-get update && apt-get install -y \
    curl wget git build-essential \
    ripgrep fd-find jq python3 python3-pip \
    && rm -rf /var/lib/apt/lists/*

# 安装 Rust
RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
ENV PATH="/root/.cargo/bin:${PATH}"

# 通过 nvm 安装 Node.js
RUN curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

构建并打标签：

docker build -f my-sandbox-base.dockerfile -t my-sandbox-base:latest .

在 Sandbox.toml 中使用：

[sandbox]
base_image = "my-sandbox-base:latest"

挂载工作空间和持久化目录：

docker run \
  -v $(pwd)/workspace:/workspace \
  -v $(pwd)/.docker-cache/cargo:/root/.cargo \
  -v $(pwd)/.docker-cache/npm:/root/.npm \
  -v $(pwd)/.docker-cache/pip:/root/.cache/pip \
  -v $(pwd)/.docker-cache/claude:/root/.claude \
  sandbox-container

关键挂载点：

/workspace - 项目源代码（可从主机编辑）
/root/.cargo - Rust 包缓存
/root/.npm - Node.js 包缓存
/root/.cache/pip - Python 包缓存
/root/.claude - Claude Code 配置和缓存

源代码可从主机编辑
包在容器重启后持久存在
Claude Code 身份验证持久存在
容器重建速度快

为 Web 开发转发端口：

docker run -p 3000-3999:3000-3999 sandbox-container

端口范围选择理由：

常见的开发服务器端口（3000、3001 等）
支持单体仓库中的多个服务
范围足够灵活，又足够窄以保证安全

自定义端口： 从 package.json 脚本或用户指定中检测：

# 仅特定端口
docker run -p 3000:3000 -p 8080:8080 sandbox-container

传递必需的环境变量：

docker run \
  --env-file .env \
  -e GITHUB_TOKEN="${GITHUB_TOKEN}" \
  sandbox-container

GITHUB_TOKEN - 用于 gh CLI 操作
在 .env 中指定的自定义 API 密钥

敏感的主机环境变量
系统路径或凭据

FROM ubuntu:24.04

# 为 apt 设置非交互式前端
ENV DEBIAN_FRONTEND=noninteractive

# 安装基础包
RUN apt-get update && apt-get install -y \
    curl wget git build-essential \
    ca-certificates gnupg \
    && rm -rf /var/lib/apt/lists/*

# 设置工作目录
WORKDIR /workspace

# 安装语言（Rust、Python、Node.js）
# ... 语言特定设置 ...

# 安装 CLI 工具
# ... 工具安装 ...

# 安装 Claude Code
RUN curl -fsSL https://claude.ai/install.sh | bash

# 配置 shell
# ... shell 设置 ...

CMD ["/bin/bash"]

按变更频率排序 Dockerfile 命令：

基础包（很少更改）
语言运行时（偶尔更新）
CLI 工具（偶尔更新）
项目依赖项（频繁更改）
源代码（不断更改 - 改用卷挂载）

良好的排序：

# 很少更改 - 缓存效果好
FROM ubuntu:24.04
RUN apt-get update && apt-get install -y curl git

# 偶尔更改 - 中等缓存命中率
RUN install_rust_stable

# 频繁更改 - 通过卷挂载，不放入镜像
# （不要将源代码 COPY 到镜像中）

较早的层缓存时间更长
对较后层的更改不会使较早的缓存失效
开发期间重建速度更快

多阶段构建注意事项

沙盒容器通常不需要多阶段构建，因为：

容器是开发环境，而非生产镜像
开发需要完整的工具集可用
功能比尺寸优化更重要

对于沙盒，跳过多阶段构建。

#!/bin/bash
# up.sh

docker build -t sandbox-${PROJECT_NAME} .
docker run -d \
  --name sandbox-${PROJECT_NAME} \
  -v $(pwd)/workspace:/workspace \
  -v $(pwd)/.docker-cache/cargo:/root/.cargo \
  -v $(pwd)/.docker-cache/npm:/root/.npm \
  -v $(pwd)/.docker-cache/pip:/root/.cache/pip \
  -v $(pwd)/.docker-cache/claude:/root/.claude \
  -p 3000-3999:3000-3999 \
  --env-file .env \
  sandbox-${PROJECT_NAME}

echo "沙盒正在启动..."

# 等待并检查容器是否在运行
sleep 2
if docker ps | grep -q "sandbox-${PROJECT_NAME}"; then
    echo "✅ 沙盒正在运行！"
    echo "使用以下命令访问：./sandbox/shell.sh"
else
    echo "❌ 启动沙盒失败。"
    echo "检查日志：docker logs sandbox-${PROJECT_NAME}"
    exit 1
fi

#!/bin/bash
# shell.sh

docker exec -it sandbox-${PROJECT_NAME} /bin/zsh

#!/bin/bash
# run.sh

docker exec sandbox-${PROJECT_NAME} "$@"

#!/bin/bash
# stop.sh

docker stop sandbox-${PROJECT_NAME}
docker rm sandbox-${PROJECT_NAME}

添加视觉指示器以表明你处于容器中：

# 在 .zshrc 中
if [ -f /.dockerenv ]; then
    export IN_CONTAINER=true
    # Starship 将显示容器指示器
fi

Starship 配置能识别此变量：

[container]
disabled = false
symbol = "🐳 "
style = "bold red"

保留构建上下文

使用 .dockerignore 排除不必要的文件：

# .dockerignore
.git
node_modules/
.docker-cache/
*.log
.env.local

构建更快（上下文更小）
防止意外复制敏感文件
减小镜像尺寸

为长时间运行的服务添加健康检查：

HEALTHCHECK --interval=30s --timeout=3s \
  CMD curl -f http://localhost:3000/ || exit 1

谨慎使用 - 仅用于需要它的服务。

容器默认以 root 身份运行。在工作空间中创建的文件将归 root 所有。

解决方案 1：匹配主机 UID/GID

ARG USER_ID=1000
ARG GROUP_ID=1000

RUN groupadd -g ${GROUP_ID} developer && \
    useradd -u ${USER_ID} -g developer developer

USER developer

解决方案 2：在停止时修复权限

# 在 stop.sh 中
docker exec sandbox-${PROJECT_NAME} chown -R $(id -u):$(id -g) /workspace
docker stop sandbox-${PROJECT_NAME}

为简单起见，选择解决方案 2。

容器默认是网络隔离的。只有暴露的端口可访问。

端口 22 (SSH)
数据库端口（除非必需）
内部服务端口

切勿将密钥构建到镜像中：

# ❌ 错误做法
RUN git clone https://user:password@github.com/repo.git

# ✅ 正确做法
RUN git clone https://github.com/repo.git
# （需要在环境中提供 GITHUB_TOKEN）

改用 .env 文件和 --env-file 标志。

用于详细故障排除和优化：

references/troubleshooting.md - 常见的 Docker 问题及解决方案
references/optimization.md - 性能和开发体验改进

完整的工作示例：

examples/Dockerfile.template - 包含所有功能的完整 Dockerfile 模板
examples/docker-compose.yml - 使用 Docker Compose 的替代方案

与其他技能的集成

与 language-environment-config：

此技能处理 Docker 容器设置
language-environment-config 处理容器内的语言安装
在生成 Dockerfile 时同时使用两者

与 sandbox-config-management：

此技能实现 Sandbox.toml 指定的内容
从 Sandbox.toml 读取 base_image、ports、volumes
生成与配置文件匹配的 Docker 配置

默认基础镜像： ubuntu:24.04

必需的卷挂载：

/workspace - 源代码
/root/.cargo - Rust 缓存
/root/.npm - Node 缓存
/root/.cache/pip - Python 缓存
/root/.claude - Claude Code 配置

常用端口范围： -p 3000-3999:3000-3999

环境变量： --env-file .env + -e GITHUB_TOKEN

Dockerfile 顺序： 基础 → 语言 → 工具 → 配置

对于开发容器，跳过多阶段构建

🇺🇸English

docker-sandbox-setup

Configure Docker containers to run Claude Code in isolated, safe environments that prevent AI agents from modifying the host system.

Purpose

This skill provides Docker configuration knowledge specifically for creating sandboxed development environments. Focus on the minimum Docker setup needed for Claude Code isolation while maintaining full development capabilities, not general Docker expertise.

Core Concepts

Isolation Strategy

Sandboxes use Docker to create complete isolation between Claude Code and the host system:

Container boundary : All Claude Code operations occur within the container
Volume mounts : Workspace shared between host and container for file access
Network isolation : Port forwarding for web development, no direct host network access
Persistent caches : Package managers and build caches preserved across restarts

Base Image Selection

Default recommendation : Ubuntu 24.04 LTS

FROM ubuntu:24.04

Why Ubuntu 24.04:

Stable LTS release with long support window
Widely used, extensive package availability
Good balance of stability and modern tooling

Alternative images:

debian:bookworm - Minimal, smaller image size
ubuntu:25.04 - Latest features, shorter support

Custom Base Images

For faster sandbox creation with common tools pre-installed, build a custom base image:

When to use custom base images:

Creating multiple sandboxes with similar tooling
Want faster sandbox initialization
Standard tool set across all projects

How to create:

# my-sandbox-base.dockerfile
FROM ubuntu:24.04

# Install common tools
RUN apt-get update && apt-get install -y \
    curl wget git build-essential \
    ripgrep fd-find jq python3 python3-pip \
    && rm -rf /var/lib/apt/lists/*

# Install Rust
RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
ENV PATH="/root/.cargo/bin:${PATH}"

# Install Node.js via nvm
RUN curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

Build and tag:

docker build -f my-sandbox-base.dockerfile -t my-sandbox-base:latest .

Use in Sandbox.toml:

[sandbox]
base_image = "my-sandbox-base:latest"

Container Configuration

Volume Mounts

Mount the workspace and persistence directories:

docker run \
  -v $(pwd)/workspace:/workspace \
  -v $(pwd)/.docker-cache/cargo:/root/.cargo \
  -v $(pwd)/.docker-cache/npm:/root/.npm \
  -v $(pwd)/.docker-cache/pip:/root/.cache/pip \
  -v $(pwd)/.docker-cache/claude:/root/.claude \
  sandbox-container

Critical mounts:

/workspace - Project source code (editable from host)
/root/.cargo - Rust package cache
/root/.npm - Node.js package cache
/root/.cache/pip - Python package cache
/root/.claude - Claude Code config and cache

Benefits:

Source code editable from host
Packages persist across container restarts
Claude Code authentication persists
Fast container rebuilds

Port Forwarding

Forward ports for web development:

docker run -p 3000-3999:3000-3999 sandbox-container

Port range rationale:

Common dev server ports (3000, 3001, etc.)
Supports multiple services in monorepos
Wide enough for flexibility, narrow enough for security

Custom ports: Detect from package.json scripts or user specification:

# Specific ports only
docker run -p 3000:3000 -p 8080:8080 sandbox-container

Environment Variables

Pass through essential environment variables:

docker run \
  --env-file .env \
  -e GITHUB_TOKEN="${GITHUB_TOKEN}" \
  sandbox-container

Always pass through:

GITHUB_TOKEN - For gh CLI operations
Custom API keys as specified in .env

Never pass through:

Sensitive host environment variables
System paths or credentials

Dockerfile Structure

Basic Template

FROM ubuntu:24.04

# Set non-interactive frontend for apt
ENV DEBIAN_FRONTEND=noninteractive

# Install base packages
RUN apt-get update && apt-get install -y \
    curl wget git build-essential \
    ca-certificates gnupg \
    && rm -rf /var/lib/apt/lists/*

# Set working directory
WORKDIR /workspace

# Install languages (Rust, Python, Node.js)
# ... language-specific setup ...

# Install CLI tools
# ... tool installation ...

# Install Claude Code
RUN curl -fsSL https://claude.ai/install.sh | bash

# Configure shell
# ... shell setup ...

CMD ["/bin/bash"]

Layer Optimization

Order Dockerfile commands by change frequency:

Base packages (rarely change)
Language runtimes (occasionally update)
CLI tools (occasionally update)
Project dependencies (change frequently)
Source code (changes constantly - use volume mount instead)

Good ordering:

# Rarely changes - cached well
FROM ubuntu:24.04
RUN apt-get update && apt-get install -y curl git

# Occasionally changes - medium cache hit rate
RUN install_rust_stable

# Frequently changes - volume mounted, not in image
# (Don't COPY source code into image)

Why this matters:

Earlier layers cached longer
Changes to later layers don't invalidate earlier cache
Faster rebuilds during development

Multi-Stage Considerations

Multi-stage builds are typically NOT needed for sandbox containers because:

Containers are development environments, not production images
Need full tooling available for development
Size optimization less critical than functionality

Skip multi-stage builds for sandboxes.

Container Lifecycle

Starting a Sandbox

#!/bin/bash
# up.sh

docker build -t sandbox-${PROJECT_NAME} .
docker run -d \
  --name sandbox-${PROJECT_NAME} \
  -v $(pwd)/workspace:/workspace \
  -v $(pwd)/.docker-cache/cargo:/root/.cargo \
  -v $(pwd)/.docker-cache/npm:/root/.npm \
  -v $(pwd)/.docker-cache/pip:/root/.cache/pip \
  -v $(pwd)/.docker-cache/claude:/root/.claude \
  -p 3000-3999:3000-3999 \
  --env-file .env \
  sandbox-${PROJECT_NAME}

echo "Sandbox is starting..."

# Wait and check if the container is running
sleep 2
if docker ps | grep -q "sandbox-${PROJECT_NAME}"; then
    echo "✅ Sandbox is running!"
    echo "Access it with: ./sandbox/shell.sh"
else
    echo "❌ Failed to start sandbox."
    echo "Check logs: docker logs sandbox-${PROJECT_NAME}"
    exit 1
fi

Interactive Shell

#!/bin/bash
# shell.sh

docker exec -it sandbox-${PROJECT_NAME} /bin/zsh

Running Commands

#!/bin/bash
# run.sh

docker exec sandbox-${PROJECT_NAME} "$@"

Stopping a Sandbox

#!/bin/bash
# stop.sh

docker stop sandbox-${PROJECT_NAME}
docker rm sandbox-${PROJECT_NAME}

Common Patterns

Detecting Container Environment

Add visual indicators that you're in a container:

# In .zshrc
if [ -f /.dockerenv ]; then
    export IN_CONTAINER=true
    # Starship will show container indicator
fi

Starship config recognizes this:

[container]
disabled = false
symbol = "🐳 "
style = "bold red"

Preserving Build Context

Use .dockerignore to exclude unnecessary files:

# .dockerignore
.git
node_modules/
.docker-cache/
*.log
.env.local

Benefits:

Faster builds (smaller context)
Prevents accidentally copying sensitive files
Reduces image size

Health Checks

Add health checks for long-running services:

HEALTHCHECK --interval=30s --timeout=3s \
  CMD curl -f http://localhost:3000/ || exit 1

Use sparingly - only for services that need it.

Security Considerations

File Permissions

Container runs as root by default. Files created in workspace will be root-owned.

Solution 1: Match host UID/GID

ARG USER_ID=1000
ARG GROUP_ID=1000

RUN groupadd -g ${GROUP_ID} developer && \
    useradd -u ${USER_ID} -g developer developer

USER developer

Solution 2: Fix permissions on stop

# In stop.sh
docker exec sandbox-${PROJECT_NAME} chown -R $(id -u):$(id -g) /workspace
docker stop sandbox-${PROJECT_NAME}

Choose Solution 2 for simplicity.

Network Isolation

Containers are network-isolated by default. Only exposed ports are accessible.

Don't expose:

Port 22 (SSH)
Database ports unless required
Internal service ports

Secret Management

Never build secrets into the image:

# ❌ BAD
RUN git clone https://user:password@github.com/repo.git

# ✅ GOOD
RUN git clone https://github.com/repo.git
# (Requires GITHUB_TOKEN in environment)

Use .env files and --env-file flag instead.

Additional Resources

Reference Files

For detailed troubleshooting and optimization:

references/troubleshooting.md - Common Docker issues and solutions
references/optimization.md - Performance and DevX improvements

Example Files

Complete working examples:

examples/Dockerfile.template - Full Dockerfile template with all features
examples/docker-compose.yml - Alternative using Docker Compose

Integration with Other Skills

With language-environment-config:

This skill handles Docker container setup
language-environment-config handles language installation inside container
Use both together when generating Dockerfiles

With sandbox-config-management:

This skill implements what Sandbox.toml specifies
Read base_image, ports, volumes from Sandbox.toml
Generate Docker configuration matching the config file

Quick Reference

Default base image: ubuntu:24.04

Required volume mounts:

/workspace - Source code
/root/.cargo - Rust cache
/root/.npm - Node cache
/root/.cache/pip - Python cache
/root/.claude - Claude Code config

Common port range: -p 3000-3999:3000-3999

Environment: --env-file .env + -e GITHUB_TOKEN

Order Dockerfile: Base → Languages → Tools → Config

Skip multi-stage builds for dev containers

Weekly Installs

Repository

aaronbassett/ag…-foundry

GitHub Stars

First Seen

1 day ago

Installed on

zencoder1

amp1

cline1

openclaw1

opencode1

cursor1

Azure RBAC 权限管理工具：查找最小角色、创建自定义角色与自动化分配

117,000 周安装

Docker沙盒环境配置指南：安全隔离Claude Code开发环境

🇨🇳中文介绍

docker-sandbox-setup

目的

核心概念

隔离策略

基础镜像选择

相关 Skills

自定义基础镜像

容器配置

卷挂载

端口转发

环境变量

Dockerfile 结构

基础模板

层优化

多阶段构建注意事项

容器生命周期

启动沙盒

交互式 Shell

运行命令

停止沙盒

常见模式

检测容器环境

保留构建上下文

健康检查

安全注意事项

文件权限

网络隔离

密钥管理

附加资源

参考文件

示例文件

与其他技能的集成

快速参考

🇺🇸English

docker-sandbox-setup

Purpose

Core Concepts

Isolation Strategy

Base Image Selection

Custom Base Images

Container Configuration

Volume Mounts

Port Forwarding

Environment Variables

Dockerfile Structure

Basic Template

Layer Optimization

Multi-Stage Considerations

Container Lifecycle

Starting a Sandbox

Interactive Shell

Running Commands

Stopping a Sandbox

Common Patterns

Detecting Container Environment

Preserving Build Context

Health Checks

Security Considerations

File Permissions

Network Isolation

Secret Management

Additional Resources

Reference Files

Example Files

Integration with Other Skills

Quick Reference

最新 Skills