CodeRunner：为AI智能体打造本地安全沙盒，实现安全代码执行与自动化

1. CodeRunner 项目概述：为AI智能体打造一个本地的“安全屋”

如果你正在尝试让Claude Code、GPT-4o或者Gemini这类AI助手帮你写代码、处理文件，但心里总有点打鼓——万一它执行了rm -rf /怎么办？或者它想读取我电脑里的私人文档呢？这种担忧非常合理，毕竟让一个外部模型直接操作你的本地环境，无异于将家门钥匙交给一个陌生人。CodeRunner这个项目，就是为了解决这个核心痛点而生的。它本质上是一个本地沙盒环境，专门用来安全地运行AI智能体（Agent）生成的代码和操作指令。

你可以把它想象成一个功能齐全的“安全屋”或“隔离实验室”。AI助手在这个屋子里可以自由地敲代码、安装包、读写文件、甚至运行Web服务，但它所有的活动都被严格限制在这个屋子内，无法触及你主机上的真实数据和系统。这对于开发者、数据分析师、安全研究员，或者任何希望利用AI自动化工作流程但又担心安全问题的用户来说，是一个至关重要的工具。它的核心价值在于隔离与安全，让你可以大胆地授权AI去执行任务，而无需担心数据泄露或系统损坏。

2. 核心架构与安全设计解析

要理解CodeRunner为什么安全，我们需要深入其技术底座。CodeRunner并非从零造轮子，而是巧妙地构建在苹果公司开源的apple/container项目之上。这是一个关键点，也是其安全性的基石。

2.1 基于 Apple/container 的虚拟化隔离

apple/container项目为macOS（特别是Apple Silicon芯片）提供了一种轻量级但强隔离的容器运行时。它与我们熟知的Docker有本质区别：

• Docker容器：基于Linux内核的命名空间（namespace）和控制组（cgroup）技术实现隔离。虽然高效，但在理论上，内核漏洞可能导致“容器逃逸”，隔离强度被认为是一种“进程级隔离”。
• Apple/container：利用了macOS底层的虚拟化框架（Virtualization.framework），为每个容器提供了一个完整的、硬件虚拟化的轻量级虚拟机。这意味着每个容器都运行在一个独立的、精简的虚拟机实例中，拥有自己的内核（尽管是高度优化的）。这种“虚拟机级隔离”在安全性上远高于传统的进程级隔离，几乎完全消除了容器间或容器对宿主机产生影响的可能性。

注意：这种设计也带来了一个重要的平台限制：目前CodeRunner的核心沙盒功能仅支持运行在Apple Silicon（M1/M2/M3/M4）芯片的macOS上。这是因为它深度依赖苹果自家的虚拟化框架。项目路线图中提到的Linux支持，计划通过Firecracker（另一种轻量级虚拟机管理程序）来实现，但当前版本尚不可用。

2.2 MCP协议：连接AI大脑与沙盒身体的“神经”

有了坚固的“身体”（沙盒容器），还需要一个高效的“神经系统”来让外部的AI模型（大脑）控制它。这就是Model Context Protocol的作用。

MCP是一种新兴的开放协议，旨在标准化AI模型与外部工具、数据源之间的通信。你可以把它看作AI世界的“USB-C”接口。在CodeRunner的上下文中：

1. MCP服务器：运行在CodeRunner沙盒内部。它暴露了一系列“工具”（Tools），比如execute_python_code（执行Python代码）、list_skills（列出可用技能）等。
2. MCP客户端：集成在支持MCP的AI客户端中，如Claude Desktop、Claude Code CLI、OpenCode等。
3. 通信流程：当你在Claude Desktop中提出“请帮我分析这个CSV文件”时，Claude模型会判断需要调用execute_python_code工具。这个请求会通过MCP协议，从Claude Desktop（客户端）发送到CodeRunner的MCP服务器。服务器在沙盒内安全地执行对应的Python代码（例如使用pandas读取CSV），然后将执行结果或错误信息通过MCP协议返回给客户端，最终呈现给你。

