vndee/llm-sandbox · 上手攻略

仓库：vndee/llm-sandbox
链接：https://github.com/vndee/llm-sandbox
分类：AI 基础设施 / 代码沙箱
作者：spark
更新：2026-08-25

是什么

llm-sandbox 是一个面向 LLM 生成代码的轻量级、可移植的沙箱运行时 Python 库。它把"AI 写的代码跑在哪里、怎么隔离、怎么回收产物"这一整套工程问题封装成统一的 SandboxSession API，避免每个 Agent 项目都自己塞一遍 Docker / Kubernetes 调用。

仓库自身定位是"代码解释器后端"——OpenAI 的 Code Interpreter 思路，但完全开源、可自托管、可换底层。当前支持 Docker、Kubernetes、Podman 三种容器后端，覆盖 Python、JavaScript/Node.js、Java、C++、Go、R 六种语言。近期版本合并了 MCP server 集成，Claude Desktop 等 MCP 客户端可以直接把生成的代码丢进沙箱跑。

⚠️ 本攻略的命令、镜像名（python:3.9.19-bullseye、ghcr.io/vndee/sandbox-r-451-bullseye）、可选 extras（[docker]/[k8s]/[podman]）均直接取自 GitHub README 与官方文档，未独立下载校验最新 release tag；版本以官方 PyPI / 文档为准，使用前请 pip show llm-sandbox 复核一次。

解决什么问题

把 LLM 生成的不可信代码塞进生产 Agent 链路时，最头疼的不是"它能不能跑"，而是三件事：

隔离 —— 不污染宿主机文件系统 / 网络。
依赖 —— 不同语言的 pip/npm/mvn 自动装。
产物回收 —— 跑完之后图表、日志、文件怎么拿出来。

SandboxSession 把这三件事压成同一个 session.run(code) 接口；ArtifactSandboxSession 还内置 base64 编码回传 matplotlib / ggplot2 图表；InteractiveSandboxSession 起一个长生命周期的 IPython kernel，让多次 run() 共享状态（导入、变量、%pip install magic 全部持久）。Container Pool 预热容器，README 称"快到 10×"，对需要高频执行的小段代码很关键。

快速安装

# 基础包（仅包含接口抽象 + 内置 mock 风格的 fallback）
pip install llm-sandbox

# 按后端选装 extras
pip install 'llm-sandbox[docker]'      # 最常用
pip install 'llm-sandbox[k8s]'
pip install 'llm-sandbox[podman]'
pip install 'llm-sandbox[docker,k8s,podman]'   # 全装

# 开发者依赖（用 uv 管理 dev group）
git clone https://github.com/vndee/llm-sandbox.git
cd llm-sandbox
make install   # uv sync + pre-commit install

⚠️ README 里 extras 名字是小写 [docker] 而非 [Docker]，手敲时注意。

核心用法

1. Python 最小可跑示例

from llm_sandbox import SandboxSession

with SandboxSession(lang="python") as session:
    result = session.run("""
print("Hello from LLM Sandbox!")
print("I'm running in a secure container.")
""")
    print(result.stdout)

2. 自动安装依赖（libraries 参数）

with SandboxSession(lang="python") as session:
    result = session.run("""
import numpy as np
arr = np.array([1, 2, 3, 4, 5])
print(f"Mean: {np.mean(arr)}")
""", libraries=["numpy"])
    print(result.stdout)

3. 跨语言：JS / Java / C++ / Go / R

with SandboxSession(lang="javascript") as session:
    result = session.run("""
const axios = require('axios');
console.log("Axios loaded successfully!");
""")

R 用例需要显式指定官方镜像（默认 Python 镜像不带 R 工具链）：

with SandboxSession(
    lang="r",
    image="ghcr.io/vndee/sandbox-r-451-bullseye",
    verbose=True,
) as session:
    result = session.run("print(mean(c(1,2,3,4,5)))")

4. InteractiveSandboxSession（notebook 风格）

from llm_sandbox import InteractiveSandboxSession

with InteractiveSandboxSession(
    lang="python",
    kernel_type="ipython",
    history_size=200,
) as session:
    session.run("value = 21 * 2")
    result = session.run("print(f'Result: {value}')")  # Result: 42
    session.run("%pip install pandas")
    result = session.run("import pandas as pd; print(pd.__version__)")

适合多轮 Agent 调试：上一轮定义的变量 / 安装的库下一轮直接用。⚠️ 当前 README 标注 Interactive 仅支持 Python，且后端需是 Docker / Podman / Kubernetes。

5. ArtifactSandboxSession（取回图表）

from llm_sandbox import ArtifactSandboxSession
import base64
from pathlib import Path

with ArtifactSandboxSession(lang="python") as session:
    result = session.run("""
import matplotlib.pyplot as plt
import numpy as np
plt.plot(np.linspace(0, 10, 100), np.sin(np.linspace(0, 10, 100)))
plt.savefig("sine_wave.png", dpi=150)
""", libraries=["matplotlib", "numpy"])

    for i, plot in enumerate(result.plots):
        Path(f"plot_{i+1}.{plot.format.value}").write_bytes(
            base64.b64decode(plot.content_base64)
        )

