AI导哈

轻量级Docker沙盒CLI

一个支持模型上下文协议（MCP）的轻量级Docker沙盒CLI，为AI代理提供安全、隔离和临时环境以运行代码和命令。

  • by fyerfyer
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 fyerfyer/Agent-Docker-MCP

使用说明

代理docker mcp🐳

该项目是一个轻量级的重构版本 代理沙盒平台.

支持模型上下文协议（MCP）的轻量级Docker沙盒CLI。 为AI代理（如Cursor）构建，为它们提供了一个安全、隔离和可丢弃的环境来运行代码和命令。

当使用本地AI编码助手时，您通常希望他们运行测试、安装依赖项或执行shell命令，而不会弄乱您的主机。 agent-docker-mcp 无缝创建一个映射到您的项目的临时Docker容器，将其作为MCP服务器公开，供AI安全使用。

⚠️ 注： 该项目目前处于早期开发阶段 仅在Linux上使用Cursor IDE进行了测试.MOSC/Windows支持和与其他MCP客户端的兼容性可能会有所不同。

✨ 特性

  • 即时沙盒： 立即启动一个隔离的环境，将身份完美地挂载到您当前的工作目录中。
  • 原生MCP支持： 为代理提供标准工具，以安全地运行bash命令。
  • 结构化输出： exec_bash 返回机器可读的 stdout/stderr/exitCode/truncated 领域。
  • 后台工作： 在后台运行长期命令（开发服务器、监视器），并通过以下方式轮询它们 get_job_output.
  • 资源限制： 强化默认值包括内存/CPU/PID限制、功能下降和 no-new-privileges.
  • 严格模式： 一个标志选择在Docker之外禁用Docker，隔离网络和影子敏感文件。
  • 自动脚手架： 自动设置 .cursor/mcp.json 或 .vscode/mcp.json 与您最喜欢的IDE集成。
  • 会话历史记录和回放： 内置SQLite跟踪记录每个命令及其输出。你甚至可以像一个asciinema演员一样“重播”这个环节！

🚀 快速开始

先决条件:

  • Node.js>=18.0.0
  • Docker桌面/引擎正在运行（对于强化默认值，建议使用Docker>=20.10）

您可以直接使用以下命令运行我们的CLI npx （无需安装）：

# 1. Initialize the sandbox and setup agent configurations
npx agent-docker-mcp init

# 2. Start the sandbox for your project
npx agent-docker-mcp start

🛠 与AI IDE集成

光标

通过跑步 npx agent-docker-mcp init 在项目根目录中，CLI执行繁重的工作：

  1. 检查Docker运行状况并提取默认沙盒映像。
  2. 自动创建 .cursor/mcp.json （或 .vscode/mcp.json)用于MCP集成。
  3. 自动创建 .cursorrules 指示AI更喜欢沙盒而不是主机shell。

然后你需要去 Settings -> Tools & MCP 并启用 agent-docker MCP。

初始化后，AI代理将自动访问 agent-docker MCP工具！

副驾驶

只管跑 npx agent-docker-mcp init 在您的项目根目录中，一旦项目启动，代理将尝试启动MCP服务器本身！

📖 基本命令

# Initialize sandbox and scaffolding
npx agent-docker-mcp init

# Start a sandbox container for the current directory
npx agent-docker-mcp start

# Start in strict mode (no DooD, isolated network, .env shadowed)
npx agent-docker-mcp start --strict

# Execute a command inside the sandbox manually
# Quotes are handled safely, so `npx agent-docker-mcp exec echo "a b"` keeps "a b" as one argument.
npx agent-docker-mcp exec "npm run test"

# List active sandbox containers
npx agent-docker-mcp ps

# Stop the current sandbox
npx agent-docker-mcp stop

# List past sandbox sessions
npx agent-docker-mcp history

# Replay a specific session log (great for debugging agent actions)
npx agent-docker-mcp replay <session-id>

# Clean up orphaned sandbox containers
npx agent-docker-mcp cleanup

🔒 安全模型

沙盒使用多层隔离：

  • 内核强制边界 （真正的隔离）：cgroup的资源限制（内存、CPU、PID），能力边界集降至最小集， no-new-privileges、非root用户执行， .git 在中安装只读和可选的网络隔离/DouD禁用 --strict 模式。在严格模式下，Docker API访问由 wollomatic/socket-proxy sidecar加上一个瘦请求体过滤器，可以阻止特权容器、主机网络/pid、设备挂载和项目外绑定挂载。
  • 防脚枪护罩：正则表达式黑名单阻止了明显危险的命令，如 rm -rf / 或叉式炸弹。这是一个便利防护装置， 不 安全边界——确定的对手可以绕过字符串过滤。
  • 默认模式下的已知剩余风险：容器可以访问主机的 docker.sock （DooD）并可能使用 host Linux上的网络。这相当于授予代理本地根访问权限。 仅对您信任的项目使用默认模式。 对于不受信任的工作负载或公共代码，请使用 --strict.

⚙️ 配置

创建 .agent-docker/config.json 在项目根目录中覆盖默认值。CLI标志优先于配置文件。

{
  "image": "ubuntu:22.04",
  "strict": false,
  "network": "host",
  "allowDocker": true,
  "composeProxy": true,
  "resources": {
    "memoryMb": 4096,
    "cpus": 2,
    "pidsLimit": 512
  },
  "env": ["KEY=VALUE"],
  "protectPaths": [".env.local"]
}
字段 类型 默认值 描述
image 字符串 agent-docker-base:latest 用于沙盒的Docker镜像。
strict 布尔值 false 何时 true，禁用DooD，将网络切换到 bridge，并添加 .env 到 protectPathsDocker Compose仍然通过过滤套接字代理工作。
network "host" | "bridge" | "none" Linux： host，其他： bridge 集装箱网络模式。显式值覆盖 strict.
allowDocker 布尔值 true 将主机Docker套接字挂载到容器中。 strict 迫使这 false.
composeProxy 布尔值 true In strict 模式下，启动一个过滤套接字代理sidecar docker/docker compose 仍然工作。设置为 false 在严格模式下完全禁用Docker访问。
resources 对象 memoryMb: 4096, cpus: 2, pidsLimit: 512 cgroups对容器的限制。
env string[] [] 传递给容器的额外环境变量为 KEY=VALUE.
protectPaths string[] [] 项目中要屏蔽的文件 /dev/null:ro。目录将被忽略。

🧠 原理

  1. 身份挂载: agent-docker 将当前目录装载到容器中(ubuntu-默认情况下基于）使用完全相同的路径。代理生成或编辑的任何代码都会立即反映在您的主机上。
  2. MCP 服务器：生成标准配置后(init)，AI连接到 npx agent-docker serve，拿起专用工具(exec_bash, get_job_output等）在容器内。
  3. 执行与审计：命令通过以下方式发送到Docker dockerode 图书馆。解析执行流，并将其安全地记录到本地SQLite中(~/.config/agent-docker/db.sqlite)，并安全返回AI。

🧪 发展

# Install dependencies
pnpm install

# Build TypeScript
pnpm build

# Run unit tests
pnpm test

# Run Docker-backed E2E tests
pnpm test:e2e

📄 许可证

麻省理工学院

相关 MCP