llm-sandbox

library0.3.39pypypi✓ verified 85d ago

LLM Sandbox is a lightweight and portable Python library designed to run large language model (LLM) generated code in a safe and isolated environment. It supports various container backends like Docker, Kubernetes, and Podman, and offers multi-language execution (Python, JavaScript, Java, C++, Go, R). The project sees frequent minor releases, addressing features, fixes, and security enhancements, and now supports the Model Context Protocol (MCP) server for direct AI assistant integration.

llm-agents devops ai-ml

pip install llm-sandbox

github ↗package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · LLM-SANDBOX

llm-sandbox

llm-agentspythonv0.3.39

Install

3.2s avg

Import

579ms

Disk

26MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.3.39 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.940 runs

installs and imports cleanly · install 0.0s · import 0.488s · 28.7MB

glibc

py 3.10–3.940 runs

installs and imports cleanly · install 3.2s · import 0.439s · 28MB

26MB installed

● package 26MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

SandboxSession

✓ from llm_sandbox import SandboxSession

This quickstart demonstrates how to create a `SandboxSession` for Python, execute code, and optionally specify libraries. It includes error handling for common setup issues like the container backend not running.

import os from llm_sandbox import SandboxSession # Ensure Docker or another backend is running and accessible # For a simple test, ensure `llm-sandbox[docker]` is installed. try: with SandboxSession(lang="python") as session: print("Running Python code in sandbox...") result = session.run( "import math\nprint(math.factorial(5))" ) print(f"Sandbox Output: {result.stdout.strip()}") if result.stderr: print(f"Sandbox Error: {result.stderr.strip()}") print("\nRunning Python code with a library (numpy)...") # Requires numpy to be installed in the sandbox environment, # or configured for on-the-fly installation. The default image often includes it. result_numpy = session.run( "import numpy as np\nprint(np.mean([1, 2, 3, 4]))", libraries=["numpy"] ) print(f"Sandbox NumPy Output: {result_numpy.stdout.strip()}") if result_numpy.stderr: print(f"Sandbox NumPy Error: {result_numpy.stderr.strip()}") except Exception as e: print(f"An error occurred during sandbox execution: {e}") print("Ensure your container backend (e.g., Docker) is running and configured correctly.")

Debug

Known issues

breakingOlder versions (prior to 0.3.35) contained command injection and path traversal vulnerabilities. Update immediately to version 0.3.35 or newer to secure your environment.

fix

Upgrade to `llm-sandbox>=0.3.35`.

affects: <0.3.35

gotchaWhen using features like pooled sessions or `skip_environment_setup`, ensure consistent Python environments. Version 0.3.32 fixed an issue where pooled sessions didn't correctly use the venv Python, and 0.3.29 addressed `skip_environment_setup` using a non-existent venv.

fix

Upgrade to `llm-sandbox>=0.3.32`. Carefully review environment configuration for pooled sessions and fast production modes.

affects: <0.3.32

gotchaTo use Docker, Kubernetes, or Podman as a backend, you must install the corresponding optional dependencies (e.g., `pip install 'llm-sandbox[docker]'`) in addition to the base `llm-sandbox` package. Failure to do so will result in runtime errors when attempting to use specific backends.

fix

Install `llm-sandbox` with the correct extra, e.g., `pip install 'llm-sandbox[docker]'`.

affects: All versions

gotchaBy default, sandbox containers are destroyed after the `SandboxSession` closes, meaning any state (e.g., installed libraries, created files) is lost. To persist the container image state, ensure `keep_template=True` is set during session initialization, though the default `SandboxSession` might not directly expose this in all scenarios, requiring careful management of custom images or `SandboxPoolManager`.

fix

Understand the lifecycle of `SandboxSession` and use features like `keep_template` or `SandboxPoolManager` for state management if persistence is required. Refer to documentation for advanced usage.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'llm_sandbox'

The `llm-sandbox` library is not installed in the Python environment, or the environment where the code is being run does not have access to the installed library.

fix

Install the library using pip: `pip install llm-sandbox`. If using specific backends, install with extras, e.g., `pip install 'llm-sandbox[docker]'`.

ModuleNotFoundError: No module named 'numpy'

A Python package required by the code running *inside* the LLM Sandbox container is not installed within that container's environment.

fix

When creating the `SandboxSession`, specify the required libraries using the `libraries` parameter: `session = SandboxSession(lang="python", libraries=["numpy"])`.

docker.errors.DockerException: Error while fetching server API version

The `llm-sandbox` library, when using the Docker backend, cannot connect to the Docker daemon. This typically happens if Docker Desktop or the Docker service is not running, or if there's a permission/configuration issue.

fix

Ensure Docker Desktop or the Docker daemon is running and properly configured on your system. Check Docker's logs for more specific connection issues.

ImportError: cannot import name 'LLM' from 'llm_sandbox'

The user is attempting to import a class named 'LLM' which does not exist in the `llm_sandbox` library. The primary session class for this library is `SandboxSession`.

fix

Correct the import statement to use `SandboxSession`: `from llm_sandbox import SandboxSession`.

TimeoutError

The code executed within the sandbox exceeded the maximum allowed execution time, causing the sandbox to terminate the process.

fix

Increase the `timeout` parameter when creating the `SandboxSession` or when calling `session.run()`: `session = SandboxSession(lang="python", timeout=60)` or `result = session.run("long_running_code()", timeout=120)`.

Upgrade

Version history

0.3.39latest on PyPI · released Apr 20, 2026

Audit

Dependencies

pythonrequiredRequired Python version.

pydanticrequiredCore dependency for data validation and settings management.

dockeroptionalRequired for Docker container backend.

kubernetesoptionalRequired for Kubernetes container backend.

podmanoptionalRequired for Podman container backend.

Agent activity

29 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/vndee/llm-sandbox ↗

packagehttps://pypi.org/project/llm-sandbox/ ↗

homepagehttps://vndee.github.io/llm-sandbox/ ↗

docshttps://vndee.github.io/llm-sandbox/ ↗