Browser Automation with Chrome and Playwright in Sandboxes

OpenSandbox supports two approaches to browser automation in isolated containers. The Chrome example launches a full Chromium instance with VNC access and the Chrome DevTools Protocol (CDP) exposed on port 9222, making it possible to connect any DevTools client or MCP tool directly to the browser. The Playwright example uses a prebuilt image with Chromium binaries and the Playwright Python library pre-installed, suitable for headless scraping, screenshot capture, and automated testing workflows.

Chrome (VNC + DevTools)
Playwright

The opensandbox/chrome image starts a VNC server (Xtigervnc :1) and launches Chromium with remote debugging enabled. Once the sandbox is running, you can connect a native VNC client to port 5901 or attach any CDP-compatible tool to port 9222.

Get the image

cd examples/chrome
docker build -t opensandbox/chrome .

Start the OpenSandbox server

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

Create and access the Chrome sandbox

uv pip install opensandbox
uv run python examples/chrome/main.py

import asyncio
from datetime import timedelta

from opensandbox.sandbox import Sandbox
from opensandbox.config import ConnectionConfig
from opensandbox.exceptions import SandboxException


async def main():
    try:
        sandbox = await Sandbox.create(
            image="opensandbox/chrome:latest",
            timeout=timedelta(minutes=5),
            entrypoint=["/entrypoint"],
            metadata={"examples.opensandbox.io": "chrome"},
            connection_config=ConnectionConfig(domain="localhost:8080"),
        )

        # Get the execd process endpoint
        execd = await sandbox.get_endpoint(44772)
        print(f"execd daemon running with {execd.endpoint}")

        vnc = await sandbox.get_endpoint(5901)
        print(f"VNC running with {vnc.endpoint}")

        devtools = await sandbox.get_endpoint(9222)
        print(f"DevTools running with {devtools.endpoint}/json")

    except SandboxException as e:
        print(f"Sandbox Error: [{e.error.code}] {e.error.message}")
    except Exception as e:
        print(f"Error: {e}")


if __name__ == "__main__":
    asyncio.run(main())

Expected output

execd daemon running with endpoint='127.0.0.1:48379/proxy/44772'
VNC running with endpoint='127.0.0.1:48379/proxy/5901'
DevTools running with endpoint='127.0.0.1:48379/proxy/9222'/json

Fetch the DevTools JSON endpoint to list open pages:

[
  {
    "description": "",
    "devtoolsFrontendUrl": "https://chrome-devtools-frontend.appspot.com/...",
    "id": "2215AF60AC345E4BA6D822389CFC743B",
    "title": "Google",
    "type": "page",
    "url": "https://www.google.com.hk/",
    "webSocketDebuggerUrl": "ws://127.0.0.1:52302/devtools/page/2215AF60AC345E4BA6D822389CFC743B"
  }
]

You can also connect the Chrome sandbox to an MCP client using chrome-devtools-mcp for agent-driven browser control.

The Playwright example uses a dedicated image with Chromium binaries, the Playwright Python package, Node.js (for Playwright MCP), and a non-root user (playwright) for security. The script launches Chromium in headless mode, scrapes the page title and body content, captures a full-page screenshot, and downloads it to the local working directory.

Build the Playwright image

cd examples/playwright
docker build -t opensandbox/playwright:latest .

Or pull the prebuilt image:

docker pull sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/playwright:latest

Start the OpenSandbox server

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

Create and access the Playwright sandbox

uv pip install opensandbox
uv run python examples/playwright/main.py

import asyncio
import os
from datetime import timedelta
from pathlib import Path

from opensandbox import Sandbox
from opensandbox.config import ConnectionConfig


async def _print_logs(label: str, execution) -> None:
    for msg in execution.logs.stdout:
        print(f"[{label} stdout] {msg.text}")
    for msg in execution.logs.stderr:
        print(f"[{label} stderr] {msg.text}")
    if execution.error:
        print(f"[{label} error] {execution.error.name}: {execution.error.value}")


async def main() -> None:
    domain = os.getenv("SANDBOX_DOMAIN", "localhost:8080")
    api_key = os.getenv("SANDBOX_API_KEY")
    image = os.getenv("SANDBOX_IMAGE", "opensandbox/playwright:latest")
    python_version = os.getenv("PYTHON_VERSION", "3.11")

    config = ConnectionConfig(
        domain=domain,
        api_key=api_key,
        request_timeout=timedelta(seconds=60),
    )

    # Inject Python version into container environment
    env = {"PYTHON_VERSION": python_version}
    sandbox = await Sandbox.create(
        image,
        connection_config=config,
        env=env,
    )

    async with sandbox:
        # Playwright and Chromium are pre-installed in the image
        browse_exec = await sandbox.commands.run(
            "python - <<'PY'\n"
            "import asyncio\n"
            "import os\n"
            "from pathlib import Path\n"
            "from playwright.async_api import async_playwright\n"
            "\n"
            "URL = os.environ.get('TARGET_URL', 'https://example.com')\n"
            "SCREENSHOT_PATH = Path('/home/playwright/screenshot.png')\n"
            "SCREENSHOT_PATH.parent.mkdir(parents=True, exist_ok=True)\n"
            "\n"
            "async def run():\n"
            "    async with async_playwright() as p:\n"
            "        browser = await p.chromium.launch(headless=True)\n"
            "        page = await browser.new_page()\n"
            "        await page.goto(URL, wait_until='networkidle')\n"
            "        title = await page.title()\n"
            "        content = await page.text_content('body')\n"
            "        await page.screenshot(path=str(SCREENSHOT_PATH), full_page=True)\n"
            "        print('title:', title)\n"
            "        print('screenshot saved at:', SCREENSHOT_PATH)\n"
            "        if content:\n"
            "            snippet = content.strip().replace('\\n', ' ')\n"
            "            print('content snippet:', snippet[:300])\n"
            "        await browser.close()\n"
            "\n"
            "asyncio.run(run())\n"
            "PY"
        )
        await _print_logs("browse", browse_exec)

        # Download screenshot from sandbox to local disk
        screenshot_remote = "/home/playwright/screenshot.png"
        screenshot_local = Path("screenshot.png")
        try:
            data = await sandbox.files.read_bytes(screenshot_remote)
            screenshot_local.write_bytes(data)
            print(f"\nDownloaded screenshot to: {screenshot_local.resolve()}")
        except Exception as e:
            print(f"\nFailed to download screenshot from {screenshot_remote}: {e}")

        await sandbox.kill()


if __name__ == "__main__":
    asyncio.run(main())

The screenshot is saved to ./screenshot.png in the local working directory after the run completes.

Basic Usage

AI Agent Integrations

Browser & Desktop

ML & Training

Browser Automation with Chrome and Playwright in Sandboxes

Get the image

Start the OpenSandbox server

Create and access the Chrome sandbox

Expected output

Build the Playwright image

Start the OpenSandbox server

Create and access the Playwright sandbox

References

Build docs developers (and LLMs) love

Basic Usage

AI Agent Integrations

Browser & Desktop

ML & Training

Documentation Index

​Get the image

​Start the OpenSandbox server

​Create and access the Chrome sandbox

​Expected output

​Build the Playwright image

​Start the OpenSandbox server

​Create and access the Playwright sandbox

​References

Build docs developers (and LLMs) love

Get the image

Start the OpenSandbox server

Create and access the Chrome sandbox

Expected output

Build the Playwright image

Start the OpenSandbox server

Create and access the Playwright sandbox

References