https://github.com/gradion-ai/ipybox
A lightweight and secure Python code execution sandbox based on IPython and Docker
https://github.com/gradion-ai/ipybox
code-execution code-interpreter code-sandbox mcp mcp-client mcp-server python
Last synced: about 1 month ago
JSON representation
A lightweight and secure Python code execution sandbox based on IPython and Docker
- Host: GitHub
- URL: https://github.com/gradion-ai/ipybox
- Owner: gradion-ai
- License: apache-2.0
- Created: 2024-12-03T15:21:24.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-09-14T09:57:05.000Z (about 2 months ago)
- Last Synced: 2025-10-04T06:43:21.392Z (about 1 month ago)
- Topics: code-execution, code-interpreter, code-sandbox, mcp, mcp-client, mcp-server, python
- Language: Python
- Homepage: https://gradion-ai.github.io/ipybox/
- Size: 1.98 MB
- Stars: 40
- Watchers: 2
- Forks: 10
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-mcp-servers - **ipybox** - Python code execution sandbox based on IPython and Docker. Stateful code execution, file transfer between host and container, configurable network access. See ipybox MCP server for details. `file` `http` `docker` `ai` `git` (📦 Other)
README
# ipybox
mcp-name: io.github.gradion-ai/ipybox
`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.
## 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())
```