这种设计的美妙之处在于解耦。AI模型不需要知道沙盒的具体实现，它只需要按照MCP协议调用工具。而CodeRunner只需要确保MCP服务器稳定运行，并安全地执行收到的指令。你可以在不同的AI助手（Claude, GPT, Gemini）之间无缝切换，只要它们支持MCP，就能共用同一个安全的CodeRunner沙盒。

2.3 技能系统：可扩展的自动化工具箱

CodeRunner不仅仅是一个代码执行器，它还内置了一个技能系统，这大大提升了其实用性。技能可以理解为预封装、可复用的自动化脚本或工具包。

• 内置公共技能：开箱即用，例如pdf-text-replace（替换PDF表单中的文本）和image-crop-rotate（图像裁剪旋转）。这些技能本身也是以Python脚本的形式存在于沙盒内，通过上述的execute_python_code工具间接调用。
• 自定义技能：这是系统强大的扩展点。用户可以将自己常用的脚本（例如：特定的数据清洗流程、文档转换脚本、API调用封装）组织成技能，存放在~/.coderunner/assets/skills/user/目录下。只要按照规范（包含SKILL.md说明文档和scripts/脚本目录）放置，CodeRunner就能自动发现它们，并通过list_skills工具展示给AI助手。这意味着你可以教会你的AI助手使用你的专属工具集。

实操心得：技能系统的目录结构设计得很清晰。在实际使用中，我建议在SKILL.md中尽可能详细地描述技能的输入、输出、以及使用示例。因为AI助手（如Claude）在调用技能前，可能会通过get_skill_info工具来读取这份文档，以理解该如何使用它。文档写得好，AI就能用得准。

3. 详细安装与配置指南

虽然项目提供的install.sh一键脚本很方便，但理解其背后每一步在做什么，有助于在出现问题时进行排查。下面我们拆解一下完整过程。

3.1 环境准备与依赖检查

在运行安装脚本前，请手动确认以下条件，这能避免很多后续问题：

1. 硬件与操作系统：确认你的Mac是Apple Silicon（M1, M2, M3, M4）芯片，并运行较新版本的macOS（Sonoma或更高版本推荐）。
2. Homebrew：这是macOS的包管理器，几乎必不可少。如果未安装，请从 brew.sh 获取安装命令。
3. Python 3.10+：通过python3 --version检查。如果没有，使用brew install python@3.11安装。关键点：确保pip命令对应的是Python 3的版本，有时系统自带的pip可能指向Python 2。使用pip3 --version确认。
4. Git：用于克隆仓库，通常已预装或可通过brew install git安装。

3.2 安装脚本深度解析

执行./install.sh后，脚本大致会完成以下工作，了解这些步骤有助于高级调试：

#!/bin/bash # 这是一个简化的原理说明，并非实际脚本内容 # 1. 权限提升：因为需要安装系统级组件和配置虚拟化，所以需要sudo权限。 # 2. 安装 apple/container 工具链：这是核心依赖。脚本会通过 Homebrew 安装 `container` 命令行工具。 # brew install apple/container/container # 3. 构建并启动 CodeRunner 容器镜像：脚本会利用 `container` 工具，基于项目内的 Dockerfile 或类似定义，构建一个包含完整Python环境、Jupyter内核、MCP服务器及内置技能的沙盒镜像，并将其以特定名称（如`coderunner`）运行起来。 # 4. 配置网络与端口映射：将容器内的MCP服务器端口（如8222）映射到宿主机的某个端口，或配置为本地域名（如`coderunner.local:8222`），以便外部AI客户端连接。 # 5. 初始化技能和资产目录：在用户目录下创建 `~/.coderunner/assets/` 结构，用于存放用户自定义技能和上传的文件。

常见问题与排查：

• 错误：virtualization不可用：这通常意味着macOS版本过旧，或者Mac是Intel芯片。请检查系统是否符合要求。
• 错误：端口冲突：如果8222端口被占用，安装可能会失败。你可以查看脚本内容，看是否有修改端口映射的选项，或者手动停止占用该端口的进程。
• 安装后无法连接：首先尝试container ps命令查看coderunner容器是否处于运行状态。如果未运行，尝试container start coderunner。如果容器运行但无法连接，检查宿主机的防火墙设置是否阻止了本地端口通信。

3.3 核心客户端配置详解

