{"id":20859418,"url":"https://github.com/vndee/llm-sandbox","last_synced_at":"2026-01-28T06:56:56.361Z","repository":{"id":246319790,"uuid":"820723371","full_name":"vndee/llm-sandbox","owner":"vndee","description":"Lightweight and portable LLM sandbox runtime (code interpreter) Python library.","archived":false,"fork":false,"pushed_at":"2026-01-15T15:02:17.000Z","size":4478,"stargazers_count":771,"open_issues_count":17,"forks_count":68,"subscribers_count":5,"default_branch":"main","last_synced_at":"2026-01-15T17:42:14.787Z","etag":null,"topics":["code-generation","code-interpreter","large-language-models","llm-sandbox"],"latest_commit_sha":null,"homepage":"https://vndee.github.io/llm-sandbox/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vndee.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":"docs/security.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["vndee"],"buy_me_a_coffee":"vndee"}},"created_at":"2024-06-27T03:58:23.000Z","updated_at":"2026-01-15T15:51:44.000Z","dependencies_parsed_at":"2024-06-27T06:24:21.570Z","dependency_job_id":"c97c5dca-3e43-47e7-9af4-55bd0a479678","html_url":"https://github.com/vndee/llm-sandbox","commit_stats":null,"previous_names":["vndee/llm-sandbox"],"tags_count":34,"template":false,"template_full_name":null,"purl":"pkg:github/vndee/llm-sandbox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vndee%2Fllm-sandbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vndee%2Fllm-sandbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vndee%2Fllm-sandbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vndee%2Fllm-sandbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vndee","download_url":"https://codeload.github.com/vndee/llm-sandbox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vndee%2Fllm-sandbox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28516720,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T18:55:29.170Z","status":"ssl_error","status_checked_at":"2026-01-17T18:55:03.375Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["code-generation","code-interpreter","large-language-models","llm-sandbox"],"created_at":"2024-11-18T04:49:48.786Z","updated_at":"2026-01-17T19:19:09.737Z","avatar_url":"https://github.com/vndee.png","language":"Python","funding_links":["https://github.com/sponsors/vndee","https://buymeacoffee.com/vndee"],"categories":[],"sub_categories":[],"readme":"## LLM Sandbox\n\n*Securely Execute LLM-Generated Code with Ease*\n\n[![SonarQube Cloud](https://sonarcloud.io/images/project_badges/sonarcloud-light.svg)](https://sonarcloud.io/summary/new_code?id=vndee_llm-sandbox)\n\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=vndee_llm-sandbox\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=vndee_llm-sandbox)\n[![PyPI Downloads](https://static.pepy.tech/badge/llm-sandbox)](https://pypi.org/project/llm-sandbox/)\n[![Release](https://img.shields.io/github/v/release/vndee/llm-sandbox)](https://img.shields.io/github/v/release/vndee/llm-sandbox)\n[![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)\n[![CodeFactor](https://www.codefactor.io/repository/github/vndee/llm-sandbox/badge)](https://www.codefactor.io/repository/github/vndee/llm-sandbox)\n[![codecov](https://codecov.io/gh/vndee/llm-sandbox/branch/main/graph/badge.svg?token=EULWCESZAY)](https://codecov.io/gh/vndee/llm-sandbox)\n![](https://badge.mcpx.dev?status=on 'MCP Enabled')\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/vndee/llm-sandbox)\n\n**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.\n\nDocumentation: https://vndee.github.io/llm-sandbox/\n\n![](https://blog.duy.dev/content/images/size/w2000/2024/07/llm-sandbox--6--1.png)\n\n✨ **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.\n\n## 🚀 Key Features\n\n### 🛡️ Security First\n- **Isolated Execution**: Code runs in isolated containers with no access to host system\n- **Security Policies**: Define custom security policies to control code execution\n- **Resource Limits**: Set CPU, memory, and execution time limits\n- **Network Isolation**: Control network access for sandboxed code\n\n### 🏗️ Flexible Container Backends\n- **Docker**: Most popular and widely supported option\n- **Kubernetes**: Enterprise-grade orchestration for scalable deployments\n- **Podman**: Rootless containers for enhanced security\n\n### 🌐 Multi-Language Support\nExecute code in multiple programming languages with automatic dependency management:\n- **Python** - Full ecosystem support with pip packages\n- **JavaScript/Node.js** - npm package installation\n- **Java** - Maven and Gradle dependency management\n- **C++** - Compilation and execution\n- **Go** - Module support and compilation\n- **R** - Statistical computing and data analysis with CRAN packages\n\n### 🔌 LLM Framework Integration\nSeamlessly integrate with popular LLM frameworks such as LangChain, LangGraph, LlamaIndex, OpenAI, and more.\n\n### 📊 Advanced Features\n- **Artifact Extraction**: Automatically capture plots and visualizations\n- **Library Management**: Install dependencies on-the-fly\n- **File Operations**: Copy files to/from sandbox environments\n- **Custom Images**: Use your own container images\n- **Fast Production Mode**: Skip environment setup for faster container startup\n- **Container Pooling**: Pre-warm and reuse containers for improved performance (NEW!)\n\n## 📦 Installation\n\n### Basic Installation\n```bash\npip install llm-sandbox\n```\n\n### With Specific Backend Support\n```bash\n# For Docker support (most common)\npip install 'llm-sandbox[docker]'\n\n# For Kubernetes support\npip install 'llm-sandbox[k8s]'\n\n# For Podman support\npip install 'llm-sandbox[podman]'\n\n# All backends\npip install 'llm-sandbox[docker,k8s,podman]'\n```\n\n### Development Installation\n```bash\ngit clone https://github.com/vndee/llm-sandbox.git\ncd llm-sandbox\npip install -e '.[dev]'\n```\n\n## 🏃‍♂️ Quick Start\n\n### Basic Usage\n\n```python\nfrom llm_sandbox import SandboxSession\n\n# Create and use a sandbox session\nwith SandboxSession(lang=\"python\") as session:\n    result = session.run(\"\"\"\nprint(\"Hello from LLM Sandbox!\")\nprint(\"I'm running in a secure container.\")\n    \"\"\")\n    print(result.stdout)\n```\n\n### Installing Libraries\n\n```python\nfrom llm_sandbox import SandboxSession\n\nwith SandboxSession(lang=\"python\") as session:\n    result = session.run(\"\"\"\nimport numpy as np\n\n# Create an array\narr = np.array([1, 2, 3, 4, 5])\nprint(f\"Array: {arr}\")\nprint(f\"Mean: {np.mean(arr)}\")\n    \"\"\", libraries=[\"numpy\"])\n\n    print(result.stdout)\n```\n\n### Multi-Language Support\n\n#### JavaScript\n```python\nwith SandboxSession(lang=\"javascript\") as session:\n    result = session.run(\"\"\"\nconst greeting = \"Hello from Node.js!\";\nconsole.log(greeting);\n\nconst axios = require('axios');\nconsole.log(\"Axios loaded successfully!\");\n    \"\"\", libraries=[\"axios\"])\n```\n\n#### Java\n```python\nwith SandboxSession(lang=\"java\") as session:\n    result = session.run(\"\"\"\npublic class HelloWorld {\n    public static void main(String[] args) {\n        System.out.println(\"Hello from Java!\");\n    }\n}\n    \"\"\")\n```\n\n#### C++\n```python\nwith SandboxSession(lang=\"cpp\") as session:\n    result = session.run(\"\"\"\n#include \u003ciostream\u003e\n\nint main() {\n    std::cout \u003c\u003c \"Hello from C++!\" \u003c\u003c std::endl;\n    return 0;\n}\n    \"\"\")\n```\n\n#### Go\n```python\nwith SandboxSession(lang=\"go\") as session:\n    result = session.run(\"\"\"\npackage main\nimport \"fmt\"\n\nfunc main() {\n    fmt.Println(\"Hello from Go!\")\n}\n    \"\"\")\n```\n\n#### R\n```python\nwith SandboxSession(\n    lang=\"r\",\n    image=\"ghcr.io/vndee/sandbox-r-451-bullseye\",\n    verbose=True,\n) as session:\n    result = session.run(\n        \"\"\"\n# Basic R operations\nprint(\"=== Basic R Demo ===\")\n\n# Create some data\nnumbers \u003c- c(1, 2, 3, 4, 5, 10, 15, 20)\nprint(paste(\"Numbers:\", paste(numbers, collapse=\", \")))\n\n# Basic statistics\nprint(paste(\"Mean:\", mean(numbers)))\nprint(paste(\"Median:\", median(numbers)))\nprint(paste(\"Standard Deviation:\", sd(numbers)))\n\n# Work with data frames\ndf \u003c- data.frame(\n    name = c(\"Alice\", \"Bob\", \"Charlie\", \"Diana\"),\n    age = c(25, 30, 35, 28),\n    score = c(85, 92, 78, 96)\n)\n\nprint(\"=== Data Frame ===\")\nprint(df)\n\n# Calculate average score\navg_score \u003c- mean(df$score)\nprint(paste(\"Average Score:\", avg_score))\n        \"\"\"\n    )\n```\n\n### Interactive Sessions\n\nFor notebook-style workflows you can use `InteractiveSandboxSession`, which keeps the Python interpreter state across multiple `run` calls.\n\n```python\nfrom llm_sandbox import InteractiveSandboxSession\n\nwith InteractiveSandboxSession(\n    lang=\"python\",\n    kernel_type=\"ipython\",\n    history_size=200,\n) as session:\n    session.run(\"value = 21 * 2\")\n    result = session.run(\"print(f'Result: {value}')\")\n    print(result.stdout)  # -\u003e Result: 42\n\n    # Use magic command to install libraries\n    session.run(\"%pip install pandas\")\n    result = session.run(\"import pandas as pd; print(pd.DataFrame({'A': [1, 2, 3], 'B': [4, 5, 6]}))\")\n    print(result.stdout)\n```\n\nInteractive 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.\n\n### Capturing Plots and Visualizations\n\n#### Python Plots\n```python\nfrom llm_sandbox import ArtifactSandboxSession\nimport base64\nfrom pathlib import Path\n\nwith ArtifactSandboxSession(lang=\"python\") as session:\n    result = session.run(\"\"\"\nimport matplotlib.pyplot as plt\nimport numpy as np\n\nx = np.linspace(0, 10, 100)\ny = np.sin(x)\n\nplt.figure(figsize=(10, 6))\nplt.plot(x, y)\nplt.title(\"Sine Wave\")\nplt.xlabel(\"x\")\nplt.ylabel(\"sin(x)\")\nplt.grid(True)\nplt.savefig(\"sine_wave.png\", dpi=150, bbox_inches=\"tight\")\nplt.show()\n    \"\"\", libraries=[\"matplotlib\", \"numpy\"])\n\n    # Extract the generated plots\n    print(f\"Generated {len(result.plots)} plots\")\n\n    # Save plots to files\n    for i, plot in enumerate(result.plots):\n        plot_path = Path(f\"plot_{i + 1}.{plot.format.value}\")\n        with plot_path.open(\"wb\") as f:\n            f.write(base64.b64decode(plot.content_base64))\n```\n\n#### R Plots\n```python\nfrom llm_sandbox import ArtifactSandboxSession\nimport base64\nfrom pathlib import Path\n\nwith ArtifactSandboxSession(lang=\"r\") as session:\n    result = session.run(\"\"\"\nlibrary(ggplot2)\n\n# Create sample data\ndata \u003c- data.frame(\n    x = rnorm(100),\n    y = rnorm(100)\n)\n\n# Create ggplot2 visualization\np \u003c- ggplot(data, aes(x = x, y = y)) +\n    geom_point(alpha = 0.6) +\n    geom_smooth(method = \"lm\", se = FALSE) +\n    labs(title = \"Scatter Plot with Trend Line\",\n         x = \"X values\", y = \"Y values\") +\n    theme_minimal()\n\nprint(p)\n\n# Base R plot\nhist(data$x, main = \"Distribution of X\",\n     xlab = \"X values\", col = \"lightblue\", breaks = 20)\n    \"\"\", libraries=[\"ggplot2\"])\n\n    # Extract the generated plots\n    print(f\"Generated {len(result.plots)} R plots\")\n\n    # Save plots to files\n    for i, plot in enumerate(result.plots):\n        plot_path = Path(f\"r_plot_{i + 1}.{plot.format.value}\")\n        with plot_path.open(\"wb\") as f:\n            f.write(base64.b64decode(plot.content_base64))\n```\n\n## 🔧 Configuration\n\n### Basic Configuration\n\n```python\nfrom llm_sandbox import SandboxSession\n\n# Create a new sandbox session\nwith SandboxSession(image=\"python:3.9.19-bullseye\", keep_template=True, lang=\"python\") as session:\n    result = session.run(\"print('Hello, World!')\")\n    print(result)\n\n# With custom Dockerfile\nwith SandboxSession(dockerfile=\"Dockerfile\", keep_template=True, lang=\"python\") as session:\n    result = session.run(\"print('Hello, World!')\")\n    print(result)\n\n# Or default image\nwith SandboxSession(lang=\"python\", keep_template=True) as session:\n    result = session.run(\"print('Hello, World!')\")\n    print(result)\n```\n\n\nLLM Sandbox also supports copying files between the host and the sandbox:\n\n```python\nfrom llm_sandbox import SandboxSession\n\nwith SandboxSession(lang=\"python\", keep_template=True) as session:\n    # Copy a file from the host to the sandbox\n    session.copy_to_runtime(\"test.py\", \"/sandbox/test.py\")\n\n    # Run the copied Python code in the sandbox\n    result = session.execute_command(\"python /sandbox/test.py\")\n    print(result)\n\n    # Copy a file from the sandbox to the host\n    session.copy_from_runtime(\"/sandbox/output.txt\", \"output.txt\")\n```\n\n#### Custom runtime configs\n\n```python\nfrom llm_sandbox import SandboxSession\n\npod_manifest = {\n    \"apiVersion\": \"v1\",\n    \"kind\": \"Pod\",\n    \"metadata\": {\n        \"name\": \"test\",\n        \"namespace\": \"test\",\n        \"labels\": {\"app\": \"sandbox\"},\n    },\n    \"spec\": {\n        \"containers\": [\n            {\n                \"name\": \"sandbox-container\",\n                \"image\": \"test\",\n                \"tty\": True,\n                \"volumeMounts\": {\n                    \"name\": \"tmp\",\n                    \"mountPath\": \"/tmp\",\n                },\n            }\n        ],\n        \"volumes\": [{\"name\": \"tmp\", \"emptyDir\": {\"sizeLimit\": \"5Gi\"}}],\n    },\n}\nwith SandboxSession(\n    backend=\"kubernetes\",\n    image=\"python:3.9.19-bullseye\",\n    dockerfile=None,\n    lang=\"python\",\n    keep_template=False,\n    verbose=False,\n    pod_manifest=pod_manifest,\n) as session:\n    result = session.run(\"print('Hello, World!')\")\n    print(result)\n```\n\n#### Remote Docker Host\n\n```python\nimport docker\nfrom llm_sandbox import SandboxSession\n\ntls_config = docker.tls.TLSConfig(\n    client_cert=(\"path/to/cert.pem\", \"path/to/key.pem\"),\n    ca_cert=\"path/to/ca.pem\",\n    verify=True\n)\ndocker_client = docker.DockerClient(base_url=\"tcp://\u003cyour_host\u003e:\u003cport\u003e\", tls=tls_config)\n\nwith SandboxSession(\n    client=docker_client,\n    image=\"python:3.9.19-bullseye\",\n    keep_template=True,\n    lang=\"python\",\n) as session:\n    result = session.run(\"print('Hello, World!')\")\n    print(result)\n```\n\n#### Kubernetes Support\n\n```python\nfrom kubernetes import client, config\nfrom llm_sandbox import SandboxSession\n\n# Use local kubeconfig\nconfig.load_kube_config()\nk8s_client = client.CoreV1Api()\n\nwith SandboxSession(\n    client=k8s_client,\n    backend=\"kubernetes\",\n    image=\"python:3.9.19-bullseye\",\n    lang=\"python\",\n    pod_manifest=pod_manifest, # None by default\n) as session:\n    result = session.run(\"print('Hello from Kubernetes!')\")\n    print(result)\n```\n\n**⚠️ Important for Custom Pod Manifests:**\n\nWhen using custom pod manifests, ensure your container configuration includes:\n- `\"tty\": True` (keeps container alive)\n- Proper `securityContext` at both pod and container levels\n- Container name can be any valid name (no restrictions)\n\nSee the [Configuration Guide](docs/configuration.md#kubernetes-backend) for complete requirements.\n\n#### Podman Support\n\n```python\nfrom llm_sandbox import SandboxSession\n\nwith SandboxSession(\n    backend=\"podman\",\n    lang=\"python\",\n    image=\"python:3.9.19-bullseye\"\n) as session:\n    result = session.run(\"print('Hello from Podman!')\")\n    print(result)\n```\n\n## ⚡ Container Pooling (Performance Optimization)\n\nContainer 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.\n\n### Key Benefits\n- **Faster Execution**: Eliminate container creation overhead (up to 10x faster)\n- **Pre-warmed Environments**: Containers are initialized with your dependencies\n- **Thread-Safe**: Safely handle concurrent requests\n- **Resource Efficient**: Automatic container lifecycle management\n- **Flexible Configuration**: Control pool size, timeouts, and behavior\n\n### Basic Pool Usage\n\n```python\nfrom llm_sandbox import SandboxSession\nfrom llm_sandbox.pool import PoolConfig, create_pool_manager\n\n# Create a pool manager explicitly\npool = create_pool_manager(\n    backend=\"docker\",\n    config=PoolConfig(\n        max_pool_size=10,          # Maximum containers\n        min_pool_size=3,           # Keep at least 3 warm\n        idle_timeout=300.0,        # Recycle idle containers after 5 min\n        enable_prewarming=True,    # Create containers on startup\n    ),\n    lang=\"python\",\n)\n\n# Use the pool in a session\nwith SandboxSession(\n    lang=\"python\",\n    pool=pool,\n) as session:\n    result = session.run(\"print('Hello from pool!')\")\n\n# Container is automatically returned to pool when the session closes\n# Clean up the pool when done\npool.close()\n```\n\n### Sharing a Pool Across Sessions\n\nFor maximum efficiency, share a single pool across multiple sessions:\n\n```python\nfrom llm_sandbox import SandboxSession\nfrom llm_sandbox.pool import create_pool_manager, PoolConfig\n\n# Create a shared pool manager\npool = create_pool_manager(\n    backend=\"docker\",\n    config=PoolConfig(\n        max_pool_size=10,\n        min_pool_size=3,\n    ),\n    lang=\"python\",\n    libraries=[\"numpy\", \"pandas\"],  # Pre-install libraries in all containers\n)\n\n# Use the pool in multiple sessions\nwith SandboxSession(lang=\"python\", pool=pool) as session1:\n    result1 = session1.run(\"import pandas; print(pandas.__version__)\")\n\nwith SandboxSession(lang=\"python\", pool=pool) as session2:\n    result2 = session2.run(\"import numpy; print(numpy.__version__)\")\n\n# Clean up when done\npool.close()\n```\n\n### Concurrent Execution\n\nContainer pools are thread-safe and handle concurrent requests efficiently:\n\n```python\nfrom concurrent.futures import ThreadPoolExecutor\nfrom llm_sandbox import SandboxSession\nfrom llm_sandbox.pool import create_pool_manager, PoolConfig\n\n# Create shared pool\npool = create_pool_manager(\n    backend=\"docker\",\n    config=PoolConfig(max_pool_size=5),\n    lang=\"python\",\n)\n\ndef run_code(task_id: int):\n    with SandboxSession(lang=\"python\", pool=pool) as session:\n        return session.run(f'print(\"Task {task_id}\")')\n\ntry:\n    # Execute 20 tasks concurrently using only 5 containers\n    with ThreadPoolExecutor(max_workers=10) as executor:\n        results = list(executor.map(run_code, range(20)))\nfinally:\n    pool.close()\n```\n\n### Pool Configuration Options\n\n```python\nfrom llm_sandbox.pool import PoolConfig, ExhaustionStrategy, create_pool_manager\n\nconfig = PoolConfig(\n    # Pool size limits\n    max_pool_size=10,                      # Maximum containers in pool\n    min_pool_size=2,                       # Minimum warm containers\n\n    # Timeout configuration\n    idle_timeout=300.0,                    # Recycle idle containers (seconds)\n    acquisition_timeout=30.0,              # Wait time for available container\n\n    # Health and lifecycle\n    health_check_interval=60.0,            # Health check frequency\n    max_container_lifetime=3600.0,         # Max container lifetime\n    max_container_uses=100,                # Max uses before recycling\n\n    # Pool exhaustion behavior\n    exhaustion_strategy=ExhaustionStrategy.WAIT,  # WAIT, FAIL_FAST, or TEMPORARY\n\n    # Pre-warming\n    enable_prewarming=True,                # Pre-warm containers\n)\n\npool = create_pool_manager(\n    backend=\"docker\",\n    config=config,\n    lang=\"python\",\n    libraries=[\"requests\", \"numpy\"],       # Pre-install libraries\n)\n```\n\n### Pool Exhaustion Strategies\n\nWhen all containers are busy, the pool can handle it in different ways:\n\n#### 1. WAIT (Default)\nWait for a container to become available:\n```python\nconfig = PoolConfig(\n    max_pool_size=5,\n    exhaustion_strategy=ExhaustionStrategy.WAIT,\n    acquisition_timeout=30.0,  # Wait up to 30 seconds\n)\n```\n\n#### 2. FAIL_FAST\nImmediately raise an error:\n```python\nconfig = PoolConfig(\n    max_pool_size=5,\n    exhaustion_strategy=ExhaustionStrategy.FAIL_FAST,\n)\n```\n\n#### 3. TEMPORARY\nCreate a temporary container outside the pool:\n```python\nconfig = PoolConfig(\n    max_pool_size=5,\n    exhaustion_strategy=ExhaustionStrategy.TEMPORARY,\n)\n```\n\n### Monitoring Pool Statistics\n\n```python\nfrom llm_sandbox.pool import create_pool_manager\n\npool = create_pool_manager(backend=\"docker\", lang=\"python\")\n\n# Get pool statistics\nstats = pool.get_stats()\nprint(f\"Total containers: {stats['total_size']}\")\nprint(f\"Idle containers: {stats['state_counts']['idle']}\")\nprint(f\"Busy containers: {stats['state_counts']['busy']}\")\n\npool.close()\n```\n\n### Artifact Extraction with Pooling\n\nFor capturing plots and visualizations with container pooling, you can use either approach:\n\n```python\nfrom llm_sandbox import ArtifactSandboxSession\nfrom llm_sandbox.pool import create_pool_manager, PoolConfig\nimport base64\nfrom pathlib import Path\n\n# Create pool with pre-installed visualization libraries\npool = create_pool_manager(\n    backend=\"docker\",\n    config=PoolConfig(max_pool_size=5, min_pool_size=2),\n    lang=\"python\",\n    libraries=[\"matplotlib\", \"numpy\"],\n)\n\ntry:\n    # Option 1: Use pool parameter (recommended for API consistency)\n    with ArtifactSandboxSession(pool=pool, enable_plotting=True) as session:\n        result = session.run(\"\"\"\nimport matplotlib.pyplot as plt\nimport numpy as np\n\nx = np.linspace(0, 10, 100)\ny = np.sin(x)\nplt.plot(x, y)\nplt.title('Pooled Execution - Sine Wave')\nplt.show()\n        \"\"\")\n\n        # Save generated plots\n        for i, plot in enumerate(result.plots):\n            Path(f\"plot_{i}.{plot.format.value}\").write_bytes(\n                base64.b64decode(plot.content_base64)\n            )\n\n        print(f\"Generated {len(result.plots)} plots using pooled container\")\n\n    # Option 2: Use ArtifactPooledSandboxSession (explicit class)\n    # Both approaches work identically\n    from llm_sandbox.pool import ArtifactPooledSandboxSession\n\n    with ArtifactPooledSandboxSession(pool_manager=pool, enable_plotting=True) as session:\n        result = session.run(\"print('Same functionality, different API')\")\n\nfinally:\n    pool.close()\n```\n\n### Examples\n\nSee the `examples/` directory for complete demonstrations:\n- [pool_basic_demo.py](examples/pool_basic_demo.py) - Basic pool usage and configuration\n- [pool_concurrent_demo.py](examples/pool_concurrent_demo.py) - Concurrent execution patterns\n- [pool_monitoring_demo.py](examples/pool_monitoring_demo.py) - Health monitoring and lifecycle management\n- [pool_artifact_demo.py](examples/pool_artifact_demo.py) - Artifact extraction with pooling (plots, CSV, mixed artifacts)\n\n## 🤖 LLM Framework Integration\n\n### LangChain Tool\n\n```python\nfrom langchain.tools import BaseTool\nfrom llm_sandbox import SandboxSession\n\nclass PythonSandboxTool(BaseTool):\n    name = \"python_sandbox\"\n    description = \"Execute Python code in a secure sandbox\"\n\n    def _run(self, code: str) -\u003e str:\n        with SandboxSession(lang=\"python\") as session:\n            result = session.run(code)\n            return result.stdout if result.exit_code == 0 else result.stderr\n```\n\n### Use with OpenAI Functions\n\n```python\nimport openai\nfrom llm_sandbox import SandboxSession\n\ndef execute_code(code: str, language: str = \"python\") -\u003e str:\n    \"\"\"Execute code in a secure sandbox environment.\"\"\"\n    with SandboxSession(lang=language) as session:\n        result = session.run(code)\n        return result.stdout if result.exit_code == 0 else result.stderr\n\n# Register as OpenAI function\nfunctions = [\n    {\n        \"name\": \"execute_code\",\n        \"description\": \"Execute code in a secure sandbox\",\n        \"parameters\": {\n            \"type\": \"object\",\n            \"properties\": {\n                \"code\": {\"type\": \"string\", \"description\": \"Code to execute\"},\n                \"language\": {\"type\": \"string\", \"enum\": [\"python\", \"javascript\", \"java\", \"cpp\", \"go\", \"r\"]}\n            },\n            \"required\": [\"code\"]\n        }\n    }\n]\n```\n\n## 🔌 Model Context Protocol (MCP) Server\n\nLLM 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.\n\n### Features\n\n- **Secure Code Execution**: Execute code in isolated containers with your preferred backend\n- **Multi-Language Support**: Run Python, JavaScript, Java, C++, Go, R, and Ruby code\n- **Automatic Visualization Capture**: Automatically capture and return plots and visualizations\n- **Library Management**: Install packages and dependencies on-the-fly\n- **Flexible Backend Support**: Choose from Docker, Podman, or Kubernetes backends\n\n### Installation\n\nInstall LLM Sandbox with MCP support using your preferred backend:\n\n```bash\n# For Docker backend\npip install 'llm-sandbox[mcp-docker]'\n\n# For Podman backend\npip install 'llm-sandbox[mcp-podman]'\n\n# For Kubernetes backend\npip install 'llm-sandbox[mcp-k8s]'\n```\n\n### Configuration\n\nAdd the following configuration to your MCP client (e.g., `claude_desktop_config.json` for Claude Desktop):\n\n```json\n{\n  \"mcpServers\": {\n    \"llm-sandbox\": {\n      \"command\": \"python3\",\n      \"args\": [\"-m\", \"llm_sandbox.mcp_server.server\"],\n    }\n  }\n}\n```\n\n#### Backend-Specific Configuration\n\nFor 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.\n\n**Docker (default):**\n```json\n{\n  \"mcpServers\": {\n    \"llm-sandbox\": {\n      \"command\": \"python3\",\n      \"args\": [\"-m\", \"llm_sandbox.mcp_server.server\"],\n      \"env\": {\n        \"BACKEND\": \"docker\",\n        \"DOCKER_HOST\": \"unix:///var/run/docker.sock\" // change this to the actual host you are using\n      }\n    }\n  }\n}\n```\n\n**Podman:**\n```json\n{\n  \"mcpServers\": {\n    \"llm-sandbox\": {\n      \"command\": \"python3\",\n      \"args\": [\"-m\", \"llm_sandbox.mcp_server.server\"],\n      \"env\": {\n        \"BACKEND\": \"podman\",\n        \"DOCKER_HOST\": \"unix:///var/run/podman/podman.sock\" // change this to the actual host you are using\n      }\n    }\n  }\n}\n```\n\nFor Kubernetes, you might need to set the `KUBECONFIG` environment variable to the path to your kubeconfig file.\n\n**Kubernetes:**\n```json\n{\n  \"mcpServers\": {\n    \"llm-sandbox\": {\n      \"command\": \"python3\",\n      \"args\": [\"-m\", \"llm_sandbox.mcp_server.server\"],\n      \"env\": {\n        \"BACKEND\": \"kubernetes\",\n        \"KUBECONFIG\": \"/path/to/kubeconfig\" // change this to the actual path to your kubeconfig file\n      }\n    }\n  }\n}\n```\n\n### Available Tools\n\nThe MCP server provides the following tools:\n\n- **`execute_code`**: Execute code in a secure sandbox with automatic visualization capture\n- **`get_supported_languages`**: Get the list of supported programming languages\n- **`get_language_details`**: Get detailed information about a specific language\n\n### Usage Example\n\nOnce configured, you can ask your AI assistant to run code, and it will automatically use the LLM Sandbox MCP server:\n\n```text\n\"Create a scatter plot showing the relationship between x and y data points using matplotlib\"\n```\n\nThe assistant will execute Python code in a secure sandbox and automatically capture any generated plots or visualizations.\n\n## 🏗️ Architecture\n\n```mermaid\ngraph LR\n    A[LLM Client] --\u003e B[LLM Sandbox]\n    B --\u003e C[Container Backend]\n\n    A1[OpenAI] --\u003e A\n    A2[Anthropic] --\u003e A\n    A3[Local LLMs] --\u003e A\n    A4[LangChain] --\u003e A\n    A5[LangGraph] --\u003e A\n    A6[LlamaIndex] --\u003e A\n    A7[MCP Clients] --\u003e A\n\n    C --\u003e C1[Docker]\n    C --\u003e C2[Kubernetes]\n    C --\u003e C3[Podman]\n\n    style A fill:#e1f5fe\n    style B fill:#f3e5f5\n    style C fill:#e8f5e8\n    style A1 fill:#fff3e0\n    style A2 fill:#fff3e0\n    style A3 fill:#fff3e0\n    style A4 fill:#fff3e0\n    style A5 fill:#fff3e0\n    style A6 fill:#fff3e0\n    style A7 fill:#fff3e0\n    style C1 fill:#e0f2f1\n    style C2 fill:#e0f2f1\n    style C3 fill:#e0f2f1\n```\n\n## 📚 Documentation\n\n- **[Full Documentation](https://vndee.github.io/llm-sandbox/)** - Complete documentation\n- **[Getting Started](https://vndee.github.io/llm-sandbox/getting-started/)** - Installation and basic usage\n- **[Configuration](https://vndee.github.io/llm-sandbox/configuration/)** - Detailed configuration options\n- **[Security](https://vndee.github.io/llm-sandbox/security/)** - Security policies and best practices\n- **[Backends](https://vndee.github.io/llm-sandbox/backends/)** - Container backend details\n- **[Languages](https://vndee.github.io/llm-sandbox/languages/)** - Supported programming languages\n- **[Integrations](https://vndee.github.io/llm-sandbox/integrations/)** - LLM framework integrations\n- **[API Reference](https://vndee.github.io/llm-sandbox/api-reference/)** - Complete API documentation\n- **[Examples](https://vndee.github.io/llm-sandbox/examples/)** - Real-world usage examples\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](https://vndee.github.io/llm-sandbox/contributing/) for details.\n\n### Development Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/vndee/llm-sandbox.git\ncd llm-sandbox\n\n# Install in development mode\nmake install\n\n# Run pre-commit hooks\nuv run pre-commit run -a\n\n# Run tests\nmake test\n```\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🌟 Star History\n\nIf you find LLM Sandbox useful, please consider giving it a star on GitHub!\n\n## 📞 Support \u0026 Community\n\n- **GitHub Issues**: [Report bugs or request features](https://github.com/vndee/llm-sandbox/issues)\n- **GitHub Discussions**: [Join the community](https://github.com/vndee/llm-sandbox/discussions)\n- **PyPI**: [pypi.org/project/llm-sandbox](https://pypi.org/project/llm-sandbox/)\n- **Documentation**: [vndee.github.io/llm-sandbox](https://vndee.github.io/llm-sandbox/)\n\n## Contributors\n\u003ca href=\"https://github.com/vndee/llm-sandbox/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contrib.rocks/image?repo=vndee/llm-sandbox\" /\u003e\n\u003c/a\u003e\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=vndee/llm-sandbox\u0026type=Date)](https://www.star-history.com/#vndee/llm-sandbox\u0026Date)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvndee%2Fllm-sandbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvndee%2Fllm-sandbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvndee%2Fllm-sandbox/lists"}