/ 目录 / 演练场 / CodeRunner
● 社区 instavm ⚡ 即开即用

CodeRunner

作者 instavm · instavm/coderunner

为 agent 提供 VM 级隔离的代码执行环境——Python、Playwright、持久化 Jupyter 内核,全部沙箱隔离,与宿主机无关。

CodeRunner 为 Claude(及其他 agent)提供安全的持久化沙箱:运行带长生命周期 Jupyter 内核的 Python、使用 Playwright 爬取网页、处理 PDF 和图片。基于容器的 VM 级隔离意味着你可以让 agent 执行不受信任的代码,而不会破坏你的机器。以 MCP 服务器形式暴露,可接入任何客户端。

为什么要用

核心特性

实时演示

实际使用效果

就绪

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "coderunner-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/instavm/coderunner",
        "~/.claude/skills/coderunner"
      ],
      "_inferred": true
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "coderunner-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/instavm/coderunner",
        "~/.claude/skills/coderunner"
      ],
      "_inferred": true
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "coderunner-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/instavm/coderunner",
        "~/.claude/skills/coderunner"
      ],
      "_inferred": true
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标,然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "coderunner-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/instavm/coderunner",
        "~/.claude/skills/coderunner"
      ],
      "_inferred": true
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "coderunner-skill",
      "command": "git",
      "args": [
        "clone",
        "https://github.com/instavm/coderunner",
        "~/.claude/skills/coderunner"
      ]
    }
  ]
}

Continue 使用服务器对象数组,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "coderunner-skill": {
      "command": {
        "path": "git",
        "args": [
          "clone",
          "https://github.com/instavm/coderunner",
          "~/.claude/skills/coderunner"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add coderunner-skill -- git clone https://github.com/instavm/coderunner ~/.claude/skills/coderunner

一行命令搞定。用 claude mcp list 验证,claude mcp remove 卸载。

使用场景

实战用法: CodeRunner

让 Claude 运行不受信任的代码,同时保护你的笔记本

👤 试验自动生成代码的开发者 ⏱ ~15 min intermediate

何时使用: 你想让 Claude 编写并运行一个你还没完全审查的脚本。

前置条件
  • macOS Apple Silicon + Python 3.10+ — 当前限制;Linux 支持情况不一
  • Skill 已安装 — 按项目 README 执行 git clone + ./install.sh
步骤
  1. 交给它任务
    Use coderunner. Write a Python script that downloads my Strava activities CSV from <url>, parses, and computes weekly mileage. Run it in the sandbox.✓ 已复制
    → 脚本已执行;输出已显示;我的文件系统未被触碰
  2. 迭代
    Add a chart of weekly mileage. Re-run.✓ 已复制
    → 图表已渲染;内核状态已保留(无需重新导入)
  3. 导出结果
    Save CSV + chart to ./out/ on host (this only).✓ 已复制
    → 只有该路径被写入;沙箱保持密封

结果: 快速试验,不用担心「哎不对,它把 /Users 删了」。

注意事项
  • 沙箱内仍然允许访问网络 — 运行真正不受信任的代码时禁用网络;否则它可能泄露数据
搭配使用: filesystem

与 Claude 进行持久化数据分析

👤 将 Claude 用作 Jupyter 副驾的分析师 ⏱ ~30 min beginner

何时使用: 你想进行一次 30 分钟的探索性数据分析,且不希望丢失内核状态。

步骤
  1. 一次性加载数据
    Use coderunner. Load /data/sales.csv into df. Show schema + 5 sample rows.✓ 已复制
    → df 在内核中;会话期间持续保留
  2. 即席查询
    Pivot by region × month, show top 5 anomalies.✓ 已复制
    → 透视表 + 标记的异常行
  3. 导出
    Save the anomalies subset to /out/anomalies.csv on host.✓ 已复制
    → /out/ 中有 CSV 文件

结果: 通过对话进行笔记本级别的分析,且代码实际运行。

注意事项
  • 长时间会话中内核状态漂移;结果基于过时变量 — 不相关任务之间重启内核;Claude 可以执行 %reset
搭配使用: filesystem

安全地爬取 JS 重度网站

👤 需要从 SPA 一次性提取数据的开发者 ⏱ ~20 min intermediate

何时使用: 网站需要完整浏览器;你不想在宿主机上运行 Chrome 进程。

步骤
  1. 启动会话
    Use coderunner Playwright. Open <url>, wait for the table, extract rows as JSON.✓ 已复制
    → 返回 JSON;浏览器保持在沙箱中
  2. 调整选择器
    Selector missed the price column; adjust to find it.✓ 已复制
    → 选择器已更新;数据完整

结果: 数据已提取;宿主机上没有浏览器痕迹。

注意事项
  • 网站检测到 headless 浏览器并拦截 — 切换到技能暴露的 chromium stealth 选项

组合

与其他 MCP 搭配,撬动十倍杠杆

coderunner-skill + filesystem

仅通过挂载路径在沙箱和宿主机之间传输数据

Mount only /Users/me/data and /Users/me/out; everything else is read-only.✓ 已复制
coderunner-skill + duckduckgo-mcp

搜索 → 抓取 → 分析的完整流程

Search via duckduckgo, scrape via coderunner Playwright, analyze in Python.✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
run_python code: str 任何代码执行 0
browser_navigate url, wait_for? Playwright 会话,用于 SPA 爬取 0
browser_extract selector, format 导航后提取数据 0
pdf_ops input_path, op, args PDF 合并 / 拆分 / 提取 0
image_ops input_path, op, args 缩放、格式转换、OCR 0
kernel_reset 不相关任务之间 0

成本与限制

运行它的成本

API 配额
无——本地
每次调用 Token 数
只有代码/输出的 token
费用
免费
提示
持久内核省去重复导入的 token;只在状态出错时重置

安全

权限、密钥、影响范围

最小权限: Mounted filesystem paths only Network on/off via config
凭据存储: 不要把 secret 放进沙箱,除非你接受 agent 看到它们
数据出站: 如果网络开启,沙箱可访问任意 URL——敏感运行时请禁用网络
切勿授予: 不要挂载 $HOME 或 /——这样沙箱就失去了意义

故障排查

常见错误与修复

install.sh 在 Linux 上失败

项目以 macOS Apple Silicon 为一等目标;Linux 支持不稳定。查看 issue 获取特定发行版的说明

Playwright 状态过期

运行 kernel_reset;旧的浏览器上下文可能跨调用持续存在

沙箱无法访问网络

配置中网络已禁用;需要时启用。反之,不需要时隔离

PDF/图片技能缺少依赖

容器镜像捆绑了常用依赖;重建镜像以添加自定义依赖

替代方案

CodeRunner 对比其他方案

替代方案何时用它替代权衡
Anthropic code execution beta你想要服务端执行,无需本地沙箱云端执行;数据离开你的机器
Docker by hand你想完全控制容器镜像手动配置;没有开箱即用的 MCP 服务器

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills