agno-opensandbox-toolkit

OpenSandbox support for the Agno agent framework.

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

Installation

# 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:

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

See the OpenSandbox docs for full setup instructions.

Quick Start

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 file.