CodeBox-AI

What is CodeBox-AI?

CodeBox-AI is a secure, self-hosted Python code execution service built with FastAPI and IPython kernels. It provides a private alternative to OpenAI’s Code Interpreter or Anthropic’s Claude analysis tool, supports session-based code execution, and integrates with LLM function calling and the Model Context Protocol (MCP).

How to use CodeBox-AI?

Clone the repository, install dependencies with uv sync, and start the server with uv run -m codeboxai.main. Optionally run the MCP server standalone with uv run mcp dev mcp_server.py, register it with Claude Desktop via uv run mcp install mcp_server.py --name "CodeBox-AI", or start both FastAPI and MCP servers together with uv run run.py. Use the REST API endpoints (POST /sessions, POST /execute, etc.) or the MCP tools (execute_code, session://{session_id}, sessions://) for code execution.

Key features of CodeBox-AI

• Session-based Python code execution in Docker containers
• IPython kernel for rich output and plotting support
• Dynamic package installation with allowlist/blocklist and version controls
• State persistence between executions in the same session
• AST-based code security validation and dangerous import protection
• Host directory mounting with read-only or read-write access control

Use cases of CodeBox-AI

• Give an LLM (like Claude or GPT) a secure Python sandbox for data analysis
• Run multi-step computational workflows that keep variables across cells
• Allow users to safely execute untrusted code inside isolated Docker sessions
• Enable LLM applications to mount local directories for file processing tasks

FAQ from CodeBox-AI

What runtime dependencies does CodeBox-AI require?

Python 3.9+, Docker, and uv (fast package installer and resolver). For MCP or Claude Desktop integration, uv must be installed and configured.

How does CodeBox-AI keep code execution secure?

Code execution runs inside Docker containers – each session is isolated. The service implements AST-based code analysis, protection against dangerous imports and operations, basic resource limits, and a package allowlist/blocklist system.

Can I mount local directories into the execution environment?

Yes. You can specify mount points with host and container paths, set read-only or read-write access, and the service performs security validations to prevent access to sensitive paths. Mounting can be done via the API or environment variable CODEBOX_MOUNT_PATH.

Does CodeBox-AI support integration with Claude Desktop?

Yes. You can register the MCP server with Claude Desktop by installing it via uv run mcp install mcp_server.py --name "CodeBox-AI" and adding the server configuration to the Claude Desktop settings file (claude_desktop_config.json). The server then appears as a custom tool.

Is this code ready for production use?

No – the README explicitly states it is “a prototype implementation, not intended for production use without additional hardening.” It provides basic security and resource limits but should be reviewed and extended for production scenarios.