
CodeBox-AI
A secure Python code execution service designed to integrate with LLMs like GPT and Claude, providing a self-hosted alternative to OpenAI's Code Interpreter. Now with MCP server.
what is CodeBox-AI?
CodeBox-AI is a secure Python code execution service that provides a self-hosted alternative to OpenAI's Code Interpreter, designed to integrate seamlessly with large language models (LLMs) like GPT and Claude.
how to use CodeBox-AI?
To use CodeBox-AI, clone the repository, install dependencies, and start the server. You can then create sessions and execute Python code via API calls.
key features of CodeBox-AI?
- Session-based Python code execution in Docker containers
- IPython kernel for rich output support
- Dynamic package installation with security controls
- State persistence between executions
- Code security validation with AST-based analysis
- Support for plotting and visualization
- Integration with the Model Context Protocol (MCP) for LLM applications
use cases of CodeBox-AI?
- Running Python scripts in a secure, isolated environment.
- Integrating with LLMs for interactive coding sessions.
- Educational purposes for teaching Python programming.
FAQ from CodeBox-AI?
- Is CodeBox-AI secure?
Yes! Code execution is containerized using Docker, ensuring isolation and security.
- Can I use it for production?
It is a prototype implementation and not intended for production use without additional security measures.
- What are the prerequisites?
You need Python 3.9+, Docker, and the uv package for installation.
CodeBox-AI
A secure Python code execution service that provides a self-hosted alternative to OpenAI's Code Interpreter or Anthropic's Claude analysis tool. Built with FastAPI and IPython kernels, it supports session-based code execution and integrates with LLM function calling.
It also now supports the Model Context Protocol (MCP) for seamless integration with LLM applications.
Features
- Session-based Python code execution in Docker containers
- IPython kernel for rich output support
- Dynamic package installation with security controls
- Package allowlist/blocklist system
- Version control for security vulnerabilities
- Support for pip and conda installations
- State persistence between executions
- Support for plotting and visualization
- Code security validation
- AST-based code analysis
- Protection against dangerous imports and operations
- Support for Jupyter magic commands and shell operations
- Host directory mounting
- Mount local directories into the container
- Read-only or read-write access control
- Security validations to prevent access to sensitive paths
MCP Server (Model Context Protocol)
CodeBox-AI now supports the Model Context Protocol (MCP), allowing LLM applications (like Claude Desktop) to interact with your code execution service in a standardized way.
Running the MCP Server
You can run the MCP server in several ways:
-
Standalone (for MCP clients or Claude Desktop):
uv run mcp dev mcp_server.py
This starts the MCP server in development mode for local testing and debugging.
-
Register with Claude Desktop:
uv run mcp install mcp_server.py --name "CodeBox-AI"
This will make your server available to Claude Desktop as a custom tool.
-
Combined FastAPI + MCP server:
python run.py
This starts both the FastAPI API and the MCP server (MCP available at
/mcp
). -
MCP server only:
python run.py --mode mcp
MCP Features
execute_code
: Execute Python code and return resultssession://{session_id}
: Get info about a sessionsessions://
: List all active sessions
Example: Testing with MCP Inspector
- Start the MCP server:
uv run mcp dev mcp_server.py
- Open the MCP Inspector and connect to your local server.
Example: Registering with Claude Desktop
- Configure the MCP server in the Claude Desktop settings:
Edit the file ~/Library/Application Support/Claude/claude_desktop_config.json
. The following is an example configuration:
{
"mcpServers": {
"CodeBox-AI": {
"command": "uv",
"args": [
"run",
"--project",
"/Users/username/src/codebox-ai",
"/Users/username/src/codebox-ai/mcp_server.py",
"--mount",
"/Users/username/Downloads"
]
}
}
}
Unfortunately, all paths need to be absolute. This example shows how to mount the Downloads
directory into the container.
- Open Claude Desktop and the server should appear as a custom tool.
Prerequisites
- Python 3.9+
- Docker
- uv - Fast Python package installer and resolver
Installation
- Clone the repository:
git clone https://github.com/yourusername/codebox-ai.git
cd codebox-ai
- Install dependencies with uv:
# Install uv if you don't have it yet
curl -LsSf https://astral.sh/uv/install.sh | sh
# Create a virtual environment and install dependencies in one step
uv sync
# Or to install with development dependencies
uv sync --extra dev
- Start the server:
uv run -m codeboxai.main
The API will be available at http://localhost:8000
Development setup
For development, install with the development extras:
uv sync --extra "dev docs"
Docker "file not found" error
If you encounter a "file not found" DockerException
when running the server on MacOS, you might need to set the DOCKER_HOST
environment variable. First, find out which context you are using by running:
docker context ls
Then set the DOCKER_HOST
environment variable to the correct endpoint:
export DOCKER_HOST="unix:///Users/tconte/.docker/run/docker.sock"
Usage
Direct API Usage
- Create a new session:
curl -X POST http://localhost:8000/sessions \
-H "Content-Type: application/json" \
-d '{
"dependencies": ["numpy", "pandas"]
}'
- Execute code in the session:
curl -X POST http://localhost:8000/execute \
-H "Content-Type: application/json" \
-d '{
"code": "x = 42\nprint(f\"Value of x: {x}\")",
"session_id": "YOUR_SESSION_ID"
}'
- Check execution status:
curl -X GET http://localhost:8000/execute/YOUR_REQUEST_ID/status
- Get execution results:
curl -X GET http://localhost:8000/execute/YOUR_REQUEST_ID/results
- Execute more code in the same session:
curl -X POST http://localhost:8000/execute \
-H "Content-Type: application/json" \
-d '{
"code": "print(f\"x is still: {x}\")",
"session_id": "YOUR_SESSION_ID"
}'
- Create a session with mounted directories:
curl -X POST http://localhost:8000/sessions \
-H "Content-Type: application/json" \
-d '{
"execution_options": {
"mount_points": [
{
"host_path": "/Users/tconte/Downloads",
"container_path": "/data/downloads",
"read_only": true
}
],
"timeout": 300
}
}'
- Execute code that accesses mounted files:
curl -X POST http://localhost:8000/execute \
-H "Content-Type: application/json" \
-d '{
"code": "import os\nprint(\"Files in mounted directory:\")\nfor file in os.listdir(\"/data/downloads\"):\n print(f\" - {file}\")",
"session_id": "YOUR_SESSION_ID"
}'
OpenAI GPT Integration Example
- Create a
.env
file in the project root:
AZURE_OPENAI_ENDPOINT=https://xxx.cognitiveservices.azure.com/
AZURE_OPENAI_API_KEY=foo
AZURE_OPENAI_DEPLOYMENT=gpt-4o
OPENAI_API_VERSION=2024-05-01-preview
- Install additional requirements:
uv sync --extra "examples"
- Run the example:
uv run examples/example_openai.py
This will start an interactive session where you can chat with GPT-4 and have it execute Python code. The script maintains state between executions, so variables and imports persist across interactions.
API Endpoints
POST /sessions
- Create a new sessionPOST /execute
- Execute code in a sessionGET /execute/{request_id}/status
- Get execution statusGET /execute/{request_id}/results
- Get execution resultsDELETE /sessions/{session_id}
- Cleanup a session
Security Notes
- Code execution is containerized using Docker
- Each session runs in an isolated environment
- Basic resource limits are implemented
- Network access is available but can be restricted
- Input code validation is implemented for basic security
License
MIT License - See LICENSE file for details.
A Note on Authorship
This code was pair-programmed with Claude 3.5 Sonnet (yes, an AI helping to build tools for other AIs - very meta). While I handled the product decisions and architecture reviews, Claude did most of the heavy lifting in terms of code generation and documentation. Even this README was written by Claude, which makes this acknowledgment a bit like an AI writing about an AI writing about AI tools... we need to go deeper 🤖✨
Humans were (mostly) present during the development process. No AIs were harmed in the making of this project, though a few might have gotten slightly dizzy from the recursion.
A prototype implementation, not intended for production use without additional security measures.