CodeRunner的强大在于其广泛的客户端兼容性。下面以最常用的Claude Desktop和Claude Code CLI为例，进行超详细配置说明。

3.3.1 配置 Claude Desktop

这是将CodeRunner与图形化Claude应用集成的标准方式。

1. 定位配置文件：Claude Desktop的MCP服务器配置通常位于~/Library/Application Support/Claude/claude_desktop_config.json。CodeRunner项目提供的examples/claude_desktop/目录中的示例文件是让你参考的模板。
2. 关键配置解析：你需要编辑的JSON配置核心部分是：

   { "mcpServers": { "coderunner": { "command": "/usr/local/bin/python3", // 这是关键！必须指向宿主机的Python解释器路径 "args": [ "/Users/你的用户名/coderunner/examples/claude_desktop/mcpproxy.py" // 代理脚本的绝对路径 ] } } }

   • command：绝对不能写成容器内的Python路径（如/app/venv/bin/python）。它必须是你宿主机上Python 3的路径。因为Claude Desktop进程是在宿主机上运行的，它需要启动一个本地进程（即mcpproxy.py）来与容器通信。你可以通过终端执行which python3来找到正确路径。
   • args：需要修改为mcpproxy.py脚本在你电脑上的绝对路径。请将/Users/你的用户名/替换成你的实际家目录路径。
3. 代理脚本的作用：mcpproxy.py这个文件至关重要。它扮演了一个“中转站”的角色：
   • 它在宿主机上运行，接收来自Claude Desktop的MCP请求。
   • 然后它通过HTTP或其它方式，将请求转发给运行在容器内的CodeRunner MCP服务器（http://coderunner.local:8222/mcp）。
   • 再将容器的响应传回给Claude Desktop。 这样做的好处是，Claude Desktop无需直接处理容器网络，所有复杂性由代理脚本封装。

配置步骤总结：

# 进入示例目录 cd /path/to/coderunner/examples/claude_desktop # 复制示例配置（如果你没有该目录的配置文件） cp claude_desktop_config.example.json ~/Library/Application\ Support/Claude/claude_desktop_config.json # 使用你喜欢的编辑器（如VSCode, nano, vim）编辑该文件 code ~/Library/Application\ Support/Claude/claude_desktop_config.json # 或者 nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

编辑完成后，完全退出Claude Desktop应用（右键点击Dock图标 -> 退出），再重新启动。进入设置 -> 开发者选项，你应该能看到coderunner服务器已添加。现在，当你和Claude对话时，它就可以提议使用CodeRunner的工具了。

3.3.2 配置 Claude Code CLI

Claude Code是Anthropic推出的命令行AI编程助手，与CodeRunner的集成更为原生和强大。

1. 安装CodeRunner插件：按照项目说明，使用Claude Code的插件市场命令添加。这里有一个易错点：确保你的Claude Code CLI已经成功安装并登录。插件安装命令是在Claude Code的交互式会话中执行的，而不是在普通终端。
2. 交互式安装流程：
   • 在终端输入claude进入Claude Code交互界面。
   • 输入/plugin marketplace add https://github.com/instavm/coderunner-plugin添加仓库。
   • 输入/plugin install instavm-coderunner安装插件。
   • 安装后，输入/mcp reconnect或按照提示重新连接MCP服务器。
3. 验证与使用：插件安装成功后，你可以直接让Claude Code执行操作，例如：“请使用CodeRunner创建一个Python脚本，计算斐波那契数列。” Claude Code会自动调用execute_python_code工具，并在回复中展示代码和执行结果。

实操心得：Claude Code CLI + CodeRunner 的组合是我个人认为效率最高的模式。它完全在终端内完成，无需在图形界面和命令行之间切换，非常适合沉浸式的编程和系统管理任务。插件会自动处理MCP连接，比手动配置Claude Desktop更省心。

4. 核心功能实战：从代码执行到技能运用

配置完成后，我们来看看如何在日常工作中实际使用CodeRunner。其核心功能围绕代码执行和技能调用展开。

4.1 安全地执行任意代码

这是最基本也是最常用的功能。当你让AI助手“运行这段代码”时，它会在沙盒内发生。

示例场景：数据清洗与分析假设你有一个脏乱的CSV文件sales_data.csv，想快速进行初步分析。

1. 上传文件：首先，你需要将文件放入CodeRunner沙盒能访问的位置。所有需要处理的文件都应放在~/.coderunner/assets/uploads/目录下。你可以手动复制，或者写一个简单的脚本。

   # 在宿主机终端执行 cp ~/Downloads/sales_data.csv ~/.coderunner/assets/uploads/

2. 向AI助手提问：在已配置好的Claude Desktop或Claude Code中，你可以直接说：

   “请使用CodeRunner读取sales_data.csv文件，检查是否有空值，并计算每个月的销售总额。数据中有date和amount列。”

3. AI助手的处理流程：

   • AI理解你的请求，生成相应的Python代码。
   • 通过MCP调用execute_python_code工具，发送类似以下的代码：

     import pandas as pd import os # 文件路径在容器内是 /app/uploads/ file_path = '/app/uploads/sales_data.csv' df = pd.read_csv(file_path) # 检查空值 null_counts = df.isnull().sum() print("各列空值数量：") print(null_counts) # 确保日期列是datetime类型并提取月份 df['date'] = pd.to_datetime(df['date']) df['month'] = df['date'].dt.to_period('M') # 按月分组求和 monthly_sales = df.groupby('month')['amount'].sum().reset_index() print("\n月度销售总额：") print(monthly_sales) # （可选）将结果保存回沙盒内，供后续步骤使用 output_path = '/app/uploads/monthly_sales_summary.csv' monthly_sales.to_csv(output_path, index=False) print(f"\n结果已保存至：{output_path}")

   • CodeRunner沙盒接收代码，在隔离的Jupyter内核中执行。
   • 执行结果（包括打印输出和可能的错误信息）通过MCP返回，显示在你的AI聊天界面中。

安全边界验证：你可以故意让AI执行危险命令来测试隔离性，例如在代码中加入import os; os.system('rm -rf /')或尝试读取/etc/passwd。你会发现，这些操作要么被限制在容器内（容器内的根目录是/，但这是虚拟的根），要么因权限问题失败，完全不会影响到你的宿主机。

4.2 探索与使用内置技能

技能系统让AI助手的能力超越了简单的代码执行，可以直接操作特定类型的文件。

实战：使用PDF文本替换技能假设你有一份PDF格式的标准化合同（contract.pdf），需要将其中的“甲方：[COMPANY_NAME]”替换为“甲方：某某科技有限公司”。

1. 放置文件：将contract.pdf放入上传目录。
2. 询问AI：你可以直接对AI说：“请使用CodeRunner的PDF技能，将contract.pdf中的‘[COMPANY_NAME]’替换为‘某某科技有限公司’，并生成新文件contract_filled.pdf。”
3. 幕后调用：AI助手会进行以下操作：
   • 首先，它可能调用list_skills()工具来查看有哪些可用技能。
   • 然后，调用get_skill_info("pdf-text-replace")来获取该技能的使用方法。
   • 最后，生成并调用执行一段Python代码，该代码内部会调用技能脚本：

     import subprocess subprocess.run([ 'python', '/app/uploads/skills/public/pdf-text-replace/scripts/replace_text_in_pdf.py', '/app/uploads/contract.pdf', '[COMPANY_NAME]', '某某科技有限公司', '/app/uploads/contract_filled.pdf' ])

4. 获取结果：替换完成后，新的contract_filled.pdf会生成在沙盒的/app/uploads/目录下，对应宿主机的~/.coderunner/assets/uploads/目录，你可以从中取出使用。

4.3 创建与使用自定义技能

这是将个人工作流固化的高级用法。例如，你经常需要将一批JPG图片转换为WebP格式并调整大小。

1. 创建技能目录结构：

   mkdir -p ~/.coderunner/assets/skills/user/image-converter/ cd ~/.coderunner/assets/skills/user/image-converter/

2. 编写技能文档 (SKILL.md)：

   # 图片转换与压缩技能 将指定目录下的JPG/PNG图片转换为WebP格式，并可选调整最大边长。 **输入参数：** 1. `input_dir`: 输入图片目录路径（容器内路径，如 `/app/uploads/images/`） 2. `output_dir`: 输出图片目录路径 3. `max_size` (可选): 输出图片的最大宽度或高度，默认保持原尺寸 **示例调用：** ```python # 转换 /app/uploads/images/ 下的所有图片，输出到 /app/uploads/converted/， 调整最大边长为1200像素 await execute_skill("image-converter", { "input_dir": "/app/uploads/images/", "output_dir": "/app/uploads/converted/", "max_size": 1200 })

3. 编写技能脚本 (scripts/convert.py)：

   #!/usr/bin/env python3 import os import sys from PIL import Image def convert_images(input_dir, output_dir, max_size=None): os.makedirs(output_dir, exist_ok=True) supported_ext = ('.jpg', '.jpeg', '.png') for filename in os.listdir(input_dir): if filename.lower().endswith(supported_ext): input_path = os.path.join(input_dir, filename) output_name = os.path.splitext(filename)[0] + '.webp' output_path = os.path.join(output_dir, output_name) try: with Image.open(input_path) as img: if max_size: img.thumbnail((max_size, max_size)) img.save(output_path, 'WEBP', quality=85) print(f"Converted: {filename} -> {output_name}") except Exception as e: print(f"Failed to convert {filename}: {e}") if __name__ == "__main__": if len(sys.argv) < 3: print("Usage: python convert.py <input_dir> <output_dir> [max_size]") sys.exit(1) input_dir = sys.argv[1] output_dir = sys.argv[2] max_size = int(sys.argv[3]) if len(sys.argv) > 3 else None convert_images(input_dir, output_dir, max_size)

4. 使用技能：现在，你可以直接告诉AI助手：“请使用我自定义的‘image-converter’技能，处理/app/uploads/images/里的所有图片，输出到/app/uploads/converted/，最大边长设为800像素。” AI助手会通过list_skills发现这个新技能，并生成正确的调用代码。

注意事项：自定义技能的脚本在沙盒容器内运行，因此只能访问容器内的文件系统（主要是/app/uploads/映射的区域）。确保你的脚本所需的Python库（如本例中的Pillow）已经安装在CodeRunner的容器环境中。如果没有，你可能需要先让AI助手在沙盒内执行pip install Pillow。

5. 高级集成与其他客户端配置

除了Claude系产品，CodeRunner的MCP服务器可以接入任何支持该协议的客户端，这极大地扩展了其应用场景。

5.1 配置 OpenAI Agents (Python库)

对于喜欢编程控制的用户，可以使用OpenAI的Python Agents SDK。这让你能用代码直接驱动AI智能体在沙盒中工作。

1. 环境准备：在宿主机（非容器内）创建一个Python虚拟环境并安装必要包。

   cd /path/to/coderunner/examples python3 -m venv venv source venv/bin/activate pip install -r requirements.txt # 这会安装 openai, mcp 等库 export OPENAI_API_KEY="sk-..." # 设置你的OpenAI API密钥

2. 运行示例客户端：examples/openai_agents/openai_client.py这个文件是一个简单的对话循环。运行它：

   python openai_client.py

3. 交互示例：程序启动后，你可以输入自然语言指令。

   你: 请写一个Python函数来计算斐波那契数列，并计算前10项。 Agent: 我将为您编写并执行代码。 [Agent调用 execute_python_code 工具...] 执行结果： 斐波那契数列前10项为：[0, 1, 1, 2, 3, 5, 8, 13, 21, 34]

   这种方式非常适合构建自动化流水线，例如：定期从某个URL抓取数据，在沙盒中清洗分析，然后生成报告。

5.2 配置 Gemini CLI 和 Kiro

配置Gemini CLI和Kiro的过程与Claude Desktop类似，核心都是修改其MCP服务器配置文件，指向CodeRunner的MCP服务器端点。

• Gemini CLI：编辑~/.gemini/settings.json，在mcpServers部分添加一个指向http://coderunner.local:8222/mcp的HTTP配置。这种是远程HTTP连接，要求CodeRunner的MCP服务器已经启动并在网络上可访问（通常本地网络没问题）。
• Kiro：编辑~/.kiro/settings/mcp.json，其配置格式与Claude Desktop更相似，使用command和args来指定一个本地代理脚本（和Claude Desktop共用同一个mcpproxy.py即可）。这种是通过本地命令代理。

配置选择建议：

• HTTP连接（如Gemini CLI配置）：更通用，任何能发送HTTP请求的客户端都能连接。但需要确保coderunner.local域名能正确解析到本地（通常通过/etc/hosts文件映射127.0.0.1 coderunner.local）。
• 命令代理（如Claude Desktop, Kiro配置）：更灵活稳定，代理脚本可以处理更复杂的连接逻辑和错误重试。推荐优先采用这种方式。

5.3 故障排除与连接测试

当配置完成后客户端无法连接时，可以按以下步骤排查：

1. 确认容器状态：在终端运行container ps，查看coderunner容器是否处于Running状态。
2. 测试MCP服务器端点：在宿主机终端使用curl测试连通性。

   curl -v http://coderunner.local:8222/mcp

   如果返回类似{"error": "Method Not Allowed"}或其它非连接失败的响应，说明MCP服务器HTTP服务是正常的（因为通常GET请求不被允许，POST才是正确的调用方式）。如果连接被拒绝，可能是容器未启动或端口映射错误。
3. 检查客户端配置：
   • 路径错误：检查command中的Python路径和args中的脚本路径是否完全正确。使用which python3和realpath /path/to/mcpproxy.py确认。
   • 权限问题：确保代理脚本mcpproxy.py有可执行权限 (chmod +x /path/to/mcpproxy.py)。
   • 依赖缺失：运行代理脚本可能需要额外的Python包。尝试在宿主机上手动运行它看是否有导入错误：/usr/local/bin/python3 /path/to/mcpproxy.py。根据错误提示安装缺失的包（如pip install mcp）。
4. 查看日志：apple/container的日志可以通过container logs coderunner查看。客户端的日志位置因软件而异（如Claude Desktop可能在开发者控制台）。

6. 项目局限、展望与最佳实践

6.1 当前局限与注意事项

• 平台锁定：最大的限制是仅支持Apple Silicon Mac。对于Windows和Linux用户，需要等待官方基于Firecracker的实现。
• 资源开销：虽然比完整VM轻量，但每个容器仍是一个微型虚拟机，会占用一定的内存和CPU资源。在内存有限的机器上同时运行多个重型任务时需要注意。
• 文件交换：与沙盒交换文件需要通过固定的~/.coderunner/assets/uploads/目录。处理大量或深度嵌套的文件结构时，需要额外的脚本进行同步。
• 网络访问：容器默认可能具有网络访问能力。虽然这有利于安装Python包或访问API，但也意味着AI执行的代码可以对外发起网络请求。这是设计使然，但用户需有意识。

6.2 最佳实践建议

1. 用途分离：为不同的项目或任务创建不同的上传子目录，如uploads/project_a/,uploads/project_b/，避免文件混乱。
2. 技能文档化：为你创建的自定义技能编写清晰详细的SKILL.md。好的文档不仅是给人看的，更是给AI看的，能显著提高AI调用技能的准确率。
3. 敏感信息处理：虽然沙盒隔离了主机，但如果AI代码需要访问API密钥等敏感信息，切勿硬编码在请求中。可以通过让AI读取沙盒内一个预先放置的配置文件（不提交到版本控制）的方式，或者利用客户端的环境变量传递机制（如果支持）。
4. 结合版本控制：将你常用的、稳定的自定义技能脚本和配置文件纳入git管理。~/.coderunner/assets/skills/user/目录就是一个很好的本地仓库。
5. 性能监控：对于长时间运行的计算任务，可以通过让AI执行简单的系统监控命令（如容器内的ps aux,top）来观察资源使用情况。

CodeRunner代表了一种重要的范式转变：AI不再只是一个聊天或生成文本的伙伴，而是一个可以安全、可控地在我们数字环境中行动的智能体。通过将强大的大模型与一个坚不可摧的本地沙盒结合，它为我们打开了一扇新的大门，让我们能够以之前难以想象的方式，将AI的创造力应用于实际的、本地的自动化任务中。随着MCP协议的普及和更多客户端的支持，这种“安全屋”模式很可能成为未来AI应用开发的标配。