Skip to content
Back to search

llm-sandbox

Lightweight and portable LLM sandbox runtime (code interpreter) Python library.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/vndee/llm-sandbox with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/vndee/llm-sandbox'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/vndee--llm-sandbox/badge.svg)](/listings/vndee--llm-sandbox)

HTML

<a href="/listings/vndee--llm-sandbox"><img src="/api/listings/vndee--llm-sandbox/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Basic Installation

pip install llm-sandbox

With Specific Backend Support

# For Docker support (most common)
pip install 'llm-sandbox[docker]'

# For Kubernetes support
pip install 'llm-sandbox[k8s]'

# For Podman support
pip install 'llm-sandbox[podman]'

# All optional container SDKs
pip install 'llm-sandbox[docker,k8s,podman]'

Bubblewrap and NsJail use the base Python package plus system executables; no container SDK extra is needed. See [local backend requirements](docs/backends.md#local-linux-backends) for Linux prerequisites.

The Windows adapters also need no container SDK. `windows-mxc` requires a compatible Windows host and the native helper, while `wsl2-bubblewrap` requires a configured WSL2 distribution with the matching Python package and Linux prerequisites. See [Windows requirements](docs/backends.md#windows-backends); neither adapter installs an OS runtime or falls back to unsandboxed execution.

Development Installation

Dev dependencies live in the `dev` [uv dependency group](https://docs.astral.sh/uv/concepts/projects/dependencies/#dependency-groups), so install them with `uv` (or the `make install` shortcut):

git clone https://github.com/vndee/llm-sandbox.git
cd llm-sandbox
make install   # uv sync + pre-commit install

See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,061 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <!-- mcp-name: io.github.vndee/llm-sandbox -->
  2. ## LLM Sandbox
  3. *Securely Execute LLM-Generated Code with Ease*
  4. [![SonarQube Cloud](https://sonarcloud.io/images/project_badges/sonarcloud-light.svg)](https://sonarcloud.io/summary/new_code?id=vndee_llm-sandbox)
  5. [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=vndee_llm-sandbox&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=vndee_llm-sandbox)
  6. [![PyPI Downloads](https://static.pepy.tech/badge/llm-sandbox)](https://pypi.org/project/llm-sandbox/)
  7. [![Release](https://img.shields.io/github/v/release/vndee/llm-sandbox)](https://img.shields.io/github/v/release/vndee/llm-sandbox)
  8. [![Build status](https://img.shields.io/github/actions/workflow/status/vndee/llm-sandbox/main.yml?branch=main)](https://github.com/vndee/llm-sandbox/actions/workflows/main.yml?query=branch%3Amain)
  9. [![CodeFactor](https://www.codefactor.io/repository/github/vndee/llm-sandbox/badge)](https://www.codefactor.io/repository/github/vndee/llm-sandbox)
  10. [![codecov](https://codecov.io/gh/vndee/llm-sandbox/branch/main/graph/badge.svg)](https://codecov.io/gh/vndee/llm-sandbox)
  11. ![](https://badge.mcpx.dev?status=on 'MCP Enabled')
  12. [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21760525.svg)](https://doi.org/10.5281/zenodo.21760525)
  13. **LLM Sandbox** runs Large Language Model (LLM) generated code through a common API for container and local Linux and Windows sandbox backends. Choose an isolation backend for your deployment, configure its security controls, and reuse the same code execution and file APIs.
  14. Documentation: https://vndee.github.io/llm-sandbox/
  15. [Backend benchmarks](docs/benchmarks.md) compare Docker, Bubblewrap and NsJail across startup, execution, file transfers and concurrency, with confidence intervals and [reproducible evidence](benchmarks/results/expanded-20261016/REPORT.md).
  16. ![](https://blog.duy.dev/content/images/size/w2000/2024/07/llm-sandbox--6--1.png)
  17. ✨ **New:** This project now supports the [Model Context Protocol (MCP)](https://vndee.github.io/llm-sandbox/mcp-integration/) server, which allows your MCP clients (e.g. Claude Desktop) to run code generated by LLMs in a secure sandbox environment.
  18. ## 🚀 Key Features
  19. ### 🛡️ Security First
  20. - **Isolated Execution**: Container or local OS sandboxing with explicitly configured host access
  21. - **Security Policies**: Define custom security policies to control code execution
  22. - **Resource Limits**: Set CPU, memory, and execution time limits
  23. - **Network Isolation**: Control network access for sandboxed code
  24. ### 🏗️ Flexible Sandbox Backends
  25. - **Docker**: Most popular and widely supported option
  26. - **Kubernetes**: Enterprise-grade orchestration for scalable deployments
  27. - **Podman**: Rootless containers for enhanced security
  28. - **Bubblewrap**: Local Linux namespaces and seccomp without Docker or a daemon
  29. - **NsJail**: Local Linux namespaces and native seccomp policies without a daemon
  30. - **Windows MXC**: Native Windows process isolation through Microsoft's MXC/PSEC APIs
  31. - **WSL2 Bubblewrap**: Linux namespaces and seccomp in an explicitly selected WSL2 distribution
  32. - **Backend Registry**: Register additional adapters and inspect their supported features
  33. ### 🌐 Multi-Language Support
  34. Execute code in multiple programming languages with automatic dependency management:
  35. - **Python** - Full ecosystem support with pip packages
  36. - **JavaScript/Node.js** - npm package installation
  37. - **Java** - Maven and Gradle dependency management
  38. - **C++** - Compilation and execution
  39. - **Go** - Module support and compilation
  40. - **R** - Statistical computing and data analysis with CRAN packages
  41. ### 🔌 LLM Framework Integration
  42. Runnable examples for eleven agent frameworks — OpenAI Agents SDK, Claude Agent SDK, LangChain, DeepAgents, LlamaIndex, Google ADK, CrewAI, Pydantic AI, smolagents, Strands and AG2. See [`examples/agent_sdks/`](examples/agent_sdks/README.md).
  43. ### 📊 Advanced Features
  44. - **Artifact Extraction**: Automatically capture plots and visualizations
  45. - **Library Management**: Install dependencies on-the-fly
  46. - **File Operations**: Copy files to/from sandbox environments
  47. - **Custom Images**: Use your own container images
  48. - **Fast Production Mode**: Skip environment setup for faster container startup
  49. - **Container Pooling**: Pre-warm and reuse containers for improved performance (NEW!)
  50. ## 📦 Installation
  51. ### Basic Installation
  52. ```bash
  53. pip install llm-sandbox
  54. ```
  55. ### With Specific Backend Support
  56. ```bash
  57. # For Docker support (most common)
  58. pip install 'llm-sandbox[docker]'
  59. # For Kubernetes support
  60. pip install 'llm-sandbox[k8s]'
  61. # For Podman support
  62. pip install 'llm-sandbox[podman]'
  63. # All optional container SDKs
  64. pip install 'llm-sandbox[docker,k8s,podman]'
  65. ```
  66. Bubblewrap and NsJail use the base Python package plus system executables; no container SDK extra is needed. See [local backend requirements](docs/backends.md#local-linux-backends) for Linux prerequisites.
  67. The Windows adapters also need no container SDK. `windows-mxc` requires a compatible Windows host and the native helper, while `wsl2-bubblewrap` requires a configured WSL2 distribution with the matching Python package and Linux prerequisites. See [Windows requirements](docs/backends.md#windows-backends); neither adapter installs an OS runtime or falls back to unsandboxed execution.
  68. ### Development Installation
  69. Dev dependencies live in the `dev` [uv dependency group](https://docs.astral.sh/uv/concepts/projects/dependencies/#dependency-groups), so install them with `uv` (or the `make install` shortcut):
  70. ```bash
  71. git clone https://github.com/vndee/llm-sandbox.git
  72. cd llm-sandbox
  73. make install # uv sync + pre-commit install
  74. ```
  75. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow.
  76. ## 🏃‍♂️ Quick Start
  77. ### Basic Usage
  78. ```python
  79. from llm_sandbox import SandboxSession
  80. # Create and use a sandbox session
  81. with SandboxSession(lang="python") as session:
  82. result = session.run("""
  83. print("Hello from LLM Sandbox!")
  84. print("I'm running in a secure container.")
  85. """)
  86. print(result.stdout)
  87. ```
  88. ### Local Linux Usage Without Docker
  89. On Debian/Ubuntu, install the system prerequisites with `sudo apt install bubblewrap libseccomp2 python3-venv`. Bubblewrap must be version 0.8.0 or newer with `--disable-userns` support; older distributions such as Ubuntu 22.04 need a newer package or upstream build. Your host must permit unprivileged user namespaces; distribution security policy can restrict them.
  90. ```python
  91. from llm_sandbox import SandboxSession
  92. with SandboxSession(backend="bubblewrap", lang="python") as session:
  93. result = session.run("print('Hello from a local Linux sandbox!')")
  94. print(result.stdout)
  95. ```
  96. The local defaults combine namespace isolation with a seccomp syscall denylist, disable network access, expose runtime paths read-only, and provide a private writable workspace and temporary directory. Python setup creates a virtual environment offline. Install the host runtime and its `venv` support first. Select `backend="nsjail"` to use an installed NsJail binary instead.
  97. The Linux adapters support `run()`, `execute_command()`, `install()`, file copying, and the artifact wrapper. They do not support container images, pooling, or interactive sessions. Files persist between commands in a session; background processes do not. These backends share the host kernel and are not a VM boundary. See [configuration](docs/configuration.md#local-linux-configuration), [security](docs/security.md#local-linux-isolation-and-seccomp), and the [backend roadmap](docs/backends.md#extension-roadmap).
  98. ### Windows Usage Without Docker
  99. For native Windows Python execution, use the MXC adapter on a compatible Windows host with the helper installed:
  100. ```python
  101. from llm_sandbox import SandboxSession
  102. with SandboxSession(backend="windows-mxc", lang="python") as session:
  103. print(session.run("import platform; print(platform.system())").stdout)
  104. ```
  105. To run Linux tools from a Windows Python application, select a WSL2 distribution explicitly:
  106. ```python
  107. from llm_sandbox import SandboxSession
  108. with SandboxSession(
  109. backend="wsl2-bubblewrap",
  110. distribution="Ubuntu",
  111. lang="python",
  112. ) as session:
  113. print(session.run("import platform; print(platform.system())").stdout)
  114. ```
  115. These are experimental adapters with different prerequisites and API limits. MXC initially supports Python and JavaScript with preinstalled dependencies. WSL2 reuses the Linux Bubblewrap runtime, requires seccomp, and restricts mounts to built-in Linux runtime paths to keep Windows interoperability inaccessible. Both default to disabled networking. See [backend setup and limitations](docs/backends.md#windows-backends).
  116. ### Installing Libraries
  117. ```python
  118. from llm_sandbox import SandboxSession
  119. with SandboxSession(lang="python") as session:
  120. result = session.run("""
  121. import numpy as np
  122. # Create an array
  123. arr = np.array([1, 2, 3, 4, 5])
  124. print(f"Array: {arr}")
  125. print(f"Mean: {np.mean(arr)}")
  126. """, libraries=["numpy"])
  127. print(result.stdout)
  128. ```
  129. ### Multi-Language Support
  130. #### JavaScript
  131. ```python
  132. with SandboxSession(lang="javascript") as session:
  133. result = session.run("""
  134. const greeting = "Hello from Node.js!";
  135. console.log(greeting);
  136. const axios = require('axios');
  137. console.log("Axios loaded successfully!");
  138. """, libraries=["axios"])
  139. ```
  140. #### Java
  141. ```python
  142. with SandboxSession(lang="java") as session:
  143. result = session.run("""
  144. public class HelloWorld {
  145. public static void main(String[] args) {
  146. System.out.println("Hello from Java!");
  147. }
  148. }
  149. """)
  150. ```
  151. #### C++
  152. ```python
  153. with SandboxSession(lang="cpp") as session:
  154. result = session.run("""
  155. #include <iostream>
  156. int main() {
  157. std::cout << "Hello from C++!" << std::endl;
  158. return 0;
  159. }
  160. """)
  161. ```
  162. #### Go
  163. ```python
  164. with SandboxSession(lang="go") as session:
  165. result = session.run("""
  166. package main
  167. import "fmt"
  168. func main() {
  169. fmt.Println("Hello from Go!")
  170. }
  171. """)
  172. ```
  173. #### R
  174. ```python
  175. with SandboxSession(
  176. lang="r",
  177. image="ghcr.io/vndee/sandbox-r-451-bullseye",
  178. verbose=True,
  179. ) as session:
  180. result = session.run(
  181. """
  182. # Basic R operations
  183. print("=== Basic R Demo ===")
  184. # Create some data
  185. numbers <- c(1, 2, 3, 4, 5, 10, 15, 20)
  186. print(paste("Numbers:", paste(numbers, collapse=", ")))
  187. # Basic statistics
  188. print(paste("Mean:", mean(numbers)))
  189. print(paste("Median:", median(numbers)))
  190. print(paste("Standard Deviation:", sd(numbers)))
  191. # Work with data frames
  192. df <- data.frame(
  193. name = c("Alice", "Bob", "Charlie", "Diana"),
  194. age = c(25, 30, 35, 28),
  195. score = c(85, 92, 78, 96)
  196. )
  197. print("=== Data Frame ===")
  198. print(df)
  199. # Calculate average score
  200. avg_score <- mean(df$score)
  201. print(paste("Average Score:", avg_score))
  202. """
  203. )
  204. ```
  205. ### Interactive Sessions
  206. For notebook-style workflows you can use `InteractiveSandboxSession`, which keeps the Python interpreter state across multiple `run` calls.
  207. ```python
  208. from llm_sandbox import InteractiveSandboxSession
  209. with InteractiveSandboxSession(
  210. lang="python",
  211. kernel_type="ipython",
  212. history_size=200,
  213. ) as session:
  214. session.run("value = 21 * 2")
  215. result = session.run("print(f'Result: {value}')")
  216. print(result.stdout) # -> Result: 42
  217. # Use magic command to install libraries
  218. session.run("%pip install pandas")
  219. result = session.run("import pandas as pd; print(pd.DataFrame({'A': [1, 2, 3], 'B': [4, 5, 6]}))")
  220. print(result.stdout)
  221. ```
  222. Interactive sessions support Docker, Podman, and Kubernetes backends and currently target Python language. They spin up a long-running IPython kernel inside the sandbox, so each `run()` behaves like a notebook cell—state, imports, and magic commands stay alive until the context manager exits, without any extra networking or manual serialization.
  223. ### Capturing Plots and Visualizations
  224. #### Python Plots
  225. ```python
  226. from llm_sandbox import ArtifactSandboxSession
  227. import base64
  228. from pathlib import Path
  229. with ArtifactSandboxSession(lang="python") as session:
  230. result = session.run("""
  231. import matplotlib.pyplot as plt
  232. import numpy as np
  233. x = np.linspace(0, 10, 100)
  234. y = np.sin(x)
  235. plt.figure(figsize=(10, 6))
  236. plt.plot(x, y)
  237. plt.title("Sine Wave")
  238. plt.xlabel("x")
  239. plt.ylabel("sin(x)")
  240. plt.grid(True)
  241. plt.savefig("sine_wave.png", dpi=150, bbox_inches="tight")
  242. plt.show()
  243. """, libraries=["matplotlib", "numpy"])
  244. # Extract the generated plots
  245. print(f"Generated {len(result.plots)} plots")
  246. # Save plots to files
  247. for i, plot in enumerate(result.plots):
  248. plot_path = Path(f"plot_{i + 1}.{plot.format.value}")
  249. with plot_path.open("wb") as f:
  250. f.write(base64.b64decode(plot.content_base64))
  251. ```
  252. #### R Plots
  253. ```python
  254. from llm_sandbox import ArtifactSandboxSession
  255. import base64
  256. from pathlib import Path
  257. with ArtifactSandboxSession(lang="r") as session:
  258. result = session.run("""
  259. library(ggplot2)
  260. # Create sample data
  261. data <- data.frame(
  262. x = rnorm(100),
  263. y = rnorm(100)
  264. )
  265. # Create ggplot2 visualization
  266. p <- ggplot(data, aes(x = x, y = y)) +
  267. geom_point(alpha = 0.6) +
  268. geom_smooth(method = "lm", se = FALSE) +
  269. labs(title = "Scatter Plot with Trend Line",
  270. x = "X values", y = "Y values") +
  271. theme_minimal()
  272. print(p)
  273. # Base R plot
  274. hist(data$x, main = "Distribution of X",
  275. xlab = "X values", col = "lightblue", breaks = 20)
  276. """, libraries=["ggplot2"])
  277. # Extract the generated plots
  278. print(f"Generated {len(result.plots)} R plots")
  279. # Save plots to files
  280. for i, plot in enumerate(result.plots):
  281. plot_path = Path(f"r_plot_{i + 1}.{plot.format.value}")
  282. with plot_path.open("wb") as f:
  283. f.write(base64.b64decode(plot.content_base64))
  284. ```
  285. ## 🔧 Configuration
  286. ### Basic Configuration
  287. ```python
  288. from llm_sandbox import SandboxSession
  289. # Create a new sandbox session
  290. with SandboxSession(image="python:3.9.19-bullseye", keep_template=True, lang="python") as session:
  291. result = session.run("print('Hello, World!')")
  292. print(result)
  293. # With custom Dockerfile
  294. with SandboxSession(dockerfile="Dockerfile", keep_template=True, lang="python") as session:
  295. result = session.run("print('Hello, World!')")
  296. print(result)
  297. # Or default image
  298. with SandboxSession(lang="python", keep_template=True) as session:
  299. result = session.run("print('Hello, World!')")
  300. print(result)
  301. ```
  302. LLM Sandbox also supports copying files between the host and the sandbox:
  303. ```python
  304. from llm_sandbox import SandboxSession
  305. with SandboxSession(lang="python", keep_template=True) as session:
  306. # Copy a file from the host to the sandbox
  307. session.copy_to_runtime("test.py", "/sandbox/test.py")
  308. # Run the copied Python code in the sandbox
  309. result = session.execute_command("python /sandbox/test.py")
  310. print(result)
  311. # Copy a file from the sandbox to the host
  312. session.copy_from_runtime("/sandbox/output.txt", "output.txt")
  313. ```
  314. #### Custom runtime configs
  315. ```python
  316. from llm_sandbox import SandboxSession
  317. pod_manifest = {
  318. "apiVersion": "v1",
  319. "kind": "Pod",
  320. "metadata": {
  321. "name": "test",
  322. "namespace": "test",
  323. "labels": {"app": "sandbox"},
  324. },
  325. "spec": {
  326. "containers": [
  327. {
  328. "name": "sandbox-container",
  329. "image": "test",
  330. "tty": True,
  331. "volumeMounts": {
  332. "name": "tmp",
  333. "mountPath": "/tmp",
  334. },
  335. }
  336. ],
  337. "volumes": [{"name": "tmp", "emptyDir": {"sizeLimit": "5Gi"}}],
  338. },
  339. }
  340. with SandboxSession(
  341. backend="kubernetes",
  342. image="python:3.9.19-bullseye",
  343. dockerfile=None,
  344. lang="python",
  345. keep_template=False,
  346. verbose=False,
  347. pod_manifest=pod_manifest,
  348. ) as session:
  349. result = session.run("print('Hello, World!')")
  350. print(result)
  351. ```
  352. #### Remote Docker Host
  353. ```python
  354. import docker
  355. from llm_sandbox import SandboxSession
  356. tls_config = docker.tls.TLSConfig(
  357. client_cert=("path/to/cert.pem", "path/to/key.pem"),
  358. ca_cert="path/to/ca.pem",
  359. verify=True
  360. )
  361. docker_client = docker.DockerClient(base_url="tcp://<your_host>:<port>", tls=tls_config)
  362. with SandboxSession(
  363. client=docker_client,
  364. image="python:3.9.19-bullseye",
  365. keep_template=True,
  366. lang="python",
  367. ) as session:
  368. result = session.run("print('Hello, World!')")
  369. print(result)
  370. ```
  371. #### Kubernetes Support
  372. ```python
  373. from kubernetes import client, config
  374. from llm_sandbox import SandboxSession
  375. # Use local kubeconfig
  376. config.load_kube_config()
  377. k8s_client = client.CoreV1Api()
  378. with SandboxSession(
  379. client=k8s_client,
  380. backend="kubernetes",
  381. image="python:3.9.19-bullseye",
  382. lang="python",
  383. pod_manifest=pod_manifest, # None by default
  384. ) as session:
  385. result = session.run("print('Hello from Kubernetes!')")
  386. print(result)
  387. ```
  388. **⚠️ Important for Custom Pod Manifests:**
  389. When using custom pod manifests, ensure your container configuration includes:
  390. - `"tty": True` (keeps container alive)
  391. - Proper `securityContext` at both pod and container levels
  392. - Container name can be any valid name (no restrictions)
  393. See the [Configuration Guide](docs/configuration.md#kubernetes-backend) for complete requirements.
  394. #### Podman Support
  395. ```python
  396. from llm_sandbox import SandboxSession
  397. with SandboxSession(
  398. backend="podman",
  399. lang="python",
  400. image="python:3.9.19-bullseye"
  401. ) as session:
  402. result = session.run("print('Hello from Podman!')")
  403. print(result)
  404. ```
  405. ## ⚡ Container Pooling (Performance Optimization)
  406. Container pooling dramatically improves performance by reusing pre-warmed containers instead of creating new ones for each execution. This is particularly beneficial for applications that execute code frequently.
  407. ### Key Benefits
  408. - **Faster Execution**: Eliminate container creation overhead (up to 10x faster)
  409. - **Pre-warmed Environments**: Containers are initialized with your dependencies
  410. - **Thread-Safe**: Safely handle concurrent requests
  411. - **Resource Efficient**: Automatic container lifecycle management
  412. - **Flexible Configuration**: Control pool size, timeouts, and behavior
  413. ### Basic Pool Usage
  414. ```python
  415. from llm_sandbox import SandboxSession
  416. from llm_sandbox.pool import PoolConfig, create_pool_manager
  417. # Create a pool manager explicitly
  418. pool = create_pool_manager(
  419. backend="docker",
  420. config=PoolConfig(
  421. max_pool_size=10, # Maximum containers
  422. min_pool_size=3, # Keep at least 3 warm
  423. idle_timeout=300.0, # Recycle idle containers after 5 min
  424. enable_prewarming=True, # Create containers on startup
  425. ),
  426. lang="python",
  427. )
  428. # Use the pool in a session
  429. with SandboxSession(
  430. lang="python",
  431. pool=pool,
  432. ) as session:
  433. result = session.run("print('Hello from pool!')")
  434. # Container is automatically returned to pool when the session closes
  435. # Clean up the pool when done
  436. pool.close()
  437. ```
  438. ### Sharing a Pool Across Sessions
  439. For maximum efficiency, share a single pool across multiple sessions:
  440. ```python
  441. from llm_sandbox import SandboxSession
  442. from llm_sandbox.pool import create_pool_manager, PoolConfig
  443. # Create a shared pool manager
  444. pool = create_pool_manager(
  445. backend="docker",
  446. config=PoolConfig(
  447. max_pool_size=10,
  448. min_pool_size=3,
  449. ),
  450. lang="python",
  451. libraries=["numpy", "pandas"], # Pre-install libraries in all containers
  452. )
  453. # Use the pool in multiple sessions
  454. with SandboxSession(lang="python", pool=pool) as session1:
  455. result1 = session1.run("import pandas; print(pandas.__version__)")
  456. with SandboxSession(lang="python", pool=pool) as session2:
  457. result2 = session2.run("import numpy; print(numpy.__version__)")
  458. # Clean up when done
  459. pool.close()
  460. ```
  461. ### Concurrent Execution
  462. Container pools are thread-safe and handle concurrent requests efficiently:
  463. ```python
  464. from concurrent.futures import ThreadPoolExecutor
  465. from llm_sandbox import SandboxSession
  466. from llm_sandbox.pool import create_pool_manager, PoolConfig
  467. # Create shared pool
  468. pool = create_pool_manager(
  469. backend="docker",
  470. config=PoolConfig(max_pool_size=5),
  471. lang="python",
  472. )
  473. def run_code(task_id: int):
  474. with SandboxSession(lang="python", pool=pool) as session:
  475. return session.run(f'print("Task {task_id}")')
  476. try:
  477. # Execute 20 tasks concurrently using only 5 containers
  478. with ThreadPoolExecutor(max_workers=10) as executor:
  479. results = list(executor.map(run_code, range(20)))
  480. finally:
  481. pool.close()
  482. ```
  483. ### Pool Configuration Options
  484. ```python
  485. from llm_sandbox.pool import PoolConfig, ExhaustionStrategy, create_pool_manager
  486. config = PoolConfig(
  487. # Pool size limits
  488. max_pool_size=10, # Maximum containers in pool
  489. min_pool_size=2, # Minimum warm containers
  490. # Timeout configuration
  491. idle_timeout=300.0, # Recycle idle containers (seconds)
  492. acquisition_timeout=30.0, # Wait time for available container
  493. # Health and lifecycle
  494. health_check_interval=60.0, # Health check frequency
  495. max_container_lifetime=3600.0, # Max container lifetime
  496. max_container_uses=100, # Max uses before recycling
  497. # Pool exhaustion behavior
  498. exhaustion_strategy=ExhaustionStrategy.WAIT, # WAIT, FAIL_FAST, or TEMPORARY
  499. # Pre-warming
  500. enable_prewarming=True, # Pre-warm containers
  501. )
  502. pool = create_pool_manager(
  503. backend="docker",
  504. config=config,
  505. lang="python",
  506. libraries=["requests", "numpy"], # Pre-install libraries
  507. )
  508. ```
  509. ### Pool Exhaustion Strategies
  510. When all containers are busy, the pool can handle it in different ways:
  511. #### 1. WAIT (Default)
  512. Wait for a container to become available:
  513. ```python
  514. config = PoolConfig(
  515. max_pool_size=5,
  516. exhaustion_strategy=ExhaustionStrategy.WAIT,
  517. acquisition_timeout=30.0, # Wait up to 30 seconds
  518. )
  519. ```
  520. #### 2. FAIL_FAST
  521. Immediately raise an error:
  522. ```python
  523. config = PoolConfig(
  524. max_pool_size=5,
  525. exhaustion_strategy=ExhaustionStrategy.FAIL_FAST,
  526. )
  527. ```
  528. #### 3. TEMPORARY
  529. Create a temporary container outside the pool:
  530. ```python
  531. config = PoolConfig(
  532. max_pool_size=5,
  533. exhaustion_strategy=ExhaustionStrategy.TEMPORARY,
  534. )
  535. ```
  536. ### Monitoring Pool Statistics
  537. ```python
  538. from llm_sandbox.pool import create_pool_manager
  539. pool = create_pool_manager(backend="docker", lang="python")
  540. # Get pool statistics
  541. stats = pool.get_stats()
  542. print(f"Total containers: {stats['total_size']}")
  543. print(f"Idle containers: {stats['state_counts']['idle']}")
  544. print(f"Busy containers: {stats['state_counts']['busy']}")
  545. pool.close()
  546. ```
  547. ### Artifact Extraction with Pooling
  548. For capturing plots and visualizations with container pooling, you can use either approach:
  549. ```python
  550. from llm_sandbox import ArtifactSandboxSession
  551. from llm_sandbox.pool import create_pool_manager, PoolConfig
  552. import base64
  553. from pathlib import Path
  554. # Create pool with pre-installed visualization libraries
  555. pool = create_pool_manager(
  556. backend="docker",
  557. config=PoolConfig(max_pool_size=5, min_pool_size=2),
  558. lang="python",
  559. libraries=["matplotlib", "numpy"],
  560. )
  561. try:
  562. # Option 1: Use pool parameter (recommended for API consistency)
  563. with ArtifactSandboxSession(pool=pool, enable_plotting=True) as session:
  564. result = session.run("""
  565. import matplotlib.pyplot as plt
  566. import numpy as np
  567. x = np.linspace(0, 10, 100)
  568. y = np.sin(x)
  569. plt.plot(x, y)
  570. plt.title('Pooled Execution - Sine Wave')
  571. plt.show()
  572. """)
  573. # Save generated plots
  574. for i, plot in enumerate(result.plots):
  575. Path(f"plot_{i}.{plot.format.value}").write_bytes(
  576. base64.b64decode(plot.content_base64)
  577. )
  578. print(f"Generated {len(result.plots)} plots using pooled container")
  579. # Option 2: Use ArtifactPooledSandboxSession (explicit class)
  580. # Both approaches work identically
  581. from llm_sandbox.pool import ArtifactPooledSandboxSession
  582. with ArtifactPooledSandboxSession(pool_manager=pool, enable_plotting=True) as session:
  583. result = session.run("print('Same functionality, different API')")
  584. finally:
  585. pool.close()
  586. ```
  587. ### Examples
  588. See the `examples/` directory for complete demonstrations:
  589. - [pool_basic_demo.py](examples/pool_basic_demo.py) - Basic pool usage and configuration
  590. - [pool_concurrent_demo.py](examples/pool_concurrent_demo.py) - Concurrent execution patterns
  591. - [pool_monitoring_demo.py](examples/pool_monitoring_demo.py) - Health monitoring and lifecycle management
  592. - [pool_artifact_demo.py](examples/pool_artifact_demo.py) - Artifact extraction with pooling (plots, CSV, mixed artifacts)
  593. ## 🤖 LLM Framework Integration
  594. Runnable, version-pinned examples for **eleven** agent frameworks live in
  595. **[`examples/agent_sdks/`](examples/agent_sdks/README.md)**:
  596. | | | |
  597. |---|---|---|
  598. | [OpenAI Agents SDK](examples/agent_sdks/openai_agents_tool.py) | [Claude Agent SDK](examples/agent_sdks/claude_agent_sdk_tool.py) | [LangChain](examples/agent_sdks/langchain_tool.py) |
  599. | [DeepAgents](examples/agent_sdks/deepagents_tool.py) | [LlamaIndex](examples/agent_sdks/llamaindex_tool.py) | [Google ADK](examples/agent_sdks/google_adk_tool.py) |
  600. | [CrewAI](examples/agent_sdks/crewai_tool.py) | [Pydantic AI](examples/agent_sdks/pydantic_ai_tool.py) | [smolagents](examples/agent_sdks/smolagents_tool.py) |
  601. | [Strands Agents](examples/agent_sdks/strands_tool.py) | [AG2](examples/agent_sdks/ag2_tool.py) | |
  602. Each file is self-contained, names the SDK version it was verified against, and
  603. applies container hardening. They all share the same core — a sandbox call with
  604. the controls that matter once the code was written by a model:
  605. ```python
  606. from llm_sandbox import SandboxSession
  607. SANDBOX_RUNTIME = {
  608. "network_mode": "none", # no egress
  609. "mem_limit": "512m",
  610. "pids_limit": 128, # bounds fork bombs
  611. "security_opt": ["no-new-privileges:true"],
  612. }
  613. def run_python(code: str) -> str:
  614. with SandboxSession(
  615. lang="python",
  616. keep_template=True, # else the image is re-pulled each call
  617. runtime_configs=SANDBOX_RUNTIME,
  618. ) as session:
  619. result = session.run(code, timeout=30)
  620. return result.stdout if result.exit_code == 0 else result.stderr
  621. ```
  622. > [!IMPORTANT]
  623. > **Security policies are advisory.** `session.is_safe(code)` returns a verdict —
  624. > it does **not** block execution, and `run()` executes code the policy flagged.
  625. > Check it yourself before calling `run()`. See the
  626. > [security guide](https://vndee.github.io/llm-sandbox/security/).
  627. ## 🔌 Model Context Protocol (MCP) Server
  628. LLM Sandbox provides a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that enables AI assistants like Claude Desktop to execute code securely in sandboxed environments. This integration allows LLMs to run code directly with automatic visualization capture and multi-language support.
  629. ### Features
  630. - **Secure Code Execution**: Execute code in isolated containers with your preferred backend
  631. - **Multi-Language Support**: Run Python, JavaScript, Java, C++, Go, R, and Ruby code
  632. - **Automatic Visualization Capture**: Automatically capture and return plots and visualizations
  633. - **Library Management**: Install packages and dependencies on-the-fly
  634. - **Flexible Backend Support**: Choose from Docker, Podman, or Kubernetes backends
  635. ### Installation
  636. Install LLM Sandbox with MCP support using your preferred backend:
  637. ```bash
  638. # For Docker backend
  639. pip install 'llm-sandbox[mcp-docker]'
  640. # For Podman backend
  641. pip install 'llm-sandbox[mcp-podman]'
  642. # For Kubernetes backend
  643. pip install 'llm-sandbox[mcp-k8s]'
  644. ```
  645. ### Configuration
  646. Add the following configuration to your MCP client (e.g., `claude_desktop_config.json` for Claude Desktop):
  647. ```json
  648. {
  649. "mcpServers": {
  650. "llm-sandbox": {
  651. "command": "python3",
  652. "args": ["-m", "llm_sandbox.mcp_server.server"],
  653. }
  654. }
  655. }
  656. ```
  657. #### Backend-Specific Configuration
  658. For the specific backend, you need to set the `BACKEND` environment variable to the backend you want to use. You might need to set other environment variables depending on the backend you are using. For example, you might need to set the `DOCKER_HOST` environment variable to the host you want to use if the `DOCKER_HOST` is not automatically in your system.
  659. **Docker (default):**
  660. ```json
  661. {
  662. "mcpServers": {
  663. "llm-sandbox": {
  664. "command": "python3",
  665. "args": ["-m", "llm_sandbox.mcp_server.server"],
  666. "env": {
  667. "BACKEND": "docker",
  668. "DOCKER_HOST": "unix:///var/run/docker.sock" // change this to the actual host you are using
  669. }
  670. }
  671. }
  672. }
  673. ```
  674. **Podman:**
  675. ```json
  676. {
  677. "mcpServers": {
  678. "llm-sandbox": {
  679. "command": "python3",
  680. "args": ["-m", "llm_sandbox.mcp_server.server"],
  681. "env": {
  682. "BACKEND": "podman",
  683. "DOCKER_HOST": "unix:///var/run/podman/podman.sock" // change this to the actual host you are using
  684. }
  685. }
  686. }
  687. }
  688. ```
  689. For Kubernetes, you might need to set the `KUBECONFIG` environment variable to the path to your kubeconfig file.
  690. **Kubernetes:**
  691. ```json
  692. {
  693. "mcpServers": {
  694. "llm-sandbox": {
  695. "command": "python3",
  696. "args": ["-m", "llm_sandbox.mcp_server.server"],
  697. "env": {
  698. "BACKEND": "kubernetes",
  699. "KUBECONFIG": "/path/to/kubeconfig" // change this to the actual path to your kubeconfig file
  700. }
  701. }
  702. }
  703. }
  704. ```
  705. #### Runtime Config Environment Variables
  706. For Docker, Podman, and Micromamba backends, the MCP server can translate `SANDBOX_*` environment
  707. variables into session `runtime_configs`.
  708. ```json
  709. {
  710. "mcpServers": {
  711. "llm-sandbox": {
  712. "command": "python3",
  713. "args": ["-m", "llm_sandbox.mcp_server.server"],
  714. "env": {
  715. "BACKEND": "podman",
  716. "DOCKER_HOST": "unix:///run/podman/podman.sock",
  717. "SANDBOX_NETWORK_MODE": "none",
  718. "SANDBOX_READ_ONLY": "true",
  719. "SANDBOX_CAP_DROP": "ALL",
  720. "SANDBOX_SECURITY_OPT": "no-new-privileges:true",
  721. "SANDBOX_MEMORY": "4g",
  722. "SANDBOX_CPU_COUNT": "1"
  723. }
  724. }
  725. }
  726. }
  727. ```
  728. Supported variables: `SANDBOX_NETWORK_MODE`, `SANDBOX_READ_ONLY`, `SANDBOX_MEMORY`, `SANDBOX_MEM_LIMIT`,
  729. `SANDBOX_CPUS`, `SANDBOX_CPU_COUNT`, `SANDBOX_CAP_DROP`, `SANDBOX_SECURITY_OPT`, and `SANDBOX_PRIVILEGED`.
  730. `SANDBOX_MEMORY` is normalized to the backend-safe `mem_limit` runtime config. `SANDBOX_CPUS` and
  731. `SANDBOX_CPU_COUNT` are normalized to Linux-compatible CPU quota settings.
  732. > Security note: prefer `SANDBOX_NETWORK_MODE=none`, `SANDBOX_READ_ONLY=true`,
  733. > `SANDBOX_CAP_DROP=ALL`, and restrictive `SANDBOX_SECURITY_OPT` values for hardened
  734. > sandboxes. Avoid `SANDBOX_PRIVILEGED=true` unless you explicitly need it, keep CPU
  735. > and memory limits minimal, and audit any combination that re-enables privileges.
  736. > `SANDBOX_*` settings do not apply to the Kubernetes backend in this MCP server.
  737. > If you need Kubernetes-specific resource or security controls, provide a custom
  738. > `pod_manifest` via a custom MCP wrapper or use the llm-sandbox Python API directly.
  739. ### Available Tools
  740. The MCP server provides the following tools:
  741. - **`execute_code`**: Execute code in a secure sandbox with automatic visualization capture
  742. - **`get_supported_languages`**: Get the list of supported programming languages
  743. - **`get_language_details`**: Get detailed information about a specific language
  744. ### Usage Example
  745. Once configured, you can ask your AI assistant to run code, and it will automatically use the LLM Sandbox MCP server:
  746. ```text
  747. "Create a scatter plot showing the relationship between x and y data points using matplotlib"
  748. ```
  749. The assistant will execute Python code in a secure sandbox and automatically capture any generated plots or visualizations.
  750. ## 🏗️ Architecture
  751. ```mermaid
  752. graph LR
  753. A[LLM Client] --> B[LLM Sandbox]
  754. B --> C[Container Backend]
  755. A1[OpenAI] --> A
  756. A2[Anthropic] --> A
  757. A3[Local LLMs] --> A
  758. A4[LangChain] --> A
  759. A5[LangGraph] --> A
  760. A6[LlamaIndex] --> A
  761. A7[MCP Clients] --> A
  762. C --> C1[Docker]
  763. C --> C2[Kubernetes]
  764. C --> C3[Podman]
  765. style A fill:#e1f5fe
  766. style B fill:#f3e5f5
  767. style C fill:#e8f5e8
  768. style A1 fill:#fff3e0
  769. style A2 fill:#fff3e0
  770. style A3 fill:#fff3e0
  771. style A4 fill:#fff3e0
  772. style A5 fill:#fff3e0
  773. style A6 fill:#fff3e0
  774. style A7 fill:#fff3e0
  775. style C1 fill:#e0f2f1
  776. style C2 fill:#e0f2f1
  777. style C3 fill:#e0f2f1
  778. ```
  779. ## 📚 Documentation
  780. - **[Full Documentation](https://vndee.github.io/llm-sandbox/)** - Complete documentation
  781. - **[Getting Started](https://vndee.github.io/llm-sandbox/getting-started/)** - Installation and basic usage
  782. - **[Configuration](https://vndee.github.io/llm-sandbox/configuration/)** - Detailed configuration options
  783. - **[Security](https://vndee.github.io/llm-sandbox/security/)** - Security policies and best practices
  784. - **[Backends](https://vndee.github.io/llm-sandbox/backends/)** - Container backend details
  785. - **[Languages](https://vndee.github.io/llm-sandbox/languages/)** - Supported programming languages
  786. - **[Integrations](https://vndee.github.io/llm-sandbox/integrations/)** - LLM framework integrations
  787. - **[API Reference](https://vndee.github.io/llm-sandbox/api-reference/)** - Complete API documentation
  788. - **[Examples](https://vndee.github.io/llm-sandbox/examples/)** - Real-world usage examples
  789. ## 🤝 Contributing
  790. We welcome contributions! Please see our [Contributing Guide](https://vndee.github.io/llm-sandbox/contributing/) for details.
  791. ### Development Setup
  792. ```bash
  793. # Clone the repository
  794. git clone https://github.com/vndee/llm-sandbox.git
  795. cd llm-sandbox
  796. # Install in development mode
  797. make install
  798. # Run pre-commit hooks
  799. uv run pre-commit run -a
  800. # Run tests
  801. make test
  802. ```
  803. ## 📖 Citation
  804. If you use LLM Sandbox in your research, please cite it:
  805. ```bibtex
  806. @software{huynh_llm_sandbox,
  807. author = {Huynh, Duy V.},
  808. title = {{LLM Sandbox: a portable runtime for securely executing LLM-generated code}},
  809. publisher = {Zenodo},
  810. doi = {10.5281/zenodo.21760525},
  811. url = {https://doi.org/10.5281/zenodo.21760525}
  812. }
  813. ```
  814. The DOI above resolves to the latest release. To cite a specific version, use that release's own DOI from the [Zenodo record](https://doi.org/10.5281/zenodo.21760525).
  815. ## 📄 License
  816. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  817. ## 🌟 Star History
  818. If you find LLM Sandbox useful, please consider giving it a star on GitHub!
  819. ## 📞 Support & Community
  820. - **GitHub Issues**: [Report bugs or request features](https://github.com/vndee/llm-sandbox/issues)
  821. - **GitHub Discussions**: [Join the community](https://github.com/vndee/llm-sandbox/discussions)
  822. - **PyPI**: [pypi.org/project/llm-sandbox](https://pypi.org/project/llm-sandbox/)
  823. - **Documentation**: [vndee.github.io/llm-sandbox](https://vndee.github.io/llm-sandbox/)
  824. ## Contributors
  825. <a href="https://github.com/vndee/llm-sandbox/graphs/contributors">
  826. <img src="https://contrib.rocks/image?repo=vndee/llm-sandbox" />
  827. </a>
  828. ## Star History
  829. [![Star History Chart](https://star-history.dera.page/svg?repos=vndee/llm-sandbox&type=Date)](https://star-history.dera.page/#vndee/llm-sandbox&Date)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.