Securely run LLM-generated code in isolated containers across 7 languages and 3 container backends.
io.github.vndee/llm-sandbox MCP Server
The MCP server “io.github.vndee/llm-sandbox” securely runs LLM-generated code in isolated containers. It supports execution across 7 languages and uses 3 container backends. The project is associated with the “LLM Sandbox” concept for executing generated code in a controlled environment.
LLM Sandbox is a lightweight and portable sandbox environment designed to run Large Language Model (LLM) generated code in a safe and isolated mode. It provides a secure execution environment for AI-generated code while offering flexibility in container backends and comprehensive language support, simplifying the process of running code generated by LLMs.
✨ New: This project now supports the Model Context Protocol (MCP) server, which allows your MCP clients (e.g. Claude Desktop) to run code generated by LLMs in a secure sandbox environment.
🚀 Key Features
🛡️ Security First
Isolated Execution: Code runs in isolated containers with no access to host system
Security Policies: Define custom security policies to control code execution
Resource Limits: Set CPU, memory, and execution time limits
Network Isolation: Control network access for sandboxed code
🏗️ Flexible Container Backends
Docker: Most popular and widely supported option
Kubernetes: Enterprise-grade orchestration for scalable deployments
Podman: Rootless containers for enhanced security
🌐 Multi-Language Support
Execute code in multiple programming languages with automatic dependency management:
Python - Full ecosystem support with pip packages
JavaScript/Node.js - npm package installation
Java - Maven and Gradle dependency management
C++ - Compilation and execution
Go - Module support and compilation
R - Statistical computing and data analysis with CRAN packages
🔌 LLM Framework Integration
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/.
📊 Advanced Features
Artifact Extraction: Automatically capture plots and visualizations
Fast Production Mode: Skip environment setup for faster container startup
Container Pooling: Pre-warm and reuse containers for improved performance (NEW!)
📦 Installation
Basic Installation
bash
pip install llm-sandbox
With Specific Backend Support
bash
# 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 backends
pip install 'llm-sandbox[docker,k8s,podman]'
Development Installation
Dev dependencies live in the devuv dependency group, so install them with uv (or the make install shortcut):
bash
git clone https://github.com/vndee/llm-sandbox.git
cd llm-sandbox
make install # uv sync + pre-commit install
from llm_sandbox import SandboxSession
# Create and use a sandbox sessionwith SandboxSession(lang="python") as session:
result = session.run("""
print("Hello from LLM Sandbox!")
print("I'm running in a secure container.")
""")
print(result.stdout)
Installing Libraries
python
from llm_sandbox import SandboxSession
with SandboxSession(lang="python") as session:
result = session.run("""
import numpy as np
# Create an array
arr = np.array([1, 2, 3, 4, 5])
print(f"Array: {arr}")
print(f"Mean: {np.mean(arr)}")
""", libraries=["numpy"])
print(result.stdout)
Multi-Language Support
JavaScript
python
with SandboxSession(lang="javascript") as session:
result = session.run("""
const greeting = "Hello from Node.js!";
console.log(greeting);
const axios = require('axios');
console.log("Axios loaded successfully!");
""", libraries=["axios"])
Java
python
with SandboxSession(lang="java") as session:
result = session.run("""
public class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello from Java!");
}
}
""")
C++
python
with SandboxSession(lang="cpp") as session:
result = session.run("""
#include <iostream>
int main() {
std::cout << "Hello from C++!" << std::endl;
return 0;
}
""")
Go
python
with SandboxSession(lang="go") as session:
result = session.run("""
package main
import "fmt"
func main() {
fmt.Println("Hello from Go!")
}
""")
R
python
with SandboxSession(
lang="r",
image="ghcr.io/vndee/sandbox-r-451-bullseye",
verbose=True,
) as session:
result = session.run(
"""
# Basic R operations
print("=== Basic R Demo ===")
# Create some data
numbers <- c(1, 2, 3, 4, 5, 10, 15, 20)
print(paste("Numbers:", paste(numbers, collapse=", ")))
# Basic statistics
print(paste("Mean:", mean(numbers)))
print(paste("Median:", median(numbers)))
print(paste("Standard Deviation:", sd(numbers)))
# Work with data frames
df <- data.frame(
name = c("Alice", "Bob", "Charlie", "Diana"),
age = c(25, 30, 35, 28),
score = c(85, 92, 78, 96)
)
print("=== Data Frame ===")
print(df)
# Calculate average score
avg_score <- mean(df$score)
print(paste("Average Score:", avg_score))
"""
)
Interactive Sessions
For notebook-style workflows you can use InteractiveSandboxSession, which keeps the Python interpreter state across multiple run calls.
python
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}')")
print(result.stdout) # -> Result: 42# Use magic command to install libraries
session.run("%pip install pandas")
result = session.run("import pandas as pd; print(pd.DataFrame({'A': [1, 2, 3], 'B': [4, 5, 6]}))")
print(result.stdout)
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.
Capturing Plots and Visualizations
Python Plots
python
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
x = np.linspace(0, 10, 100)
y = np.sin(x)
plt.figure(figsize=(10, 6))
plt.plot(x, y)
plt.title("Sine Wave")
plt.xlabel("x")
plt.ylabel("sin(x)")
plt.grid(True)
plt.savefig("sine_wave.png", dpi=150, bbox_inches="tight")
plt.show()
""", libraries=["matplotlib", "numpy"])
# Extract the generated plotsprint(f"Generated {len(result.plots)} plots")
# Save plots to filesfor i, plot inenumerate(result.plots):
plot_path = Path(f"plot_{i + 1}.{plot.format.value}")
with plot_path.open("wb") as f:
f.write(base64.b64decode(plot.content_base64))
R Plots
python
from llm_sandbox import ArtifactSandboxSession
import base64
from pathlib import Path
with ArtifactSandboxSession(lang="r") as session:
result = session.run("""
library(ggplot2)
# Create sample data
data <- data.frame(
x = rnorm(100),
y = rnorm(100)
)
# Create ggplot2 visualization
p <- ggplot(data, aes(x = x, y = y)) +
geom_point(alpha = 0.6) +
geom_smooth(method = "lm", se = FALSE) +
labs(title = "Scatter Plot with Trend Line",
x = "X values", y = "Y values") +
theme_minimal()
print(p)
# Base R plot
hist(data$x, main = "Distribution of X",
xlab = "X values", col = "lightblue", breaks = 20)
""", libraries=["ggplot2"])
# Extract the generated plotsprint(f"Generated {len(result.plots)} R plots")
# Save plots to filesfor i, plot inenumerate(result.plots):
plot_path = Path(f"r_plot_{i + 1}.{plot.format.value}")
with plot_path.open("wb") as f:
f.write(base64.b64decode(plot.content_base64))
🔧 Configuration
Basic Configuration
python
from llm_sandbox import SandboxSession
# Create a new sandbox sessionwith SandboxSession(image="python:3.9.19-bullseye", keep_template=True, lang="python") as session:
result = session.run("print('Hello, World!')")
print(result)
# With custom Dockerfilewith SandboxSession(dockerfile="Dockerfile", keep_template=True, lang="python") as session:
result = session.run("print('Hello, World!')")
print(result)
# Or default imagewith SandboxSession(lang="python", keep_template=True) as session:
result = session.run("print('Hello, World!')")
print(result)
LLM Sandbox also supports copying files between the host and the sandbox:
python
from llm_sandbox import SandboxSession
with SandboxSession(lang="python", keep_template=True) as session:
# Copy a file from the host to the sandbox
session.copy_to_runtime("test.py", "/sandbox/test.py")
# Run the copied Python code in the sandbox
result = session.execute_command("python /sandbox/test.py")
print(result)
# Copy a file from the sandbox to the host
session.copy_from_runtime("/sandbox/output.txt", "output.txt")
import docker
from llm_sandbox import SandboxSession
tls_config = docker.tls.TLSConfig(
client_cert=("path/to/cert.pem", "path/to/key.pem"),
ca_cert="path/to/ca.pem",
verify=True
)
docker_client = docker.DockerClient(base_url="tcp://<your_host>:<port>", tls=tls_config)
with SandboxSession(
client=docker_client,
image="python:3.9.19-bullseye",
keep_template=True,
lang="python",
) as session:
result = session.run("print('Hello, World!')")
print(result)
Kubernetes Support
python
from kubernetes import client, config
from llm_sandbox import SandboxSession
# Use local kubeconfig
config.load_kube_config()
k8s_client = client.CoreV1Api()
with SandboxSession(
client=k8s_client,
backend="kubernetes",
image="python:3.9.19-bullseye",
lang="python",
pod_manifest=pod_manifest, # None by default
) as session:
result = session.run("print('Hello from Kubernetes!')")
print(result)
⚠️ Important for Custom Pod Manifests:
When using custom pod manifests, ensure your container configuration includes:
"tty": True (keeps container alive)
Proper securityContext at both pod and container levels
Container name can be any valid name (no restrictions)
from llm_sandbox import SandboxSession
with SandboxSession(
backend="podman",
lang="python",
image="python:3.9.19-bullseye"
) as session:
result = session.run("print('Hello from Podman!')")
print(result)
⚡ Container Pooling (Performance Optimization)
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.
Key Benefits
Faster Execution: Eliminate container creation overhead (up to 10x faster)
Pre-warmed Environments: Containers are initialized with your dependencies
Flexible Configuration: Control pool size, timeouts, and behavior
Basic Pool Usage
python
from llm_sandbox import SandboxSession
from llm_sandbox.pool import PoolConfig, create_pool_manager
# Create a pool manager explicitly
pool = create_pool_manager(
backend="docker",
config=PoolConfig(
max_pool_size=10, # Maximum containers
min_pool_size=3, # Keep at least 3 warm
idle_timeout=300.0, # Recycle idle containers after 5 min
enable_prewarming=True, # Create containers on startup
),
lang="python",
)
# Use the pool in a sessionwith SandboxSession(
lang="python",
pool=pool,
) as session:
result = session.run("print('Hello from pool!')")
# Container is automatically returned to pool when the session closes# Clean up the pool when done
pool.close()
Sharing a Pool Across Sessions
For maximum efficiency, share a single pool across multiple sessions:
python
from llm_sandbox import SandboxSession
from llm_sandbox.pool import create_pool_manager, PoolConfig
# Create a shared pool manager
pool = create_pool_manager(
backend="docker",
config=PoolConfig(
max_pool_size=10,
min_pool_size=3,
),
lang="python",
libraries=["numpy", "pandas"], # Pre-install libraries in all containers
)
# Use the pool in multiple sessionswith SandboxSession(lang="python", pool=pool) as session1:
result1 = session1.run("import pandas; print(pandas.__version__)")
with SandboxSession(lang="python", pool=pool) as session2:
result2 = session2.run("import numpy; print(numpy.__version__)")
# Clean up when done
pool.close()
Concurrent Execution
Container pools are thread-safe and handle concurrent requests efficiently:
python
from concurrent.futures import ThreadPoolExecutor
from llm_sandbox import SandboxSession
from llm_sandbox.pool import create_pool_manager, PoolConfig
# Create shared pool
pool = create_pool_manager(
backend="docker",
config=PoolConfig(max_pool_size=5),
lang="python",
)
defrun_code(task_id: int):
with SandboxSession(lang="python", pool=pool) as session:
return session.run(f'print("Task {task_id}")')
try:
# Execute 20 tasks concurrently using only 5 containerswith ThreadPoolExecutor(max_workers=10) as executor:
results = list(executor.map(run_code, range(20)))
finally:
pool.close()
Pool Configuration Options
python
from llm_sandbox.pool import PoolConfig, ExhaustionStrategy, create_pool_manager
config = PoolConfig(
# Pool size limits
max_pool_size=10, # Maximum containers in pool
min_pool_size=2, # Minimum warm containers# Timeout configuration
idle_timeout=300.0, # Recycle idle containers (seconds)
acquisition_timeout=30.0, # Wait time for available container# Health and lifecycle
health_check_interval=60.0, # Health check frequency
max_container_lifetime=3600.0, # Max container lifetime
max_container_uses=100, # Max uses before recycling# Pool exhaustion behavior
exhaustion_strategy=ExhaustionStrategy.WAIT, # WAIT, FAIL_FAST, or TEMPORARY# Pre-warming
enable_prewarming=True, # Pre-warm containers
)
pool = create_pool_manager(
backend="docker",
config=config,
lang="python",
libraries=["requests", "numpy"], # Pre-install libraries
)
Pool Exhaustion Strategies
When all containers are busy, the pool can handle it in different ways:
1. WAIT (Default)
Wait for a container to become available:
python
config = PoolConfig(
max_pool_size=5,
exhaustion_strategy=ExhaustionStrategy.WAIT,
acquisition_timeout=30.0, # Wait up to 30 seconds
)
from llm_sandbox.pool import create_pool_manager
pool = create_pool_manager(backend="docker", lang="python")
# Get pool statistics
stats = pool.get_stats()
print(f"Total containers: {stats['total_size']}")
print(f"Idle containers: {stats['state_counts']['idle']}")
print(f"Busy containers: {stats['state_counts']['busy']}")
pool.close()
Artifact Extraction with Pooling
For capturing plots and visualizations with container pooling, you can use either approach:
python
from llm_sandbox import ArtifactSandboxSession
from llm_sandbox.pool import create_pool_manager, PoolConfig
import base64
from pathlib import Path
# Create pool with pre-installed visualization libraries
pool = create_pool_manager(
backend="docker",
config=PoolConfig(max_pool_size=5, min_pool_size=2),
lang="python",
libraries=["matplotlib", "numpy"],
)
try:
# Option 1: Use pool parameter (recommended for API consistency)with ArtifactSandboxSession(pool=pool, enable_plotting=True) as session:
result = session.run("""
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(0, 10, 100)
y = np.sin(x)
plt.plot(x, y)
plt.title('Pooled Execution - Sine Wave')
plt.show()
""")
# Save generated plotsfor i, plot inenumerate(result.plots):
Path(f"plot_{i}.{plot.format.value}").write_bytes(
base64.b64decode(plot.content_base64)
)
print(f"Generated {len(result.plots)} plots using pooled container")
# Option 2: Use ArtifactPooledSandboxSession (explicit class)# Both approaches work identicallyfrom llm_sandbox.pool import ArtifactPooledSandboxSession
with ArtifactPooledSandboxSession(pool_manager=pool, enable_plotting=True) as session:
result = session.run("print('Same functionality, different API')")
finally:
pool.close()
Examples
See the examples/ directory for complete demonstrations:
Each file is self-contained, names the SDK version it was verified against, and
applies container hardening. They all share the same core — a sandbox call with
the controls that matter once the code was written by a model:
python
from llm_sandbox import SandboxSession
SANDBOX_RUNTIME = {
"network_mode": "none", # no egress"mem_limit": "512m",
"pids_limit": 128, # bounds fork bombs"security_opt": ["no-new-privileges:true"],
}
defrun_python(code: str) -> str:
with SandboxSession(
lang="python",
keep_template=True, # else the image is re-pulled each call
runtime_configs=SANDBOX_RUNTIME,
) as session:
result = session.run(code, timeout=30)
return result.stdout if result.exit_code == 0else result.stderr
IMPORTANT
Security policies are advisory.session.is_safe(code) returns a verdict —
it does not block execution, and run() executes code the policy flagged.
Check it yourself before calling run(). See the
security guide.
🔌 Model Context Protocol (MCP) Server
LLM Sandbox provides a Model Context Protocol (MCP) 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.
Features
Secure Code Execution: Execute code in isolated containers with your preferred backend
Multi-Language Support: Run Python, JavaScript, Java, C++, Go, R, and Ruby code
Automatic Visualization Capture: Automatically capture and return plots and visualizations
Library Management: Install packages and dependencies on-the-fly
Flexible Backend Support: Choose from Docker, Podman, or Kubernetes backends
Installation
Install LLM Sandbox with MCP support using your preferred backend:
bash
# For Docker backend
pip install 'llm-sandbox[mcp-docker]'# For Podman backend
pip install 'llm-sandbox[mcp-podman]'# For Kubernetes backend
pip install 'llm-sandbox[mcp-k8s]'
Configuration
Add the following configuration to your MCP client (e.g., claude_desktop_config.json for Claude Desktop):
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.
Docker (default):
json
{"mcpServers":{"llm-sandbox":{"command":"python3","args":["-m","llm_sandbox.mcp_server.server"],"env":{"BACKEND":"docker","DOCKER_HOST":"unix:///var/run/docker.sock"// change this to the actual host you are using}}}}
Podman:
json
{"mcpServers":{"llm-sandbox":{"command":"python3","args":["-m","llm_sandbox.mcp_server.server"],"env":{"BACKEND":"podman","DOCKER_HOST":"unix:///var/run/podman/podman.sock"// change this to the actual host you are using}}}}
For Kubernetes, you might need to set the KUBECONFIG environment variable to the path to your kubeconfig file.
Kubernetes:
json
{"mcpServers":{"llm-sandbox":{"command":"python3","args":["-m","llm_sandbox.mcp_server.server"],"env":{"BACKEND":"kubernetes","KUBECONFIG":"/path/to/kubeconfig"// change this to the actual path to your kubeconfig file}}}}
Runtime Config Environment Variables
For Docker, Podman, and Micromamba backends, the MCP server can translate SANDBOX_* environment
variables into session runtime_configs.
SANDBOX_MEMORY is normalized to the backend-safe mem_limit runtime config. SANDBOX_CPUS and
SANDBOX_CPU_COUNT are normalized to Linux-compatible CPU quota settings.
Security note: prefer SANDBOX_NETWORK_MODE=none, SANDBOX_READ_ONLY=true,
SANDBOX_CAP_DROP=ALL, and restrictive SANDBOX_SECURITY_OPT values for hardened
sandboxes. Avoid SANDBOX_PRIVILEGED=true unless you explicitly need it, keep CPU
and memory limits minimal, and audit any combination that re-enables privileges.
SANDBOX_* settings do not apply to the Kubernetes backend in this MCP server.
If you need Kubernetes-specific resource or security controls, provide a custom
pod_manifest via a custom MCP wrapper or use the llm-sandbox Python API directly.
Available Tools
The MCP server provides the following tools:
execute_code: Execute code in a secure sandbox with automatic visualization capture
get_supported_languages: Get the list of supported programming languages
get_language_details: Get detailed information about a specific language
Usage Example
Once configured, you can ask your AI assistant to run code, and it will automatically use the LLM Sandbox MCP server:
text
"Create a scatter plot showing the relationship between x and y data points using matplotlib"
The assistant will execute Python code in a secure sandbox and automatically capture any generated plots or visualizations.
🏗️ Architecture
graph LR
A[LLM Client] --> B[LLM Sandbox]
B --> C[Container Backend]
A1[OpenAI] --> A
A2[Anthropic] --> A
A3[Local LLMs] --> A
A4[LangChain] --> A
A5[LangGraph] --> A
A6[LlamaIndex] --> A
A7[MCP Clients] --> A
C --> C1[Docker]
C --> C2[Kubernetes]
C --> C3[Podman]
style A fill:#e1f5fe
style B fill:#f3e5f5
style C fill:#e8f5e8
style A1 fill:#fff3e0
style A2 fill:#fff3e0
style A3 fill:#fff3e0
style A4 fill:#fff3e0
style A5 fill:#fff3e0
style A6 fill:#fff3e0
style A7 fill:#fff3e0
style C1 fill:#e0f2f1
style C2 fill:#e0f2f1
style C3 fill:#e0f2f1
We welcome contributions! Please see our Contributing Guide for details.
Development Setup
bash
# Clone the repository
git clone https://github.com/vndee/llm-sandbox.git
cd llm-sandbox
# Install in development mode
make install
# Run pre-commit hooks
uv run pre-commit run -a
# Run tests
make test
📖 Citation
If you use LLM Sandbox in your research, please cite it:
bibtex
@software{huynh_llm_sandbox,
author = {Huynh, Duy V.},
title = {{LLM Sandbox: a portable runtime for securely executing LLM-generated code}},
publisher = {Zenodo},
doi = {10.5281/zenodo.21760525},
url = {https://doi.org/10.5281/zenodo.21760525}
}
The DOI above resolves to the latest release. To cite a specific version, use that release's own DOI from the Zenodo record.
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🌟 Star History
If you find LLM Sandbox useful, please consider giving it a star on GitHub!
