{"id":51002861,"url":"https://github.com/BIGPPWONG/EdgeBox","last_synced_at":"2026-07-02T03:00:42.781Z","repository":{"id":315728478,"uuid":"1055435059","full_name":"BIGPPWONG/EdgeBox","owner":"BIGPPWONG","description":"A fully-featured, GUI-powered local LLM Agent sandbox with complete MCP protocol support.   Features both CLI and full desktop environment, enabling AI agents to operate browsers, terminal, and other desktop applications just like humans. Based on E2B oss code.","archived":false,"fork":false,"pushed_at":"2026-04-22T08:41:42.000Z","size":27816,"stargazers_count":198,"open_issues_count":2,"forks_count":26,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-05-05T10:05:25.853Z","etag":null,"topics":["code-interpreter","computer-use","e2b","llm-agent","llm-sandbox","mcp"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BIGPPWONG.png","metadata":{"files":{"readme":"README-zh.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-12T09:05:04.000Z","updated_at":"2026-05-01T21:50:04.000Z","dependencies_parsed_at":"2025-09-20T11:31:06.566Z","dependency_job_id":"c0d5468d-30b0-46ac-a4c1-079abdbeb8a2","html_url":"https://github.com/BIGPPWONG/EdgeBox","commit_stats":null,"previous_names":["bigppwong/edgebox"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/BIGPPWONG/EdgeBox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BIGPPWONG%2FEdgeBox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BIGPPWONG%2FEdgeBox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BIGPPWONG%2FEdgeBox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BIGPPWONG%2FEdgeBox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BIGPPWONG","download_url":"https://codeload.github.com/BIGPPWONG/EdgeBox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BIGPPWONG%2FEdgeBox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35030921,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-02T02:00:06.368Z","response_time":173,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["code-interpreter","computer-use","e2b","llm-agent","llm-sandbox","mcp"],"created_at":"2026-06-20T17:00:21.336Z","updated_at":"2026-07-02T03:00:42.774Z","avatar_url":"https://github.com/BIGPPWONG.png","language":"TypeScript","funding_links":[],"categories":["Detailed Sandboxes Reference","Sandbox and Containerization"],"sub_categories":["Standalone / Self-Hosted Tools"],"readme":"# EdgeBox - AI 智能体的本地桌面沙箱\n\n[![Release](https://github.com/BIGPPWONG/EdgeBox/actions/workflows/release.yml/badge.svg?branch=main)](https://github.com/BIGPPWONG/EdgeBox/actions/workflows/release.yml)\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"assets/icon/icon.png\" alt=\"EdgeBox Logo\" width=\"128\" height=\"128\" /\u003e\n  \u003cbr/\u003e\n  \u003cstrong\u003e一个功能齐全、支持图形界面的本地大语言模型智能体沙箱，完全支持 MCP 协议。\u003c/strong\u003e\n  \u003cbr/\u003e\n  \u003cp\u003e为您的大语言模型（LLM）赋予真正的\"计算机使用\"能力。\u003c/p\u003e\n\u003c/div\u003e\n\n---\n\n**EdgeBox** 是一个强大的桌面应用程序，它将 E2B (e2b.dev) 基于云的沙箱功能带到您的本地机器。基于开源的 E2B 代码解释器项目，EdgeBox 将沙箱转变为本地运行的环境，让您完全控制 AI 智能体的开发和执行环境。\n\n**EdgeBox 的独特之处**：虽然大多数开源沙箱项目只提供终端/命令行界面，但 EdgeBox 同时提供了**命令行 Shell** 和**完整的图形化（GUI）桌面环境**（通过集成的 VNC 查看器）。这意味着您的 LLM 智能体不再只是代码执行器，而是一个能够操作浏览器、使用 VS Code 和与桌面应用程序交互的数字工作者，就像人类一样。\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"assets/screenshots/main-app.png\" alt=\"EdgeBox 主应用程序\" width=\"800\" /\u003e\n  \u003cp\u003e\u003cem\u003eEdgeBox 主应用程序仪表板\u003c/em\u003e\u003c/p\u003e\n\u003c/div\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"assets/screenshots/computer-use.gif\" alt=\"计算机使用演示\" width=\"800\" /\u003e\n  \u003cp\u003e\u003cem\u003e计算机使用演示：输入\"google.com\"，按回车，并截取屏幕截图 - 展示计算机使用能力。\u003c/em\u003e\u003c/p\u003e\n\u003c/div\u003e\n\n## 🤔 为什么选择 EdgeBox？\n\n| 功能特性     |           EdgeBox            | 其他开源沙箱（如 `codebox`） |\n| :----------- | :--------------------------: | :--------------------------: |\n| **环境**     |          🖥️ **本地**          |            🖥️ 本地            |\n| **界面**     |          GUI + CLI           |            仅 CLI            |\n| **能力**     | **计算机使用** 和 代码解释器 |          代码解释器          |\n| **数据隐私** |       ✅ **100% 私有**        |         ✅ 100% 私有          |\n| **延迟**     |         ⚡️ **接近零**         |           ⚡️ 接近零           |\n| **集成**     |        ✅ **MCP 兼容**        |           专有 API           |\n\n## 📖 目录\n\n- [EdgeBox - AI 智能体的本地桌面沙箱](#edgebox---ai-智能体的本地桌面沙箱)\n  - [🤔 为什么选择 EdgeBox？](#-为什么选择-edgebox)\n  - [📖 目录](#-目录)\n  - [🚀 核心功能](#-核心功能)\n    - [1. 💻 完整桌面环境（计算机使用）](#1--完整桌面环境计算机使用)\n    - [2. 🐚 完整的代码解释器 \\\u0026 Shell](#2--完整的代码解释器--shell)\n    - [3. 🔗 无缝的 LLM 智能体集成（通过 MCP）](#3--无缝的-llm-智能体集成通过-mcp)\n  - [🛠️ 可用的 MCP 工具](#️-可用的-mcp-工具)\n    - [📟 核心工具（CLI 模式 - 始终可用）](#-核心工具cli-模式---始终可用)\n    - [🖱️ 桌面工具（GUI 模式 - 启用 GUI 工具时可用）](#️-桌面工具gui-模式---启用-gui-工具时可用)\n  - [🏗️ 架构](#️-架构)\n  - [📋 前置要求](#-前置要求)\n  - [🛠️ 安装](#️-安装)\n  - [🎯 使用方法](#-使用方法)\n    - [快速开始](#快速开始)\n    - [MCP 客户端配置](#mcp-客户端配置)\n    - [指导您的 LLM 智能体](#指导您的-llm-智能体)\n    - [多会话并发沙箱](#多会话并发沙箱)\n    - [编程访问（SDK 示例）](#编程访问sdk-示例)\n  - [🔐 安全性](#-安全性)\n  - [📄 许可证](#-许可证)\n  - [🙏 致谢](#-致谢)\n  - [🔗 相关项目](#-相关项目)\n  - [📞 支持](#-支持)\n\n## 🚀 核心功能\n\nEdgeBox 通过 MCP 协议暴露其所有功能，为您的 LLM 智能体组织为三个核心模块。\n\n### 1. 💻 完整桌面环境（计算机使用）\n- **VNC 远程桌面**：访问一个完整的、交互式的 Ubuntu 桌面环境。\n- **预装应用程序**：开箱即用地附带 Google Chrome、VS Code 和其他基本工具。\n- **GUI 自动化**：您的智能体可以通过编程方式控制鼠标和键盘来与任何桌面应用程序交互。\n- **视觉感知**：内置的屏幕截图功能为智能体提供视觉上下文，使其能够\"看到\"并对 GUI 做出反应。\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"assets/screenshots/vnc.gif\" alt=\"VNC 桌面环境演示\" width=\"800\" /\u003e\n  \u003cp\u003e\u003cem\u003e带有 VS Code 和浏览器的交互式 VNC 会话。\u003c/em\u003e\u003c/p\u003e\n\u003c/div\u003e\n\n### 2. 🐚 完整的代码解释器 \u0026 Shell\n- **安全的代码执行**：在隔离的 Docker 容器中安全地运行 AI 生成的代码。\n- **完整 Shell 访问**：功能齐全的 `bash` 终端允许执行任何 Linux 命令。\n- **隔离的文件系统**：每个会话都有独立的文件系统，完全支持创建、读取、写入和删除文件。\n- **多语言支持**：原生支持 Python、JavaScript (Node.js) 和其他运行时。\n\n### 3. 🔗 无缝的 LLM 智能体集成（通过 MCP）\n- **标准化协议**：所有沙箱功能都通过 **MCP（模型上下文协议）** HTTP 接口暴露。\n- **广泛的客户端兼容性**：轻松连接到任何支持 MCP 的 LLM 客户端，如 Claude Desktop、OpenWebUI、LobeChat 等。\n- **多会话管理**：使用 `x-session-id` 头创建和管理多个隔离的沙箱会话。\n\n## 🛠️ 可用的 MCP 工具\n\nEdgeBox 通过 MCP 工具展示其能力，分为两类：\n\n### 📟 核心工具（CLI 模式 - 始终可用）\n\n**代码执行工具** - 在各种语言中执行代码：\n- `execute_python` - 在隔离环境中执行 Python 代码\n- `execute_typescript` - 执行 TypeScript/JavaScript 代码\n- `execute_r` - 执行 R 代码进行统计分析\n- `execute_java` - 执行 Java 代码\n- `execute_bash` - 执行 Bash 脚本\n\n**Shell 命令** - 与 Linux 环境交互：\n- `shell_run` - 运行 Shell 命令（有状态的、持久化环境）\n- `shell_run_background` - 在后台运行命令并进行进程管理\n\n**文件系统操作** - 管理文件和目录：\n- `fs_list` - 列出目录中的文件\n- `fs_read` - 读取文件内容\n- `fs_write` - 将内容写入文件\n- `fs_info` - 获取文件元数据和信息\n- `fs_watch` - 实时监控目录变化\n\n### 🖱️ 桌面工具（GUI 模式 - 启用 GUI 工具时可用）\n\n**鼠标控制** - 程序化鼠标交互：\n- `desktop_mouse_click` - 执行鼠标点击（左键/右键/中键）\n- `desktop_mouse_double_click` - 双击操作\n- `desktop_mouse_move` - 将光标移动到坐标位置\n- `desktop_mouse_scroll` - 以可配置数量向上/向下滚动\n- `desktop_mouse_drag` - 从一个位置拖动到另一个位置\n\n**键盘控制** - 文本输入和按键组合：\n- `desktop_keyboard_type` - 输入文本，支持非 ASCII 字符的剪贴板\n- `desktop_keyboard_press` - 按特定键（Return、Escape、Tab 等）\n- `desktop_keyboard_combo` - 执行按键组合（Ctrl+C、Alt+Tab 等）\n\n**窗口管理** - 控制桌面应用程序：\n- `desktop_get_windows` - 列出所有窗口及其标题和 ID\n- `desktop_switch_window` - 聚焦特定窗口\n- `desktop_maximize_window` - 最大化窗口\n- `desktop_minimize_window` - 最小化窗口\n- `desktop_resize_window` - 将窗口调整为特定尺寸\n\n**视觉和应用程序控制**：\n- `desktop_screenshot` - 捕获桌面屏幕截图（PNG 格式）\n- `desktop_launch_app` - 按名称启动应用程序\n- `desktop_wait` - 在操作之间添加延迟\n\n\u003e **注意**：桌面工具仅在 EdgeBox 设置中启用 GUI 工具时可用。无论 GUI 设置如何，核心工具始终可用。\n\n## 🏗️ 架构\n\nEdgeBox 旨在为 LLM 智能体提供无缝且强大的本地执行环境。\n\n**[LLM 智能体（Claude、GPT 等）]** `\u003c- MCP (HTTP 流) -\u003e` **[EdgeBox 应用]** `\u003c- Docker API -\u003e` **[隔离的沙箱容器（桌面 + Shell）]**\n\n- **前端**：Electron + React + TypeScript + Tailwind CSS\n- **后端**：Node.js + Dockerode（用于 Docker API）\n- **容器化**：Docker\n- **UI 组件**：Radix UI\n\n## 📋 前置要求\n\n- **Docker Desktop**：必须安装并运行。\n\n## 🛠️ 安装\n\n1. **下载 EdgeBox**\n   从 [发布页面](https://github.com/BIGPPWONG/edgebox/releases) 下载您平台的最新版本。\n\n2. **安装并运行 Docker Desktop**\n   在启动 EdgeBox 之前，请确保 Docker Desktop 已安装并运行。\n\n3. **运行 EdgeBox**\n   - **Windows**：运行 `EdgeBox.exe`\n   - **macOS**：打开 `EdgeBox.app`\n   - **Linux**：运行 AppImage 或安装 `.deb`/`.rpm` 包。\n\n## 🎯 使用方法\n\n### 快速开始\n1. 启动 EdgeBox 并确保 Docker 正在运行。\n2. 检查仪表板以验证所有组件（Docker、MCP 服务器）是否正常运行。\n3. 将 EdgeBox MCP 配置添加到您的 LLM 客户端。\n\n### MCP 客户端配置\n\n将 EdgeBox 添加到您的 LLM 客户端配置：\n\n```json\n{\n  \"mcpServers\": {\n    \"edgebox\": {\n      \"url\": \"http://localhost:8888/mcp\"\n    }\n  }\n}\n```\n\n### 指导您的 LLM 智能体\n\n配置完成后，您可以向 LLM 智能体发出自然语言指令，例如：\n\n  - **代码执行**：*\"编写一个 Python 脚本分析这个 CSV 文件并向我显示输出。\"*\n  - **文件操作**：*\"创建一个名为 'project' 的新文件夹，在其中创建一个名为 `main.py` 的文件。\"*\n  - **计算机使用**：*\"打开浏览器，导航到 'github.com'，搜索 'EdgeBox'，然后为我截取屏幕截图。\"*\n\n### 多会话并发沙箱\n\n通过在 MCP 请求头中指定 `x-session-id` 来轻松管理多个隔离环境。\n\n**不同任务的示例配置**：\n\n```json\n{\n  \"mcpServers\": {\n    \"edgebox-default\": {\n      \"url\": \"http://localhost:8888/mcp\"\n    },\n    \"edgebox-data-analysis\": {\n      \"url\": \"http://localhost:8888/mcp\",\n      \"headers\": {\n        \"x-session-id\": \"data-analysis\"\n      }\n    },\n    \"edgebox-web-scraping\": {\n      \"url\": \"http://localhost:8888/mcp\",\n      \"headers\": {\n        \"x-session-id\": \"web-scraping\"\n      }\n    }\n  }\n}\n```\n\n### 编程访问（SDK 示例）\n\n您可以通过代码编程方式连接到 EdgeBox 的 MCP 服务器。以下是 Python 和 TypeScript 的快速入门示例。\n\n#### Python 快速入门（FastMCP）\n\n使用 [FastMCP](https://gofastmcp.com/clients/client) 客户端从 Python 连接到 EdgeBox。\n\n**安装：**\n\n```bash\npip install fastmcp\n```\n\n**示例：**\n\n```python\nimport asyncio\nfrom fastmcp import Client\n\nEDGEBOX_MCP_URL = \"http://localhost:8888/mcp\"\n\nasync def main():\n    client = Client(EDGEBOX_MCP_URL)\n\n    async with client:\n        # 列出可用工具\n        tools = await client.list_tools()\n        for tool in tools:\n            print(f\"  - {tool.name}: {tool.description}\")\n\n        # 在沙箱中执行 Python 代码\n        result = await client.call_tool(\n            \"execute_python\",\n            {\"code\": \"import sys; print(f'Hello from EdgeBox! Python {sys.version}')\"},\n        )\n        print(f\"Result: {result}\")\n\n        # 运行 Shell 命令\n        result = await client.call_tool(\n            \"shell_run\",\n            {\"command\": \"uname -a \u0026\u0026 whoami\"},\n        )\n        print(f\"Shell: {result}\")\n\n        # 文件操作\n        await client.call_tool(\n            \"fs_write\",\n            {\"path\": \"/tmp/hello.txt\", \"content\": \"Hello from EdgeBox!\"},\n        )\n        result = await client.call_tool(\"fs_read\", {\"path\": \"/tmp/hello.txt\"})\n        print(f\"File content: {result}\")\n\n        # 在沙箱中执行 TypeScript 代码\n        result = await client.call_tool(\n            \"execute_typescript\",\n            {\"code\": \"console.log(`Node.js ${process.version}`)\"},\n        )\n        print(f\"TypeScript: {result}\")\n\n        # 桌面自动化（需要启用 GUI 工具）\n        # result = await client.call_tool(\"desktop_screenshot\", {})\n        # result = await client.call_tool(\"desktop_keyboard_type\", {\"text\": \"hello\"})\n\nasyncio.run(main())\n```\n\n#### TypeScript 快速入门（fastmcp）\n\n使用 [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk) 客户端（由 [fastmcp](https://github.com/punkpeye/fastmcp) 引用）从 TypeScript 连接到 EdgeBox。\n\n**安装：**\n\n```bash\nnpm install @modelcontextprotocol/sdk fastmcp\n```\n\n**示例：**\n\n```typescript\nimport { Client } from \"@modelcontextprotocol/sdk/client/index.js\";\nimport { StreamableHTTPClientTransport } from \"@modelcontextprotocol/sdk/client/streamableHttp.js\";\n\nconst EDGEBOX_MCP_URL = \"http://localhost:8888/mcp\";\n\nasync function main() {\n  const client = new Client(\n    { name: \"edgebox-quickstart\", version: \"1.0.0\" },\n    { capabilities: {} },\n  );\n\n  const transport = new StreamableHTTPClientTransport(\n    new URL(EDGEBOX_MCP_URL),\n  );\n  await client.connect(transport);\n\n  try {\n    // 列出可用工具\n    const { tools } = await client.listTools();\n    for (const tool of tools) {\n      console.log(`  - ${tool.name}: ${tool.description}`);\n    }\n\n    // 在沙箱中执行 Python 代码\n    const pythonResult = await client.callTool({\n      name: \"execute_python\",\n      arguments: {\n        code: \"import sys; print(f'Hello from EdgeBox! Python {sys.version}')\",\n      },\n    });\n    console.log(\"Result:\", pythonResult.content);\n\n    // 运行 Shell 命令\n    const shellResult = await client.callTool({\n      name: \"shell_run\",\n      arguments: { command: \"uname -a \u0026\u0026 whoami\" },\n    });\n    console.log(\"Shell:\", shellResult.content);\n\n    // 文件操作\n    await client.callTool({\n      name: \"fs_write\",\n      arguments: { path: \"/tmp/hello.txt\", content: \"Hello from EdgeBox!\" },\n    });\n    const readResult = await client.callTool({\n      name: \"fs_read\",\n      arguments: { path: \"/tmp/hello.txt\" },\n    });\n    console.log(\"File content:\", readResult.content);\n\n    // 在沙箱中执行 TypeScript 代码\n    const tsResult = await client.callTool({\n      name: \"execute_typescript\",\n      arguments: { code: \"console.log(`Node.js ${process.version}`)\" },\n    });\n    console.log(\"TypeScript:\", tsResult.content);\n\n    // 桌面自动化（需要启用 GUI 工具）\n    // const screenshot = await client.callTool({ name: \"desktop_screenshot\", arguments: {} });\n    // const typed = await client.callTool({ name: \"desktop_keyboard_type\", arguments: { text: \"hello\" } });\n  } finally {\n    await client.close();\n  }\n}\n\nmain().catch(console.error);\n```\n\n#### 容器管理示例\n\nEdgeBox 提供容器生命周期工具（`container_list`、`container_create`、`container_stop`、`container_restart`、`container_delete`）来编程管理沙箱容器。\n`container_stop` 会结束该 `session_id` 与容器的映射关系，因此一般应将 **`container_stop` 或 `container_delete` 二选一** 作为最终清理步骤（不要对同一个 `session_id` 先 stop 再 delete）。\n\n**Python：**\n\n```python\nimport asyncio\nfrom fastmcp import Client\n\nasync def main():\n    client = Client(\"http://localhost:8888/mcp\")\n\n    async with client:\n        # 创建新容器（60 分钟超时）\n        result = await client.call_tool(\n            \"container_create\",\n            {\"session_id\": \"my-session\", \"timeout\": 60},\n        )\n        print(f\"Create: {result}\")\n\n        # 列出所有活跃容器\n        result = await client.call_tool(\"container_list\", {})\n        print(f\"List: {result}\")\n\n        # 重启容器\n        result = await client.call_tool(\n            \"container_restart\", {\"session_id\": \"my-session\"}\n        )\n        print(f\"Restart: {result}\")\n\n        # 清理方式 A：停止容器\n        result = await client.call_tool(\n            \"container_stop\", {\"session_id\": \"my-session\"}\n        )\n        print(f\"Stop: {result}\")\n\n        # 清理方式 B（替代 stop）：直接删除容器及所有关联数据\n        # 为了演示可重复运行，这里使用不同的 session_id\n        await client.call_tool(\n            \"container_create\",\n            {\"session_id\": \"my-session-delete\", \"timeout\": 60},\n        )\n        result = await client.call_tool(\n            \"container_delete\", {\"session_id\": \"my-session-delete\"}\n        )\n        print(f\"Delete: {result}\")\n\nasyncio.run(main())\n```\n\n**TypeScript：**\n\n```typescript\nimport { Client } from \"@modelcontextprotocol/sdk/client/index.js\";\nimport { StreamableHTTPClientTransport } from \"@modelcontextprotocol/sdk/client/streamableHttp.js\";\n\nasync function main() {\n  const client = new Client(\n    { name: \"edgebox-container-mgmt\", version: \"1.0.0\" },\n    { capabilities: {} },\n  );\n  const transport = new StreamableHTTPClientTransport(\n    new URL(\"http://localhost:8888/mcp\"),\n  );\n  await client.connect(transport);\n\n  try {\n    // 创建新容器（60 分钟超时）\n    const created = await client.callTool({\n      name: \"container_create\",\n      arguments: { session_id: \"my-session\", timeout: 60 },\n    });\n    console.log(\"Create:\", created.content);\n\n    // 列出所有活跃容器\n    const list = await client.callTool({\n      name: \"container_list\",\n      arguments: {},\n    });\n    console.log(\"List:\", list.content);\n\n    // 重启容器\n    const restarted = await client.callTool({\n      name: \"container_restart\",\n      arguments: { session_id: \"my-session\" },\n    });\n    console.log(\"Restart:\", restarted.content);\n\n    // 清理方式 A：停止容器\n    const stopped = await client.callTool({\n      name: \"container_stop\",\n      arguments: { session_id: \"my-session\" },\n    });\n    console.log(\"Stop:\", stopped.content);\n\n    // 清理方式 B（替代 stop）：直接删除容器及所有关联数据\n    // 为了演示可重复运行，这里使用不同的 session_id\n    await client.callTool({\n      name: \"container_create\",\n      arguments: { session_id: \"my-session-delete\", timeout: 60 },\n    });\n    const deleted = await client.callTool({\n      name: \"container_delete\",\n      arguments: { session_id: \"my-session-delete\" },\n    });\n    console.log(\"Delete:\", deleted.content);\n  } finally {\n    await client.close();\n  }\n}\n\nmain().catch(console.error);\n```\n\n#### 会话隔离示例\n\n在 EdgeBox 中，**每个会话（session）对应一个独立的 Docker 容器**，拥有各自隔离的文件系统和运行环境。不传 `x-session-id` 时，所有请求共用同一个 `\"default_session\"` 容器。通过传入不同的 `x-session-id` header，可以并行运行完全隔离的工作负载。\n\n**Python：**\n\n```python\nimport asyncio\nfrom fastmcp import Client\nfrom fastmcp.client.transports import StreamableHttpTransport\n\nasync def run_in_session(session_id: str):\n    \"\"\"每个 session 拥有独立的隔离容器。\"\"\"\n    transport = StreamableHttpTransport(\n        url=\"http://localhost:8888/mcp\",\n        headers={\"x-session-id\": session_id},\n    )\n    client = Client(transport)\n\n    async with client:\n        # 写入文件 - 仅在此 session 的容器内可见\n        await client.call_tool(\n            \"fs_write\",\n            {\"path\": \"/tmp/id.txt\", \"content\": f\"I am {session_id}\"},\n        )\n\n        # 读取文件\n        result = await client.call_tool(\"fs_read\", {\"path\": \"/tmp/id.txt\"})\n        print(f\"[{session_id}] /tmp/id.txt =\u003e {result}\")\n\n        # 在此 session 的容器内运行命令\n        result = await client.call_tool(\n            \"shell_run\", {\"command\": \"hostname\"}\n        )\n        print(f\"[{session_id}] hostname =\u003e {result}\")\n\nasync def main():\n    # 顺序运行，输出更直观（并发场景见下方校验脚本）\n    await run_in_session(\"session-alice\")\n    await run_in_session(\"session-bob\")\n    # session-alice 的 /tmp/id.txt 内容为 \"I am session-alice\"\n    # session-bob 的 /tmp/id.txt 内容为 \"I am session-bob\"\n    # 它们互不干扰。\n\nasyncio.run(main())\n```\n\n**TypeScript：**\n\n```typescript\nimport { Client } from \"@modelcontextprotocol/sdk/client/index.js\";\nimport { StreamableHTTPClientTransport } from \"@modelcontextprotocol/sdk/client/streamableHttp.js\";\n\nasync function runInSession(sessionId: string) {\n  const client = new Client(\n    { name: \"edgebox-session-demo\", version: \"1.0.0\" },\n    { capabilities: {} },\n  );\n  const transport = new StreamableHTTPClientTransport(\n    new URL(\"http://localhost:8888/mcp\"),\n    {\n      requestInit: {\n        headers: { \"x-session-id\": sessionId },\n      },\n    },\n  );\n  await client.connect(transport);\n\n  try {\n    // 写入文件 - 仅在此 session 的容器内可见\n    await client.callTool({\n      name: \"fs_write\",\n      arguments: { path: \"/tmp/id.txt\", content: `I am ${sessionId}` },\n    });\n\n    // 读取文件\n    const read = await client.callTool({\n      name: \"fs_read\",\n      arguments: { path: \"/tmp/id.txt\" },\n    });\n    console.log(`[${sessionId}] /tmp/id.txt =\u003e`, read.content);\n\n    // 在此 session 的容器内运行命令\n    const host = await client.callTool({\n      name: \"shell_run\",\n      arguments: { command: \"hostname\" },\n    });\n    console.log(`[${sessionId}] hostname =\u003e`, host.content);\n  } finally {\n    await client.close();\n  }\n}\n\nasync function main() {\n  // 这两个 session 运行在完全独立的容器中\n  await Promise.all([\n    runInSession(\"session-alice\"),\n    runInSession(\"session-bob\"),\n  ]);\n  // session-alice 的 /tmp/id.txt 内容为 \"I am session-alice\"\n  // session-bob 的 /tmp/id.txt 内容为 \"I am session-bob\"\n  // 它们互不干扰。\n}\n\nmain().catch(console.error);\n```\n\n#### 并发隔离校验（\u003c= 4）\n\n如果你希望在轻量并发下校验会话隔离，建议将并发控制在较低水平（例如 `\u003c= 4`），并验证每个 session 都能读回自己写入的值。\n\n**Python（4 个 session，独立路径）：**\n\n```python\nimport asyncio\nfrom fastmcp import Client\nfrom fastmcp.client.transports import StreamableHttpTransport\n\nURL = \"http://localhost:8888/mcp\"\nSESSIONS = [\"s1\", \"s2\", \"s3\", \"s4\"]\nROUNDS = 20\n\nasync def run_once(session_id: str, round_no: int) -\u003e bool:\n    transport = StreamableHttpTransport(\n        url=URL,\n        headers={\"x-session-id\": session_id},\n    )\n    client = Client(transport)\n\n    path = f\"/tmp/id-{session_id}.txt\"\n    expected = f\"{session_id}-r{round_no}\"\n\n    async with client:\n        await client.call_tool(\"fs_write\", {\"path\": path, \"content\": expected})\n        read = await client.call_tool(\"fs_read\", {\"path\": path})\n        actual = read.content[0].text\n        return actual == expected\n\nasync def main():\n    bad = 0\n    for i in range(1, ROUNDS + 1):\n        results = await asyncio.gather(*[run_once(s, i) for s in SESSIONS])\n        bad += sum(0 if ok else 1 for ok in results)\n    print(f\"BAD={bad}\")\n\nasyncio.run(main())\n```\n\n**TypeScript（4 个 session，独立路径）：**\n\n```typescript\nimport { Client } from \"@modelcontextprotocol/sdk/client/index.js\";\nimport { StreamableHTTPClientTransport } from \"@modelcontextprotocol/sdk/client/streamableHttp.js\";\n\nconst URL = \"http://localhost:8888/mcp\";\nconst SESSIONS = [\"s1\", \"s2\", \"s3\", \"s4\"];\nconst ROUNDS = 20;\n\nasync function runOnce(sessionId: string, roundNo: number): Promise\u003cboolean\u003e {\n  const client = new Client(\n    { name: \"edgebox-isolation-check\", version: \"1.0.0\" },\n    { capabilities: {} },\n  );\n  const transport = new StreamableHTTPClientTransport(new URL(URL), {\n    requestInit: { headers: { \"x-session-id\": sessionId } },\n  });\n  await client.connect(transport);\n\n  const path = `/tmp/id-${sessionId}.txt`;\n  const expected = `${sessionId}-r${roundNo}`;\n\n  try {\n    await client.callTool({\n      name: \"fs_write\",\n      arguments: { path, content: expected },\n    });\n    const read = await client.callTool({\n      name: \"fs_read\",\n      arguments: { path },\n    });\n    const actual = (read.content?.[0] as any)?.text ?? \"\";\n    return actual === expected;\n  } finally {\n    await client.close();\n  }\n}\n\nasync function main() {\n  let bad = 0;\n  for (let i = 1; i \u003c= ROUNDS; i++) {\n    const results = await Promise.all(SESSIONS.map((s) =\u003e runOnce(s, i)));\n    bad += results.filter((ok) =\u003e !ok).length;\n  }\n  console.log(`BAD=${bad}`);\n}\n\nmain().catch(console.error);\n```\n\n## 🔐 安全性\n\n  - **容器隔离**：每个沙箱会话都在单独的 Docker 容器中运行。\n  - **资源限制**：可配置的 CPU 和内存约束可防止资源滥用。\n  - **网络隔离**：容器网络受到控制以保护主机机器。\n\n## 📄 许可证\n\n详细信息请参见 [LICENSE](https://www.google.com/search?q=LICENSE) 文件。\n\n## 🙏 致谢\n\n  - **E2B 团队**：创造了启发了 EdgeBox 的精彩开源 E2B 代码解释器项目。\n  - **Docker**：提供强大的容器化技术。\n  - **Electron**：使跨平台桌面应用成为可能。\n\n## 🔗 相关项目\n\n  - [E2B 代码解释器](https://github.com/e2b-dev/code-interpreter) - 作为我们基础的原项目。\n  - [FastMCP](https://github.com/jlowin/fastmcp) - 模型上下文协议（MCP）的一个实现。\n\n## 📞 支持\n\n  - **问题**：在 [GitHub Issues](https://github.com/BIGPPWONG/edgebox/issues) 上报告错误和功能请求。\n  - **讨论**：加入 [GitHub Discussions](https://github.com/BIGPPWONG/edgebox/discussions) 的对话。\n\n\u003c!-- end list --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBIGPPWONG%2FEdgeBox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FBIGPPWONG%2FEdgeBox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBIGPPWONG%2FEdgeBox/lists"}