# ipybox
`ipybox` is a lightweight, stateful and secure Python code execution sandbox built with [IPython](https://ipython.org/) and [Docker](https://www.docker.com/). Designed for AI agents that interact with their environment through code execution, like the [`freeact`](https://github.com/gradion-ai/freeact/) agent system, it is also well-suited for general-purpose code execution. `ipybox` is fully open-source and free to use, distributed under the Apache 2.0 license.
<p align="center">
<img src="docs/img/logo.png" alt="logo">
</p>
## Features
- **Secure Execution**: Executes code in isolated Docker containers, preventing unauthorized access to the host system
- **Stateful Execution**: Maintains variable and session state across commands using IPython kernels
- **Real-Time Output Streaming**: Provides immediate feedback through direct output streaming
- **Enhanced Plotting Support**: Enables downloading of plots created with Matplotlib and other visualization libraries
- **Flexible Dependency Management**: Supports package installation and updates during runtime or at build time
- **Resource Management**: Controls container lifecycle with built-in timeout and resource management features
- **Reproducible Environments**: Ensures consistent execution environments across different systems
## Documentation
The `ipybox` documentation is available [here](https://gradion-ai.github.io/ipybox/).
## Quickstart
Install `ipybox` Python package:
```bash
pip install ipybox
```
Execute Python code inside `ipybox`:
```python
import asyncio
from ipybox import ExecutionClient, ExecutionContainer
async def main():
async with ExecutionContainer(tag="ghcr.io/gradion-ai/ipybox:minimal") as container:
async with ExecutionClient(port=container.port) as client:
result = await client.execute("print('Hello, world!')")
print(f"Output: {result.text}")
if __name__ == "__main__":
asyncio.run(main())
```
Find out more in the [user guide](https://gradion-ai.github.io/ipybox/).
Raw data
{
"_id": null,
"home_page": "https://github.com/gradion-ai/ipybox",
"name": "ipybox",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.11",
"maintainer_email": null,
"keywords": null,
"author": "Martin Krasser",
"author_email": "martin@gradion.ai",
"download_url": "https://files.pythonhosted.org/packages/ae/c9/f86c07123f97e6a0e635ace9763ab8fe339bb939f6fa2b9ce49847f0cb39/ipybox-0.3.1.tar.gz",
"platform": null,
"description": "# ipybox\n\n`ipybox` is a lightweight, stateful and secure Python code execution sandbox built with [IPython](https://ipython.org/) and [Docker](https://www.docker.com/). Designed for AI agents that interact with their environment through code execution, like the [`freeact`](https://github.com/gradion-ai/freeact/) agent system, it is also well-suited for general-purpose code execution. `ipybox` is fully open-source and free to use, distributed under the Apache 2.0 license.\n\n<p align=\"center\">\n <img src=\"docs/img/logo.png\" alt=\"logo\">\n</p>\n\n## Features\n\n- **Secure Execution**: Executes code in isolated Docker containers, preventing unauthorized access to the host system\n- **Stateful Execution**: Maintains variable and session state across commands using IPython kernels\n- **Real-Time Output Streaming**: Provides immediate feedback through direct output streaming\n- **Enhanced Plotting Support**: Enables downloading of plots created with Matplotlib and other visualization libraries\n- **Flexible Dependency Management**: Supports package installation and updates during runtime or at build time\n- **Resource Management**: Controls container lifecycle with built-in timeout and resource management features\n- **Reproducible Environments**: Ensures consistent execution environments across different systems\n\n## Documentation\n\nThe `ipybox` documentation is available [here](https://gradion-ai.github.io/ipybox/).\n\n## Quickstart\n\nInstall `ipybox` Python package:\n\n```bash\npip install ipybox\n```\n\nExecute Python code inside `ipybox`:\n\n```python\nimport asyncio\nfrom ipybox import ExecutionClient, ExecutionContainer\n\nasync def main():\n async with ExecutionContainer(tag=\"ghcr.io/gradion-ai/ipybox:minimal\") as container:\n async with ExecutionClient(port=container.port) as client:\n result = await client.execute(\"print('Hello, world!')\")\n print(f\"Output: {result.text}\")\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\nFind out more in the [user guide](https://gradion-ai.github.io/ipybox/).\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Python code execution sandbox based on IPython and Docker",
"version": "0.3.1",
"project_urls": {
"Homepage": "https://github.com/gradion-ai/ipybox"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5c3b97d73ec1fe15a5ab3f5a2a0eb028b3071115b73b349339f5d3b5c8c97e62",
"md5": "d9e0bbd0a759daf86f1e9dd4003a8c3b",
"sha256": "de6eac10a71e02ea24166fcd592b54d1616d91b9e21f0d8ad1a47faedfcdf83d"
},
"downloads": -1,
"filename": "ipybox-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d9e0bbd0a759daf86f1e9dd4003a8c3b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.11",
"size": 16988,
"upload_time": "2025-01-12T16:38:16",
"upload_time_iso_8601": "2025-01-12T16:38:16.461897Z",
"url": "https://files.pythonhosted.org/packages/5c/3b/97d73ec1fe15a5ab3f5a2a0eb028b3071115b73b349339f5d3b5c8c97e62/ipybox-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "aec9f86c07123f97e6a0e635ace9763ab8fe339bb939f6fa2b9ce49847f0cb39",
"md5": "aaa871e72ec9dc410f184f42b8c8d6e1",
"sha256": "7f02dda90571ba41efdda5f946889bddeea5835d7026d9b051f95e31614739a6"
},
"downloads": -1,
"filename": "ipybox-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "aaa871e72ec9dc410f184f42b8c8d6e1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.11",
"size": 14625,
"upload_time": "2025-01-12T16:38:18",
"upload_time_iso_8601": "2025-01-12T16:38:18.432340Z",
"url": "https://files.pythonhosted.org/packages/ae/c9/f86c07123f97e6a0e635ace9763ab8fe339bb939f6fa2b9ce49847f0cb39/ipybox-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-12 16:38:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "gradion-ai",
"github_project": "ipybox",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "ipybox"
}
JSON
