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 SiliconM1/M2/M3/M4芯片的macOS上。这是因为它深度依赖苹果自家的虚拟化框架。项目路线图中提到的Linux支持计划通过Firecracker另一种轻量级虚拟机管理程序来实现但当前版本尚不可用。2.2 MCP协议连接AI大脑与沙盒身体的“神经”有了坚固的“身体”沙盒容器还需要一个高效的“神经系统”来让外部的AI模型大脑控制它。这就是Model Context Protocol的作用。MCP是一种新兴的开放协议旨在标准化AI模型与外部工具、数据源之间的通信。你可以把它看作AI世界的“USB-C”接口。在CodeRunner的上下文中MCP服务器运行在CodeRunner沙盒内部。它暴露了一系列“工具”Tools比如execute_python_code执行Python代码、list_skills列出可用技能等。MCP客户端集成在支持MCP的AI客户端中如Claude Desktop、Claude Code CLI、OpenCode等。通信流程当你在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 环境准备与依赖检查在运行安装脚本前请手动确认以下条件这能避免很多后续问题硬件与操作系统确认你的Mac是Apple SiliconM1, M2, M3, M4芯片并运行较新版本的macOSSonoma或更高版本推荐。Homebrew这是macOS的包管理器几乎必不可少。如果未安装请从 brew.sh 获取安装命令。Python 3.10通过python3 --version检查。如果没有使用brew install python3.11安装。关键点确保pip命令对应的是Python 3的版本有时系统自带的pip可能指向Python 2。使用pip3 --version确认。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应用集成的标准方式。定位配置文件Claude Desktop的MCP服务器配置通常位于~/Library/Application Support/Claude/claude_desktop_config.json。CodeRunner项目提供的examples/claude_desktop/目录中的示例文件是让你参考的模板。关键配置解析你需要编辑的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/你的用户名/替换成你的实际家目录路径。代理脚本的作用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 CLIClaude Code是Anthropic推出的命令行AI编程助手与CodeRunner的集成更为原生和强大。安装CodeRunner插件按照项目说明使用Claude Code的插件市场命令添加。这里有一个易错点确保你的Claude Code CLI已经成功安装并登录。插件安装命令是在Claude Code的交互式会话中执行的而不是在普通终端。交互式安装流程在终端输入claude进入Claude Code交互界面。输入/plugin marketplace add https://github.com/instavm/coderunner-plugin添加仓库。输入/plugin install instavm-coderunner安装插件。安装后输入/mcp reconnect或按照提示重新连接MCP服务器。验证与使用插件安装成功后你可以直接让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想快速进行初步分析。上传文件首先你需要将文件放入CodeRunner沙盒能访问的位置。所有需要处理的文件都应放在~/.coderunner/assets/uploads/目录下。你可以手动复制或者写一个简单的脚本。# 在宿主机终端执行 cp ~/Downloads/sales_data.csv ~/.coderunner/assets/uploads/向AI助手提问在已配置好的Claude Desktop或Claude Code中你可以直接说“请使用CodeRunner读取sales_data.csv文件检查是否有空值并计算每个月的销售总额。数据中有date和amount列。”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, indexFalse) 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]”替换为“甲方某某科技有限公司”。放置文件将contract.pdf放入上传目录。询问AI你可以直接对AI说“请使用CodeRunner的PDF技能将contract.pdf中的‘[COMPANY_NAME]’替换为‘某某科技有限公司’并生成新文件contract_filled.pdf。”幕后调用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 ])获取结果替换完成后新的contract_filled.pdf会生成在沙盒的/app/uploads/目录下对应宿主机的~/.coderunner/assets/uploads/目录你可以从中取出使用。4.3 创建与使用自定义技能这是将个人工作流固化的高级用法。例如你经常需要将一批JPG图片转换为WebP格式并调整大小。创建技能目录结构mkdir -p ~/.coderunner/assets/skills/user/image-converter/ cd ~/.coderunner/assets/skills/user/image-converter/编写技能文档 (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 })编写技能脚本 (scripts/convert.py)#!/usr/bin/env python3 import os import sys from PIL import Image def convert_images(input_dir, output_dir, max_sizeNone): os.makedirs(output_dir, exist_okTrue) 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, quality85) print(fConverted: {filename} - {output_name}) except Exception as e: print(fFailed 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)使用技能现在你可以直接告诉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智能体在沙盒中工作。环境准备在宿主机非容器内创建一个Python虚拟环境并安装必要包。cd /path/to/coderunner/examples python3 -m venv venv source venv/bin/activate pip install -r requirements.txt # 这会安装 openai, mcp 等库 export OPENAI_API_KEYsk-... # 设置你的OpenAI API密钥运行示例客户端examples/openai_agents/openai_client.py这个文件是一个简单的对话循环。运行它python openai_client.py交互示例程序启动后你可以输入自然语言指令。你: 请写一个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 故障排除与连接测试当配置完成后客户端无法连接时可以按以下步骤排查确认容器状态在终端运行container ps查看coderunner容器是否处于Running状态。测试MCP服务器端点在宿主机终端使用curl测试连通性。curl -v http://coderunner.local:8222/mcp如果返回类似{error: Method Not Allowed}或其它非连接失败的响应说明MCP服务器HTTP服务是正常的因为通常GET请求不被允许POST才是正确的调用方式。如果连接被拒绝可能是容器未启动或端口映射错误。检查客户端配置路径错误检查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。查看日志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 最佳实践建议用途分离为不同的项目或任务创建不同的上传子目录如uploads/project_a/,uploads/project_b/避免文件混乱。技能文档化为你创建的自定义技能编写清晰详细的SKILL.md。好的文档不仅是给人看的更是给AI看的能显著提高AI调用技能的准确率。敏感信息处理虽然沙盒隔离了主机但如果AI代码需要访问API密钥等敏感信息切勿硬编码在请求中。可以通过让AI读取沙盒内一个预先放置的配置文件不提交到版本控制的方式或者利用客户端的环境变量传递机制如果支持。结合版本控制将你常用的、稳定的自定义技能脚本和配置文件纳入git管理。~/.coderunner/assets/skills/user/目录就是一个很好的本地仓库。性能监控对于长时间运行的计算任务可以通过让AI执行简单的系统监控命令如容器内的ps aux,top来观察资源使用情况。CodeRunner代表了一种重要的范式转变AI不再只是一个聊天或生成文本的伙伴而是一个可以安全、可控地在我们数字环境中行动的智能体。通过将强大的大模型与一个坚不可摧的本地沙盒结合它为我们打开了一扇新的大门让我们能够以之前难以想象的方式将AI的创造力应用于实际的、本地的自动化任务中。随着MCP协议的普及和更多客户端的支持这种“安全屋”模式很可能成为未来AI应用开发的标配。