Metadata-Version: 2.4
Name: ipybox
Version: 0.6.3
Summary: Python code execution sandbox based on IPython and Docker
Author-email: Martin Krasser <martin@gradion.ai>, Christoph Stumpf <chris@gradion.ai>
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: <3.14,>=3.11
Requires-Dist: aiodocker<0.25,>=0.24.0
Requires-Dist: aiofiles<25,>=24.1.0
Requires-Dist: aiohttp<4,>=3.12.0
Requires-Dist: click<8.2.0
Requires-Dist: mcp<2,>=1.9.2
Requires-Dist: pillow<12,>=11.0.0
Requires-Dist: python-dotenv>=1.1.1
Requires-Dist: tornado<7,>=6.4.0
Requires-Dist: typer<0.13,>=0.12.5
Description-Content-Type: text/markdown

# ipybox

mcp-name: io.github.gradion-ai/ipybox

<p align="left">
    <a href="https://gradion-ai.github.io/ipybox/"><img alt="Website" src="https://img.shields.io/website?url=https%3A%2F%2Fgradion-ai.github.io%2Fipybox%2F&up_message=online&down_message=offline&label=docs"></a>
    <a href="https://pypi.org/project/ipybox/"><img alt="PyPI - Version" src="https://img.shields.io/pypi/v/ipybox?color=blue"></a>
    <a href="https://github.com/gradion-ai/ipybox/releases"><img alt="GitHub Release" src="https://img.shields.io/github/v/release/gradion-ai/ipybox"></a>
    <a href="https://github.com/gradion-ai/ipybox/actions"><img alt="GitHub Actions Workflow Status" src="https://img.shields.io/github/actions/workflow/status/gradion-ai/ipybox/test.yml"></a>
    <a href="https://github.com/gradion-ai/ipybox/blob/main/LICENSE"><img alt="GitHub License" src="https://img.shields.io/github/license/gradion-ai/ipybox?color=blueviolet"></a>
    <a href="https://pypi.org/project/ipybox/"><img alt="PyPI - Python Version" src="https://img.shields.io/pypi/pyversions/ipybox"></a>
</p>

`ipybox` is a lightweight and secure Python code execution sandbox based on [IPython](https://ipython.org/) and [Docker](https://www.docker.com/). You can run it locally on your computer or remotely in an environment of your choice. `ipybox` is designed for AI agents that need to execute code safely e.g. for data analytics use cases or executing code actions like in [`freeact`](https://github.com/gradion-ai/freeact/) agents.

<a href="https://glama.ai/mcp/servers/@gradion-ai/ipybox">
  <img width="380" height="200" src="https://glama.ai/mcp/servers/@gradion-ai/ipybox/badge" alt="ipybox MCP server" />
</a>

<p align="center">
  <img src="docs/img/logo.png" alt="logo">
</p>

## Features

- Secure code execution inside Docker containers
- [Restrict network access](https://gradion-ai.github.io/ipybox/examples/#restrict-network-access) with a configurable firewall
- Stateful code execution with IPython kernels
- Stream code execution output as it is generated
- Install Python packages at build time or runtime
- Return plots generated with visualization libraries
- Exposes an [MCP server](https://gradion-ai.github.io/ipybox/mcp-server/) interface for AI agent integration
- [Invocation of MCP servers](https://gradion-ai.github.io/ipybox/mcp-client/) via generated client code
- Flexible deployment options, local or remote
- `asyncio` API for managing the execution environment

## Documentation

- [User Guide](https://gradion-ai.github.io/ipybox/)
- [API Docs](https://gradion-ai.github.io/ipybox/api/execution_container/)

## MCP server

`ipybox` can be installed as [MCP server](https://gradion-ai.github.io/ipybox/mcp-server/).

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

## Python example

Install `ipybox` Python package:

```bash
pip install ipybox
```

Execute code in an `ipybox` container:

```python
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())
```
