CodeRunner 帮助你将 AI 智能体及其操作沙箱化,使其在沙箱内运行。
主要用例: 在沙箱中运行 AI 智能体代码,并显式选择主机挂载和网络访问权限。隔离可降低风险;但它并不能防止所有数据丢失或数据外泄。
我们已推出面向智能体的云端托管虚拟机——InstaVM - 为 AI 智能体提供即时计算机
前提条件: 搭载 macOS 和 Apple Silicon(M1/M2/M3/M4)的 Mac,Python 3.10+
安装程序会在 ~/.coderunner/api-token 中生成沙箱令牌(或保存你导出的
CODERUNNER_API_TOKEN)。客户端以
Authorization: Bearer <token> 的形式发送该令牌;cat ~/.coderunner/api-token 可将其打印出来。只有
GET /health 是公开的,令牌缺失或强度不足时会默认拒绝访问。当未设置该变量时,
Claude Desktop 代理和示例会从该文件中读取令牌。参见身份验证与网络边界。
git clone https://github.com/instavm/coderunner.git
cd coderunner
chmod +x install.sh
./install.sh
完成后停止沙箱:
container stop coderunner
稍后恢复同一沙箱,保留其文件系统。Python 内核状态是易失的,在 VM 或服务器重启后不会保留:
container start coderunner
要重新开始一个干净的沙箱,请删除容器并再次运行安装程序:
container delete coderunner && ./install.sh
CPU 和内存限制可通过安装程序选项或 CODERUNNER_CPUS 和 CODERUNNER_MEMORY 环境变量进行设置:
./install.sh --cpus 4 --memory 8g
其他主机目录必须挂载到 /workspace 下。它们默认是只读的;仅当沙箱需要写入主机时才添加 :rw:
./install.sh \
--mount "$HOME/projects/api:/workspace/api" \
--mount "$HOME/projects/output:/workspace/output:rw"
额外挂载默认无。资源与挂载设置在容器创建时即固定;如需更改,请先删除容器。
默认情况下,沙箱中运行的代码具有不受限制的网络访问权限。要使其在无互联网访问的仅主机网络上运行:
CODERUNNER_NETWORK=none ./install.sh
在此模式下,MCP 服务器可通过 http://127.0.0.1:8222/mcp 访问。该设置在创建容器时即固定;安装程序拒绝恢复使用不同网络模式的容器。
Claude Code 以你的身份在你的机器上运行命令,权限提示是唯一的边界。将其指向 CodeRunner 的工具后,它编写的代码将在虚拟机中运行:无论收到什么指令,它只能访问你挂载到 /workspace 下的文件夹、你允许的网络以及沙箱自身的文件系统。对于处理不可信输入的代码,或你不会手动运行的代码,以及多个不得共享状态的代理(命名会话),请使用沙箱。它无法保护你以读写方式挂载的任何内容。
./install.sh(如果尚未执行)
container exec -it coderunner /bin/bash
root@coderunner:/app# npm install -g @anthropic-ai/claude-code
MCP 服务器将可通过以下地址访问:http://coderunner.local:8222/mcp
安装程序会为 Claude Desktop 代理创建 ~/.coderunner/venv。对于其他 Python 示例,请在你自己的 virtualenv 中安装其依赖项:
pip install -r examples/requirements.txt



复制示例配置:
cd examples
cp claude_desktop/claude_desktop_config.example.json claude_desktop/claude_desktop_config.json
编辑配置文件并替换占位符路径:
/path/to/your/python 替换为 $HOME/.coderunner/venv/bin/python,使用你主目录的完整路径/path/to/coderunner 替换为你克隆仓库的实际路径编辑后的示例:
{
"mcpServers": {
"coderunner": {
"command": "/Users/yourname/.coderunner/venv/bin/python",
"args": ["/Users/yourname/coderunner/examples/claude_desktop/mcpproxy.py"]
}
}
}
更新 Claude Desktop 配置:
在 Claude 中开始使用 CodeRunner: Claude 现在编写的代码会在沙箱中运行。
如果该工具在聊天工具菜单中显示为“Disabled”,尽管服务器已列为正在运行:请完全退出 Claude
Desktop(Cmd-Q)并重新打开,确保 command 是安装程序打印的 venv python(它
包含 fastmcp),并查看 ~/Library/Logs/Claude/mcp-server-coderunner.log 以获取代理的错误信息。该代理
需要沙箱正在运行(container list)以及令牌文件 ~/.coderunner/api-token。
快速开始:
# 1. Install and start CodeRunner (one-time setup; run as yourself, it asks for sudo when it needs it)
git clone https://github.com/instavm/coderunner.git
cd coderunner
./install.sh
# 2. Add the sandbox with its token (the installer prints this command)
claude mcp add --transport http coderunner http://coderunner.local:8222/mcp \
--header "Authorization: Bearer $(cat ~/.coderunner/api-token)"
# 3. Reconnect to MCP servers
/mcp
Claude Code 插件(claude plugin marketplace add https://github.com/instavm/coderunner-plugin)早于该令牌出现,在发送相同请求头之前会返回 401;在插件更新之前,请使用上面的命令。
安装步骤:
导航到插件市场:

添加 InstaVM 仓库:

使用 Claude Code 执行 Python 代码:

就是这样!Claude Code 现在可以访问所有 CodeRunner 工具:
将返回的 session_id 传递给 execute_python_code,以在代理之间保持状态隔离。最多可以同时运行五个命名会话。
了解更多: 请参阅插件仓库获取详细文档。

创建或编辑 ~/.config/opencode/opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"coderunner": {
"type": "remote",
"url": "http://coderunner.local:8222/mcp",
"headers": { "Authorization": "Bearer <contents of ~/.coderunner/api-token>" },
"enabled": true
}
}
}
保存配置后:

设置你的 OpenAI API 密钥:
export OPENAI_API_KEY="your-openai-api-key-here"
运行客户端:
python examples/openai_agents/openai_client.py
开始编写代码: 输入类似“write python code to generate 100 prime numbers”的提示词,然后观察它在沙箱中安全执行!
Gemini CLI 是 Google 最近推出的。
{
"theme": "Default",
"selectedAuthType": "oauth-personal",
"mcpServers": {
"coderunner": {
"httpUrl": "http://coderunner.local:8222/mcp",
"headers": { "Authorization": "Bearer <contents of ~/.coderunner/api-token>" }
}
}
}


Kiro 是 Amazon 最近推出的。