CodeRunner：面向 AI 代理的本地沙箱

CodeRunner 帮助你将 AI 代理及其操作安全地隔离在沙箱中。

关键用例： 你可以在我们的沙箱中运行多个 Claude Code 或 AI 代理，无需担心数据丢失和外泄。

快速开始

前置要求： Mac（macOS 和 Apple Silicon (M1/M2/M3/M4)），Python 3.10+

git clone https://github.com/instavm/coderunner.git
cd coderunner
chmod +x install.sh
./install.sh

停止与恢复

完成后停止沙箱：

container stop coderunner

稍后恢复同一个沙箱，上传文件、内核和已安装的软件包都会保留：

container start coderunner

如需用全新沙箱重新开始，请删除容器并重新运行安装程序：

container delete coderunner && ./install.sh

在沙箱中运行 Claude Code

./install.sh（如果尚未完成）

container exec -it coderunner /bin/bash

root@coderunner:/app# npm install -g @anthropic-ai/claude-code

其他集成方式

MCP 服务器将在以下地址可用：http://coderunner.local:8222/mcp

安装所需软件包（使用 virtualenv 并注意 python 路径）：

pip install -r examples/requirements.txt

1. Claude Desktop 集成

配置 Claude Desktop，将 CodeRunner 用作 MCP 服务器：

demo1

demo2

demo4

复制示例配置：

cd examples
cp claude_desktop/claude_desktop_config.example.json claude_desktop/claude_desktop_config.json

编辑配置文件并替换占位符路径：
- 将 /path/to/your/python 替换为你的实际 Python 路径（例如 /usr/bin/python3 或 /opt/homebrew/bin/python3）
- 将 /path/to/coderunner 替换为你克隆仓库的实际路径
编辑后的示例：
```
{
  "mcpServers": {
    "coderunner": {
      "command": "/opt/homebrew/bin/python3",
      "args": ["/Users/yourname/coderunner/examples/claude_desktop/mcpproxy.py"]
    }
  }
}
```
更新 Claude Desktop 配置：
- 打开 Claude Desktop

2. Claude Code CLI

通过 Claude Code CLI 使用 CodeRunner，获得基于终端的 AI 辅助：

快速开始：

# 1. Install and start CodeRunner (one-time setup)
git clone https://github.com/instavm/coderunner.git
cd coderunner
sudo ./install.sh

# 2. Install the Claude Code plugin
claude plugin marketplace add https://github.com/instavm/coderunner-plugin
claude plugin install instavm-coderunner

# 3. Reconnect to MCP servers
/mcp

安装步骤：

进入插件市场：
添加 InstaVM 仓库：
使用 Claude Code 执行 Python 代码：

就这样！Claude Code 现在可以使用所有 CodeRunner 工具：

execute_python_code - 在持久化的 Jupyter 内核中运行 Python 代码
navigate_and_get_all_visible_text - 使用 Playwright 进行网页抓取
list_skills - 列出可用技能（docx、xlsx、pptx、pdf、图像处理等）
get_skill_info - 获取特定技能的文档
get_skill_file - 读取技能文件和示例

了解更多： 有关详细文档，请参阅插件仓库。

3. OpenCode 配置

配置 OpenCode，将 CodeRunner 用作 MCP 服务器：

OpenCode 示例

创建或编辑 ~/.config/opencode/opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "coderunner": {
      "type": "remote",
      "url": "http://coderunner.local:8222/mcp",
      "enabled": true
    }
  }
}

保存配置后：

重启 OpenCode
CodeRunner 工具将自动可用
开始执行 Python 代码，并完全访问沙箱环境

4. Python OpenAI Agents

将 CodeRunner 与 OpenAI 的 Python agents 库一起使用：

demo3

设置你的 OpenAI API 密钥：

export OPENAI_API_KEY="your-openai-api-key-here"

运行客户端：

python examples/openai_agents/openai_client.py

开始编码： 输入类似“写一段 Python 代码生成 100 个质数”的提示词，然后看着它在沙箱中安全执行！

5. Gemini-CLI

Gemini CLI 是 Google 最近推出的工具。

~/.gemini/settings.json

{
  "theme": "Default",
  "selectedAuthType": "oauth-personal",
  "mcpServers": {
    "coderunner": {
      "httpUrl": "http://coderunner.local:8222/mcp"
    }
  }
}

gemini1

gemini2

6. Kiro（Amazon 出品）

Kiro 是 Amazon 最近推出的产品。

~/.kiro/settings/mcp.json

{
  "mcpServers": {
    "coderunner": {
      "command": "/path/to/venv/bin/python",
      "args": [
        "/path/to/coderunner/examples/claude_desktop/mcpproxy.py"
      ],
      "disabled": false,
      "autoApprove": [
        "execute_python_code"
      ]
    }
  }
}

kiro

7. Coderunner-UI（离线 AI 工作区）

Coderunner-UI 是我们自有的离线 AI 工作区工具，专为完全隐私和本地处理而设计。

coderunner-ui

安全性

代码在具有虚拟机级隔离的独立容器中运行。你的主机系统和沙箱之外的文件仍受到保护。

来自 @apple/container：

每个容器都具有完整 VM 的隔离特性，使用最少的核心工具和动态库来降低资源占用和攻击面。

技能系统

CodeRunner 内置技能系统，为常见任务提供预打包工具。技能分为两类：

内置公共技能

以下技能包含在每次 CodeRunner 安装中：

pdf-text-replace - 替换可填写 PDF 表单中的文本
image-crop-rotate - 裁剪和旋转图像

使用技能

技能通过 MCP 工具访问：

# List all available skills
result = await list_skills()

# Get documentation for a specific skill
info = await get_skill_info("pdf-text-replace")

# Execute a skill's script
code = """
import subprocess
subprocess.run([
    'python',
    '/app/uploads/skills/public/pdf-text-replace/scripts/replace_text_in_pdf.py',
    '/app/uploads/input.pdf',
    'OLD TEXT',
    'NEW TEXT',
    '/app/uploads/output.pdf'
])
"""
result = await execute_python_code(code)

添加自定义技能

用户可以将自己的技能添加到 ~/.coderunner/assets/skills/user/ 目录：

为你的技能创建一个目录（例如 my-custom-skill/）
添加包含文档的 SKILL.md 文件
在 scripts/ 子目录中添加你的脚本
技能将被 list_skills() 工具自动发现

技能结构：

~/.coderunner/assets/skills/user/my-custom-skill/
├── SKILL.md              # Documentation with usage examples
└── scripts/              # Your Python/bash scripts
    └── process.py

示例：使用 PDF 文本替换技能

# Inside the container, execute:
python /app/uploads/skills/public/pdf-text-replace/scripts/replace_text_in_pdf.py \
    /app/uploads/tax_form.pdf \
    "John Doe" \
    "Jane Smith" \
    /app/uploads/tax_form_updated.pdf

架构

CodeRunner 由以下部分组成：

沙箱容器： 带 Jupyter 内核的隔离执行环境
MCP 服务器： 处理 AI 模型与沙箱之间的通信
技能系统： 面向常见任务的预打包工具（PDF 处理、图像处理等）

示例

examples/ 目录包含：

openai-agents - OpenAI agents 集成示例
claude-desktop - Claude Desktop 集成示例

构建容器镜像教程

https://github.com/apple/container/blob/main/docs/tutorial.md

路线图

借助 Firecracker 提供 Linux 支持
为外部代理操作设置护栏
Coderunner 的 CLI

参与贡献

我们欢迎贡献！请参阅 CONTRIBUTING.md 了解相关指南。

许可证

本项目采用 Apache 2.0 许可证授权 - 有关详细信息，请参阅 LICENSE 文件。

coderunner

最受欢迎