llm-sandbox

环境要求

• Python 环境，且 pip 可用（README 示例镜像为 python:3.9.19-bullseye）
• 使用 Docker 后端时需本机可用的 Docker 守护进程
• 使用 Podman 后端时需本机可用的 Podman（rootless 容器）
• 使用 Kubernetes 后端时需可访问的集群与 kubeconfig 文件

安装与启动步骤

1. 1安装核心库

   安装 llm-sandbox 基础包，这是所有用法（SandboxSession、Pool 等）的前提。

   pip install llm-sandbox

   复制

2. 2安装 Docker 支持

   Docker 是最常用的后端，需要额外安装 docker 可选依赖，否则无法创建容器沙箱。

   pip install 'llm-sandbox[docker]'

   复制

3. 3运行首个沙箱

   用 SandboxSession 创建 python 语言沙箱并执行代码；退出 with 块时自动清理沙箱资源。

   from llm_sandbox import SandboxSession
   
   with SandboxSession(lang="python") as session:
       result = session.run("print('Hello, World!')")
       print(result)

   复制

4. 4安装 MCP 支持

   若要给 Claude Desktop 等 MCP 客户端提供代码执行能力，安装带 mcp 与 docker 的依赖组合。

   pip install 'llm-sandbox[mcp-docker]'

   复制

5. 5配置 MCP 客户端

   在 MCP 客户端配置文件中注册 llm-sandbox 服务端，通过环境变量指定后端与 Docker 主机。

   {
     "mcpServers": {
       "llm-sandbox": {
         "command": "python3",
         "args": ["-m", "llm_sandbox.mcp_server.server"],
         "env": {
           "BACKEND": "docker",
           "DOCKER_HOST": "unix:///var/run/docker.sock"
         }
       }
     }
   }

   复制

6. 6开发模式安装

   如需参与开发或改源码，克隆仓库后用 make install（uv sync + pre-commit install）安装开发依赖。

   git clone https://github.com/vndee/llm-sandbox.git
   cd llm-sandbox
   make install

   复制

关键配置

如何确认成功

按示例运行 SandboxSession(lang="python") 并 print 结果，能输出 'Hello, World!' 即表示沙箱启动成功。

常见问题

注意事项

• README 未给出 Python 最低版本要求，示例镜像使用 python:3.9.19-bullseye，建议对齐该版本。
• MCP 配置中的 DOCKER_HOST、KUBECONFIG 需替换为你自己环境的真实值。
• 开发模式安装依赖 uv 与 make，普通使用只需 pip 安装即可。
• 沙箱代码运行在隔离容器内，请先确保所选后端（Docker/Podman/Kubernetes）已就绪。