LLM Sandbox

LLM Sandbox

*Securely Execute LLM-Generated Code with Ease*

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.

Documentation: https://vndee.github.io/llm-sandbox/

Backend benchmarks compare Docker, Bubblewrap and NsJail across startup, execution, file transfers and concurrency, with confidence intervals and reproducible evidence.

✨ 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: Container or local OS sandboxing with explicitly configured host access
• 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 Sandbox Backends

• Docker: Most popular and widely supported option
• Kubernetes: Enterprise-grade orchestration for scalable deployments
• Podman: Rootless containers for enhanced security
• Bubblewrap: Local Linux namespaces and seccomp without Docker or a daemon
• NsJail: Local Linux namespaces and native seccomp policies without a daemon
• Windows MXC: Native Windows process isolation through Microsoft's MXC/PSEC APIs
• WSL2 Bubblewrap: Linux namespaces and seccomp in an explicitly selected WSL2 distribution
• Backend Registry: Register additional adapters and inspect their supported features

🌐 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
• Library Management: Install dependencies on-the-fly
• File Operations: Copy files to/from sandbox environments
• Custom Images: Use your own container images
• Fast Production Mode: Skip environment setup for faster container startup
• Container Pooling: Pre-warm and reuse containers for improved performance (NEW!)

📦 Installation

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 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; neither adapter installs an OS runtime or falls back to unsandboxed execution.

Development Installation

Dev dependencies live in the dev uv dependency group, 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 for the full workflow.

🏃♂️ Quick Start

Basic Usage

from llm_sandbox import SandboxSession

Create and use a sandbox session

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)

Local Linux Usage Without Docker

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.

from llm_sandbox import SandboxSession

with SandboxSession(backend="bubblewrap", lang="python") as session: result = session.run("print('Hello from a local Linux sandbox!')") print(result.stdout)

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.

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, security, and the backend roadmap.

Windows Usage Without Docker

For native Windows Python execution, use the MXC adapter on a compatible Windows host with the helper installed:

from llm_sandbox import SandboxSession

with SandboxSession(backend="windows-mxc", lang="python") as session: print(session.run("import platform; print(platform.system())").stdout)

To run Linux tools from a Windows Python application, select a WSL2 distribution explicitly:

from llm_sandbox import SandboxSession

with SandboxSession( backend="wsl2-bubblewrap", distribution="Ubuntu", lang="python", ) as session: print(session.run("import platform; print(platform.system())").stdout)

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.

Installing Libraries

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

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

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++

with SandboxSession(lang="cpp") as session:

result = session.run(""" #include

int main() { std::cout << "Hello from C++!" << std::endl; return 0; } """)

Go

with SandboxSession(lang="go") as session:

result = session.run(""" package main import "fmt"

func main() { fmt.Println("Hello from Go!") } """)

R

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.

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

from llm_sandbox import ArtifactSandboxSession

import base64 from pathlib import Path

with ArtifactSandboxSession(lang="pyth