Quick Start

Get up and running with AIO Sandbox in just a few minutes.

Prerequisites

  • Docker installed on your system
  • At least 2GB of available RAM

Installation

# Pull and run the latest version
docker run --rm -it -p 8080:8080 ghcr.io/agent-infra/sandbox:v1

Option 2: For Users in Mainland China

Use our China mirror for faster downloads:

docker run --rm -it -p 8080:8080 enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest

If port 8080 is occupied, map to a different port:

docker run --rm -it -p 3000:8080 ghcr.io/agent-infra/sandbox:v1
# Then access via http://localhost:3000

Welcome

After running the Docker command, you'll see the AIO Sandbox ASCII logo:

 █████╗ ██╗ ██████╗     ███████╗ █████╗ ███╗   ██╗██████╗ ██████╗  ██████╗ ██╗  ██╗
██╔══██╗██║██╔═══██╗    ██╔════╝██╔══██╗████╗  ██║██╔══██╗██╔══██╗██╔═══██╗╚██╗██╔╝
███████║██║██║   ██║    ███████╗███████║██╔██╗ ██║██║  ██║██████╔╝██║   ██║ ╚███╔╝
██╔══██║██║██║   ██║    ╚════██║██╔══██║██║╚██╗██║██║  ██║██╔══██╗██║   ██║ ██╔██╗
██║  ██║██║╚██████╔╝    ███████║██║  ██║██║ ╚████║██████╔╝██████╔╝╚██████╔╝██╔╝ ██╗
╚═╝  ╚═╝╚═╝ ╚═════╝     ╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝╚═════╝ ╚═════╝  ╚═════╝ ╚═╝  ╚═╝

🚀 AIO(All-in-One) Agent Sandbox Environment
📦 Image Version: 1.0.0.93
🌈 Dashboard: http://localhost:8080/index.html
🔌 MCP: http://localhost:8080/mcp
📚 Documentation: http://localhost:8080/v1/docs

1. Install SDK

Python
TypeScript
pip install agent-sandbox

2. Configure client

Python
from agent_sandbox import Sandbox

client = Sandbox(base_url="http://localhost:8080")

3. Interact with the sandbox

Interact with the sandbox with file, shell, browser, code execute.

Execute Shell

Python
Curl
shell_res = client.shell.exec_command(command="ls -la")
print(shell_res.data.output) # /home/gem

File

Python
Curl
file_res = client.file.read_file(file="/home/gem/.bashrc")
print(file_res.data.content) # export TERM=xterm-256color

Browser

Screenshot

Python
Curl
screenshot = client.browser.screenshot()
print(screenshot)

GUI Actions

Python
Curl
action_res = client.browser.execute_action_actions_post(
    request=Action_MoveTo(x=100, y=100)
)
print(action_res)

More action_type details can be found in this Browser.

Connect to the browser with CDP

Python
Curl
from playwright.sync_api import sync_playwright

browser_info = client.browser.get_browser_info()
cdp_url = browser_info.data.cdp_url
playwright = sync_playwright().start()
browser = playwright.chromium.connect_over_cdp(cdp_url)

Example

Convert a webpage to Markdown with embedded base64 screenshot:

Python
import asyncio
import base64
from playwright.async_api import async_playwright
from agent_sandbox import Sandbox


async def site_to_markdown():
    # initialize sandbox client
    c = Sandbox(base_url="http://localhost:8080")
    home_dir = c.sandbox.get_sandbox_context().home_dir

    # Browser: automation to download html
    async with async_playwright() as p:
        browser_info = c.browser.get_browser_info().data
        page = await (await p.chromium.connect_over_cdp(browser_info.cdp_url)).new_page(
            viewport={
                "width": browser_info.viewport.width,
                "height": browser_info.viewport.height,
            }
        )
        await page.goto("https://sandbox.agent-infra.com/", wait_until="networkidle")
        html = await page.content()
        screenshot_b64 = base64.b64encode(
            await page.screenshot(full_page=False, type='png')
        ).decode('utf-8')

    # Jupyter: Run code in sandbox to convert html to markdown
    c.jupyter.execute_jupyter_code(
        code=f"""
from markdownify import markdownify
html = '''{html}'''
screenshot_b64 = "{screenshot_b64}"

md = f"{{markdownify(html)}}\\n\\n![Screenshot](data:image/png;base64,{{screenshot_b64}})"

with open('{home_dir}/site.md', 'w') as f:
    f.write(md)

print("Done!")
"""
    )

    # BasH: execute command to list files in sandbox
    list_result = c.shell.exec_command(command=f"ls -lh {home_dir}")
    print(f"\nFiles in sandbox home directory:\n{list_result.data.output}")

    open("./output.md", "w").write(
        c.file.read_file(file=f"{home_dir}/site.md").data.content
    )

    return "./output.md"


if __name__ == "__main__":
    # Run the async function
    result = asyncio.run(site_to_markdown())
    print(f"\nMarkdown file saved at: {result}")

Access Points

Once running, you can access different interfaces:

ServiceURLDescription
API Documentationhttp://localhost:8080/v1/docsOpenAPI documentation
Dashboardhttp://localhost:8080/index.htmlDashboard
VNC Browserhttp://localhost:8080/vnc/index.html?autoconnect=trueRemote desktop with browser
Terminalhttp://localhost:8080/terminalTerminal interaction
Code Serverhttp://localhost:8080/code-server/VSCode Server
MCP Servershttp://localhost:8080/mcpModel Context Protocol Servers
Jupyterhttp://localhost:8080/jupyterVSCode Server

Getting Help

Ready to build something awesome? Let's dive deeper into the specific components!