CLAUDE.md · vndee/llm-sandbox

Sections

1. Project Overview
2. Core Architecture
3. Project Structure
4. Development Guidelines
5. Common Tasks for AI Assistants
6. Important Conventions
7. Integration Points
8. Performance Considerations
9. Security Best Practices
10. Debugging Tips
11. Common Pitfalls
12. Configuration Files
13. Recent Changes
14. Resources
15. Working with This Codebase
16. Questions to Ask
17. Contact

First lines (shown under the repo's MIT license)

# LLM Sandbox - AI Assistant Guide

This document provides context and guidance for AI assistants working with the LLM Sandbox codebase.

## Project Overview

**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 secure execution environments for AI-generated code while offering flexibility in container backends and comprehensive language support.

**Version:** 0.3.13
**License:** MIT
**Python Support:** 3.10+
**Documentation:** https://vndee.github.io/llm-sandbox/
**Repository:** https://github.com/vndee/llm-sandbox

## Core Architecture

### Key Components

1. **Session Management** (`llm_sandbox/session.py`)
   - `SandboxSession`: Basic code execution in isolated containers
   - `ArtifactSandboxSession`: Execution with automatic artifact capture (plots, visualizations)
   - `InteractiveSandboxSession`: Stateful sessions maintaining Python interpreter state
   - `create_session()`: Factory function for session creation

2. **Container Backends** (`llm_sandbox/docker.py`, `llm_sandbox/kubernetes.py`, `llm_sandbox/podman.py`)
   - Docker (default, most common)
   - Kubernetes (enterprise-grade orchestration)
   - Podman (rootless containers)

3. **Language Handlers** (`llm_sandbox/language_handlers/`)
   - Python (`python_handler.py`)
   - JavaScript/Node.js (`javascript_handler.py`)
   - Java (`java_handler.py`)
   - C++ (`cpp_handler.py`)
   - Go (`go_handler.py`)
   - R (`r_handler.py`)
   - Ruby (`ruby_handler.py`)

4. **Container Pooling** (`llm_sandbox/pool/`)
   - Pre-warmed container management for performance
   - Thread-safe concurrent execution
   - Configurable pool sizes and lifecycle management

5. **Security** (`llm_sandbox/security.py`)
   - Security policies and pattern matching
   - Code scanning for vulnerabilities
   - Resource limits and network isolation

6. **MCP Server** (`llm_sandbox/mcp_server/`)
   - Model Context Protocol integration
   - Enables Claude Desktop and other MCP clients to execute code

## Project Structure

```
llm-sandbox/
├── llm_sandbox/              # Main package
│   ├── __init__.py          # Public API exports
│   ├── session.py           # Session implementations
│   ├── docker.py            # Docker backend
│   ├── kubernetes.py        # Kubernetes backend
│   ├── podman.py            # Podman backend
│   ├── security.py          # Security policies
│   ├── interactive.py       # Interactive session support
│   ├── data.py              # Data models (ExecutionResult, PlotOutput)
│   ├── const.py             # Constants and enums
│   ├── exceptions.py        # Custom exceptions
│   ├── core/                # Core abstractions
│   │   ├── config.py        # Configuration models
│   │   ├── session_base.py  # Base session class
│   │   └── mixins.py        # Shared functionality
│   ├── language_handlers/   # Language-specific handlers
│   │   ├── base.py          # Base handler interface
│   │   ├── python_handler.py
│   │   ├── javascript_handler.py
│   │   ├── java_handler.py
│   │   ├── cpp_handler.py
│   │   ├── go_handler.py
│   │   ├── r_handler.py
│   │   ├── ruby_handler.py
│   │   └── artifact_detection/  # Plot/artifact detection
│   ├── pool/                # Container pooling
│   │   ├── base.py          # Base pool manager
│   │   ├── config.py        # Pool configuration
│   │   ├── docker_pool.py   # Docker pool implementation
│   │   ├── kubernetes_pool.py
│   │   ├── podman_pool.py
│   │   ├── session.py       # Pooled session wrapper
│   │   └── factory.py       # Pool factory
│   └── mcp_server/          # MCP integration
│       ├── server.py        # MCP server implementation
│       ├── types.py         # MCP data types
│       └── const.py         # MCP constants
├── tests/                   # Test suite
├── examples/                # Usage examples
├── docs/                    # Documentation source
├── pyproject.toml          # Project metadata and dependencies
├── README.md               # User-facing documentation
└── CLAUDE.md               # This file

```

## Development Guidelines

### Code Style

- **Formatter:** Ruff (line length: 120)
- **Type Checking:** Mypy with strict settings
- **Testing:** pytest with integration tests for backends
- **Pre-commit hooks:** Configured for automated checks

### Key Design Patterns

1. **Context Managers**: All sessions use context managers for proper resource cleanup
2. **Factory Pattern**: `create_session()` and `create_pool_manager()` for object creation
3. **Strategy Pattern**: Language handlers implement common interface
4. **Pool Pattern**: Container pooling for performance optimization

### Testing Strategy

- Unit tests for core logic
- Integration tests marked with `@pytest.mark.integration`
- Tests require Docker/Podman/Kubernetes depending on backend
- Run tests: `make test` or `pytest tests/`

## Common Tasks for AI Assistants

### Adding a New Language Handler

1. Create handler in `llm_sandbox/language_handlers/`
2. Inherit from `BaseLanguageHandler`
3. Implement required methods:
   - `prepare_code()`
   - `get_install_command()`
   - `get_execution_command()`
4. Register in `factory.py`
5. Add to `SupportedLanguage` enum in `const.py`
6. Add tests in `tests/`

### Improving Security Features

- Security patterns defined in `security.py`
- Code scanning happens before execution
- Add new patterns to `SecurityPattern` dataclass
- Test with `tests/test_security_*.py`

### Enhancing Container Pooling

- Pool managers in `llm_sandbox/pool/`
- Configuration in `pool/config.py`
- Three exhaustion strategies: WAIT, FAIL_FAST, TEMPORARY
- Thread-safe implementation required

### Adding MCP Tools

- MCP server in `llm_sandbox/mcp_server/server.py`
- Tools defined using MCP decorators
- Must handle async operations
- Test with MCP client (e.g., Claude Desktop)