# 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, it is also well-suited for general-purpose code execution. Fully open-source and free to use, ipybox is 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**: Retains variable and session state across commands using IPython kernels.
- **Real-Time Output Streaming**: Streams execution outputs directly, enabling real-time feedback.
- **Enhanced Plotting Support**: Facilitates downloading plots created with Matplotlib and other libraries.
- **Flexible Dependency Management**: Supports installing and updating dependencies during runtime or at build time.
- **Resource Management**: Manages container lifecycle with built-in timeout and resource control mechanisms.
- **Reproducible Environments**: Provides a consistent execution setup across different systems to ensure reproducibility.
This project is in early beta, with active development of new features ongoing.
## Documentation
The official documentation is available [here](https://gradion-ai.github.io/ipybox/).
## Quickstart
Install `ipybox` Python package:
```bash
pip install ipybox
```
Build a `gradion-ai/ipybox` Docker image:
```bash
python -m ipybox build -t gradion-ai/ipybox
```
Print something inside `ipybox`:
```python
import asyncio
from ipybox import ExecutionClient, ExecutionContainer
async def main():
async with ExecutionContainer(tag="gradion-ai/ipybox") 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/).
## Development
Clone the repository:
```bash
git clone https://github.com/gradion-ai/ipybox.git
cd ipybox
```
Create a new Conda environment and activate it:
```bash
conda env create -f environment.yml
conda activate ipybox
```
Install dependencies with Poetry:
```bash
poetry install --with docs
```
Run tests:
```bash
pytest -s tests
```
Raw data
{
"_id": null,
"home_page": "https://github.com/gradion-ai/ipybox",
"name": "ipybox",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Martin Krasser",
"author_email": "martin@gradion.ai",
"download_url": "https://files.pythonhosted.org/packages/3d/f3/3b1f788539d78725eb5f2d91ef54ea7af052bbca1e1f6c66cb64a524f288/ipybox-0.2.3.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, it is also well-suited for general-purpose code execution. Fully open-source and free to use, ipybox is 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**: Retains variable and session state across commands using IPython kernels.\n- **Real-Time Output Streaming**: Streams execution outputs directly, enabling real-time feedback.\n- **Enhanced Plotting Support**: Facilitates downloading plots created with Matplotlib and other libraries.\n- **Flexible Dependency Management**: Supports installing and updating dependencies during runtime or at build time.\n- **Resource Management**: Manages container lifecycle with built-in timeout and resource control mechanisms.\n- **Reproducible Environments**: Provides a consistent execution setup across different systems to ensure reproducibility.\n\nThis project is in early beta, with active development of new features ongoing.\n\n## Documentation\n\nThe official 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\nBuild a `gradion-ai/ipybox` Docker image:\n\n```bash\npython -m ipybox build -t gradion-ai/ipybox\n```\n\nPrint something inside `ipybox`:\n\n```python\nimport asyncio\nfrom ipybox import ExecutionClient, ExecutionContainer\n\nasync def main():\n async with ExecutionContainer(tag=\"gradion-ai/ipybox\") 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\n## Development\n\nClone the repository:\n\n```bash\ngit clone https://github.com/gradion-ai/ipybox.git\ncd ipybox\n```\n\nCreate a new Conda environment and activate it:\n\n```bash\nconda env create -f environment.yml\nconda activate ipybox\n```\n\nInstall dependencies with Poetry:\n\n```bash\npoetry install --with docs\n```\n\nRun tests:\n\n```bash\npytest -s tests\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Python code execution sandbox based on IPython and Docker",
"version": "0.2.3",
"project_urls": {
"Homepage": "https://github.com/gradion-ai/ipybox"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "912ef65c969c5bd47aa7187121c45361b5b1b680616e48a4cf6ad336825ca161",
"md5": "af22d255988e250a6dfba8a664b4c60f",
"sha256": "7ceb6fc47124ae8666a4baab42f4c6cdcca41cec72cc38f23fa0bc58502fb8cd"
},
"downloads": -1,
"filename": "ipybox-0.2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "af22d255988e250a6dfba8a664b4c60f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.10",
"size": 15553,
"upload_time": "2024-12-19T06:19:14",
"upload_time_iso_8601": "2024-12-19T06:19:14.836199Z",
"url": "https://files.pythonhosted.org/packages/91/2e/f65c969c5bd47aa7187121c45361b5b1b680616e48a4cf6ad336825ca161/ipybox-0.2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3df33b1f788539d78725eb5f2d91ef54ea7af052bbca1e1f6c66cb64a524f288",
"md5": "e29f6b7b74d815e8360db90a07861fd9",
"sha256": "20b6db77fad9c2449a10863ec82bfc5c7ff138db40e3f25aa46392240b8990a5"
},
"downloads": -1,
"filename": "ipybox-0.2.3.tar.gz",
"has_sig": false,
"md5_digest": "e29f6b7b74d815e8360db90a07861fd9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.10",
"size": 13888,
"upload_time": "2024-12-19T06:19:17",
"upload_time_iso_8601": "2024-12-19T06:19:17.141090Z",
"url": "https://files.pythonhosted.org/packages/3d/f3/3b1f788539d78725eb5f2d91ef54ea7af052bbca1e1f6c66cb64a524f288/ipybox-0.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-19 06:19:17",
"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"
}