6. Container Pool（高频复用）

from llm_sandbox import SandboxSession
from llm_sandbox.pool import PoolConfig, create_pool_manager

pool = create_pool_manager(
    backend="docker",
    config=PoolConfig(
        max_pool_size=10,
        min_pool_size=3,
        idle_timeout=300.0,
        enable_prewarming=True,
    ),
    lang="python",
    libraries=["numpy", "pandas"],
)

with SandboxSession(lang="python", pool=pool) as s:
    print(s.run("import pandas; print(pandas.__version__)").stdout)

pool.close()

⚠️ README 自报"快到 10×"是相对冷启动的粗略量级，未给具体基准；并发上限取决于宿主机 Docker daemon 的 cgroup / ulimit，不是库的硬上限。

7. 自定义 Docker / K8s 客户端

import docker
from llm_sandbox import SandboxSession

tls = docker.tls.TLSConfig(
    client_cert=("path/to/cert.pem", "path/to/key.pem"),
    ca_cert="path/to/ca.pem", verify=True,
)
client = docker.DockerClient(base_url="tcp://<host>:<port>", tls=tls)

with SandboxSession(client=client, image="python:3.9.19-bullseye",
                    keep_template=True, lang="python") as session:
    print(session.run("print('Hi')").stdout)

K8s 后端需要传一个 pod_manifest 字典，README 强制要求 "tty": True 与 securityContext，否则容器会立刻退出。

8. MCP server（Claude Desktop 集成）

README 给出单独文档页：https://vndee.github.io/llm-sandbox/mcp-integration/。要点是 llm-sandbox 现在自带一个 MCP server，Claude Desktop 接上之后可以"调用工具 → 跑代码 → 看结果"全链路闭环。⚠️ MCP server 的工具列表与启动参数未在本攻略逐条展开，需查官方文档。

典型适用场景

Agent 框架的代码执行后端：README 列出 OpenAI Agents SDK、Claude Agent SDK、LangChain、DeepAgents、LlamaIndex、Google ADK、CrewAI、Pydantic AI、smolagents、Strands、AG2 11 个框架的官方 examples（examples/agent_sdks/）。
教育 / 数据科学 demo 自动跑：R 的 ggplot2 + Python 的 matplotlib 双语言回收图表。
CI 中跑不可信用户提交代码：默认开启网络隔离 + 资源限制（CPU / memory / execution time）。
企业内部 multi-tenant 评测平台：K8s backend + 自定义 pod_manifest + Container Pool 组合能撑住高并发评测任务。

坑与注意

必须装后端 extras：pip install llm-sandbox 单独只装核心抽象，缺 Docker / K8s client；不装 extras 直接跑会报 BackendUnavailable。
镜像固定 Python 版本：image="python:3.9.19-bullseye" 是 README 给的稳定样例，要追新 Python 需要换镜像 tag；⚠️ README 未列出官方维护的最新镜像版本表，长期使用建议自己构建。
R 语言必须显式指定镜像：默认 image 不带 R；用 ghcr.io/vndee/sandbox-r-451-bullseye。
InteractiveSandboxSession 限 Python + Docker 三后端：README 未列出 K8s 下 Interactive 的官方支持矩阵。
K8s pod_manifest 必带 tty: True：否则容器会被 K8s 当作已结束立刻 OOMKilled。
Container Pool 线程安全：README 自报 thread-safe，但池内容器版本漂移 / 镜像缓存清理需自行设计清理策略。
网络隔离默认开？ README 提"Network Isolation"作为 feature 列出，但未在 SandboxSession.__init__ 显式参数表中给出 network policy 字段，使用前请查 Configuration Guide。
CI / Windows 用户：Podman backend 是 rootless 容器，Windows / macOS Docker Desktop 用户也跑得通，但 K8s backend 在本地基本不可用（需要真实集群）。
⚠️ 真实命令核验状态：本攻略所有 import 名 / 类名 / extras 字符串来自 README 与文档站 https://vndee.github.io/llm-sandbox/，未在 PyPI release notes 单独抽查；下次升级前建议 pip index versions llm-sandbox 对照 CHANGELOG。

与同类对比

e2b-dev/e2b（Code Interpreter 云端版）：托管、即开即用、贵；llm-sandbox 是自托管、免费、需要自己跑 Docker。
docker-py 直接调用：零抽象，灵活但要自己处理 image 构建 / 资源限制 / 产物回收；llm-sandbox 是封装层，省掉 ~80% 样板。
Jupyter Kernel Gateway：天然支持 Interactive + 多语言，但隔离弱、安全边界靠进程级；llm-sandbox 用容器做硬隔离。
subprocess + resource：最轻量但风险最大：跑在宿主机本身，LLM 写出 rm -rf / 会真删——llm-sandbox 的核心卖点就是彻底隔离。
OpenAI Code Interpreter API：托管、闭源、按 token 收费；llm-sandbox + 任意模型 = 自建等价物。

一句话推荐

需要给自家 Agent 加"安全代码执行"能力，又不想被某个云服务绑死 —— 直接上 llm-sandbox，Docker 后端三行接入，多语言 + Container Pool 撑住生产并发。