vndee/llm-sandbox

LLM Sandbox – AI 生成程式碼的安全執行

是什麼 – 一個輕量級的 Python 庫，可啟動隔離的容器（Docker、Kubernetes 或 Podman），並在其中執行大型語言模型生成的程式碼。它讓開發者能像處理一般腳本一樣使用 LLM 的輸出，同時確保主機系統的安全。

為何重要 – LLM 常常產生可執行的程式碼，但在開發者機器上直接執行存在風險。LLM Sandbox 自動建立沙箱環境，套用資源限制，並可捕獲程式碼產生的產物（例如圖表）。

---

核心功能

功能	你將獲得
隔離	每次執行都在獨立的容器中進行，除非明確允許，否則無法存取主機檔案系統或網路。
安全策略	可自訂 CPU、記憶體、執行時間及網路連接的策略。
多後端支援	Docker（預設）、Kubernetes（企業級擴展）、Podman（無 root 權限）。
多語言支援	Python、JavaScript/Node、Java、C++、Go、R – 庫會動態安裝所需的套件管理器（pip、npm、Maven/Gradle 等）。
LLM 框架鈎子	提供 11 個主流代理 SDK（LangChain、Claude、LlamaIndex、CrewAI 等）的預設範例。
產物提取	自動將生成的影像/圖表以 base-64 字串形式回傳，便於在筆記本或 API 中顯示。
互動式會話	InteractiveSandboxSession 保持長期執行的 IPython 內核，支援跨單元狀態持久化執行。
容器池化	預熱容器池並重複使用，可將啟動延遲降低高達 10 倍，支援併發執行。
自訂映像與 Dockerfile	可使用自訂容器映像或 Dockerfile 建構專用環境。

---

快速開始（Python）

from llm_sandbox import SandboxSession

with SandboxSession(lang="python") as s:
    r = s.run("print('來自安全容器的問候！')")
    print(r.stdout)

安裝套件:

pip install llm-sandbox            # 核心功能
pip install 'llm-sandbox[docker]'   # Docker 支援（最常見）
# 或加入 [k8s] / [podman] 以啟用其他後端

你也可以在執行時請求額外套件：

s.run("import numpy as np; print(np.mean([1,2,3]))", libraries=["numpy"])

---

使用其他語言

# JavaScript (Node.js)
with SandboxSession(lang="javascript") as s:
    s.run("const axios = require('axios'); console.log('axios 準備就緒');", libraries=["axios"])

# C++
with SandboxSession(lang="cpp") as s:
    s.run("#include <iostream>\nint main(){std::cout<<'你好';}")

Java、Go 和 R 也使用相同模式，只需選擇 lang 參數，並可選擇性傳入已包含執行時的容器映像。

互動式筆記本

from llm_sandbox import InteractiveSandboxSession

with InteractiveSandboxSession(lang="python", kernel_type="ipython") as s:
    s.run("value = 7 * 6")
    print(s.run("print(value)").stdout)   # → 42
    s.run("%pip install pandas")          # 筆記本內魔術命令可用

狀態（變數、匯入、魔術命令）在上下文管理器退出前保持持久。

容器池化（高吞吐量用例）

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

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

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

pool.close()   # 應用關閉時清理

該池是執行緒安全的，可跨多個併發請求共享。

更多學習資源

• 文件 – https://vndee.github.io/llm-sandbox/（完整 API 參考、設定指南、MCP 集成）。
• MCP 伺服器 – 此套件可作為 Model Context Protocol 端點，讓 Claude Desktop 等工具能安全傳送程式碼執行。
• 範例 – examples/agent_sdks/ 包含 OpenAI、Claude、LangChain、CrewAI 等的即用型程式碼片段。

---

TL;DR

• 安裝 llm-sandbox（選擇 Docker、K8s 或 Podman 擴充）。
• 將任意 LLM 生成的程式碼片段包裝在 SandboxSession(...).run(...) 中。
• 取得 stdout、stderr、結束碼以及生成的圖表。
• 生產負載使用容器池化，筆記本使用互動式會話。

---

總結 – LLM Sandbox 將 LLM 提出的「執行這段程式碼」建議轉化為安全、可重現、語言無關的操作，使開發者能在不暴露主機環境風險的前提下，自由實驗 AI 生成的腳本。