vndee/llm-sandbox

LLM Sandbox – Secure Execution for AI‑Generated Code

What it is – A lightweight Python library that launches isolated containers (Docker, Kubernetes, or Podman) and runs code produced by large language models inside them. It lets developers treat LLM output like ordinary scripts while keeping the host system safe.

Why it matters – LLMs often emit runnable code, but executing that code directly on a developer’s machine is risky. LLM Sandbox automates the creation of a sandbox, applies resource limits, and can capture artefacts (e.g., plots) that the code generates.

Core capabilities

Feature	What you get
Isolation	Each run happens in its own container with no host filesystem or network access unless you explicitly allow it.
Security policies	Custom policies for CPU, memory, execution time, and network connectivity.
Multiple back‑ends	Docker (default), Kubernetes (enterprise‑scale), Podman (root‑less).
Multi‑language support	Python, JavaScript/Node, Java, C++, Go, R – the library installs the needed package manager (pip, npm, Maven/Gradle, etc.) on the fly.
LLM framework hooks	Ready‑made examples for 11 popular agent SDKs (LangChain, Claude, LlamaIndex, CrewAI, …).
Artifact extraction	Automatically returns generated images/plots as base‑64 blobs, so notebooks or APIs can display them.
Interactive sessions	`InteractiveSandboxSession` keeps a long‑running IPython kernel alive, letting you run multiple cells with state persistence.
Container pooling	Pre‑warm a pool of containers and reuse them, cutting start‑up latency by up to 10× and supporting concurrent execution.
Custom images & Dockerfiles	Bring your own container image or Dockerfile for specialised environments.

Quick start (Python)

from llm_sandbox import SandboxSession

with SandboxSession(lang="python") as s:
    r = s.run("print('Hello from a safe container!')")
    print(r.stdout)

Install the library:

pip install llm-sandbox            # core
pip install 'llm-sandbox[docker]'   # Docker support (most common)
# or add [k8s] / [podman] for the other back‑ends

You can also request extra packages at run‑time:

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

Using other languages

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

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

The same pattern works for Java, Go, and R – just pick the `lang` argument and optionally pass a container image that already contains the runtime.

Interactive notebooks

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")          # magic works inside the sandbox

State (variables, imports, magic commands) persists across calls until the context manager exits.

Container pooling (high‑throughput use case)

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()   # clean up when the app shuts down

The pool is thread‑safe, so you can share it across many concurrent requests.

Where to learn more

Documentation – https://vndee.github.io/llm-sandbox/ (full API reference, configuration guide, MCP integration).
MCP server – the library can act as a Model Context Protocol endpoint, letting tools like Claude Desktop send code to be executed safely.
Examples – examples/agent_sdks/ contains ready‑to‑run snippets for OpenAI, Claude, LangChain, CrewAI, and others.

TL;DR

Install llm-sandbox (choose Docker, K8s, or Podman extras).
Wrap any LLM‑generated snippet in SandboxSession(...).run(...).
Get back stdout, stderr, exit code, and any generated plots.
Use container pooling for production workloads, or interactive sessions for notebooks.

Bottom line – LLM Sandbox turns the “run this code” suggestion from an LLM into a secure, reproducible, and language‑agnostic operation, letting developers experiment with AI‑generated scripts without exposing their host environment to risk.