Ipybox

🚀 ipybox

ipybox is a lightweight and secure Python code execution sandbox built upon IPython and Docker. It offers the flexibility to run either locally on your computer or remotely in a preferred environment. Specifically designed for AI agents, ipybox enables safe code execution, which is particularly useful for data analytics scenarios or code execution actions, similar to those in freeact agents.

✨ Features

• Securely execute code within Docker containers.
• Restrict network access using a configurable firewall.
• Perform stateful code execution with IPython kernels.
• Stream the output of code execution as it is generated.
• Install Python packages either during the build process or at runtime.
• Return plots generated by visualization libraries.
• Provide an MCP server interface for AI agent integration.
• Invoke MCP servers through generated client code.
• Offer flexible deployment options, either locally or remotely.
• Provide an asyncio API for managing the execution environment.

📚 Documentation

• User Guide
• API Docs

📦 Installation as an MCP server

ipybox can be installed as an MCP server.

{
  "mcpServers": {
    "ipybox": {
      "command": "uvx",
      "args": ["ipybox", "mcp"]
    }
  }
}

💻 Usage Examples

Basic Usage

Install the ipybox Python package:

pip install ipybox

Execute code in an ipybox container:

import asyncio
from ipybox import ExecutionClient, ExecutionContainer

async def main():
    async with ExecutionContainer(tag="ghcr.io/gradion-ai/ipybox") as container:
        async with ExecutionClient(port=container.executor_port) as client:
            result = await client.execute("print('Hello, world!')")
            print(f"Output: {result.text}")

if __name__ == "__main__":
    asyncio.run(main())