Metadata-Version: 2.3
Name: agno-opensandbox-toolkit
Version: 0.1.0
Summary: OpenSandbox support for the Agno agent framework
Keywords: agno,opensandbox,sandbox,ai-agent,toolkit
Author: Valeryi Savich
Author-email: Valeryi Savich <relrin78@gmail.com>
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Requires-Dist: agno==2.5.16
Requires-Dist: opensandbox==0.1.7
Requires-Dist: opensandbox-code-interpreter==0.1.2 ; extra == 'code-interpreter'
Requires-Python: >=3.10, <4
Provides-Extra: code-interpreter
Description-Content-Type: text/markdown

# agno-opensandbox-toolkit

[![CI](https://github.com/Relrin/agno-opensandbox-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/Relrin/agno-opensandbox-toolkit/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/agno-opensandbox-toolkit)](https://pypi.org/project/agno-opensandbox-toolkit/)
[![Python](https://img.shields.io/pypi/pyversions/agno-opensandbox-toolkit)](https://pypi.org/project/agno-opensandbox-toolkit/)
[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)

[OpenSandbox](https://github.com/alibaba/OpenSandbox) support for the
[Agno](https://github.com/agno-agi/agno) agent framework.

Give your Agno agents the ability to execute shell commands, manage files, and run code
in secure, isolated OpenSandbox containers.

## Installation

```bash
# Base: shell commands + file operations
uv add agno-opensandbox-toolkit

# With code interpreter support (Python, JS, Java, Go, Bash)
uv add "agno-opensandbox-toolkit[code-interpreter]"
```

## Prerequisites

You need a running OpenSandbox server. The quickest way:

```bash
uv pip install opensandbox-server
opensandbox-server init-config ~/.sandbox.toml --example docker
opensandbox-server
```

See the [OpenSandbox docs](https://github.com/alibaba/OpenSandbox/blob/main/server/README.md)
for full setup instructions.

## Quick Start

```python
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno_opensandbox_toolkit import OpenSandboxTools

agent = Agent(
    name="Sandbox Agent",
    model=OpenAIChat(id="gpt-4o-mini"),
    tools=[OpenSandboxTools()],
    markdown=True,
)

agent.print_response("Create a file /tmp/hello.py that prints 'Hello from OpenSandbox!', then run it")
```

## Configuration

| Parameter | Env Variable | Default | Description |
|---|---|---|---|
| `domain` | `OPENSANDBOX_DOMAIN` | `localhost:8080` | OpenSandbox server address |
| `api_key` | `OPENSANDBOX_API_KEY` | `""` | API key for authentication |
| `protocol` | — | `http` | Connection protocol (`http` or `https`) |
| `image` | — | `ubuntu` | Container image |
| `timeout_minutes` | — | `10` | Sandbox TTL |
| `sandbox_env` | — | `{}` | Env vars inside sandbox |
| `sandbox_resources` | — | `None` | e.g. `{"cpu": "2", "memory": "4Gi"}` |
| `sandbox_entrypoint` | — | `None` | Custom entrypoint command list |
| `sandbox_metadata` | — | `None` | Metadata labels dict |
| `enable_code_interpreter` | — | `False` | Enable `run_code` tool |
| `persistent` | — | `True` | Reuse sandbox across calls |
| `sandbox_id` | — | `None` | Reconnect to existing sandbox |

## Available Tools

| Tool | Description |
|---|---|
| `run_shell_command` | Execute bash commands |
| `create_file` | Create/update files |
| `read_file` | Read file content |
| `list_files` | List directory contents |
| `delete_file` | Delete files/directories |
| `change_directory` | Change working directory |
| `get_sandbox_status` | Get sandbox info |
| `shutdown_sandbox` | Kill the sandbox |
| `run_code` | Execute code via interpreter (optional) |

## License

The project is published under the BSD 3-Clause license. For details see the [LICENSE](https://github.com/Relrin/agno-opensandbox-toolkit/blob/master/LICENSE) file.