Chrome Orchestrator

chrome-orchestrator is a lightweight Python SDK and CLI that abstracts away Docker management for headless browser environments, specifically Arthur and gloria-headless.

It runs a long-lived background daemon that acts as a unified HTTP proxy. AI agents request a browser session, and the daemon dynamically provisions the requested Docker container, mounts persistent storage, and seamlessly proxies the stateless HTTP/SSE MCP (Model Context Protocol) endpoints on port 3000.

Features

• Daemon Proxy Architecture: Exposes a single, unified port (3000 by default) and proxies MCP traffic to dynamically allocated Docker containers (port 8000 for Arthur, 8787 for Gloria).
• Agent Manifests: The SDK returns a ContainerManifest containing environmental instructions so AI agents automatically understand the capabilities of the environment they just provisioned.
• Persistent Storage: Automatically mounts a local directory (~/.chrome-orchestrator/data/<image>) to persist state across browser sessions.
• Active Health Monitoring: The daemon actively monitors container health in the background and attempts restarts if they become unresponsive.

Environments

Both environments expose the identical execute_python tool using the chrome browser object, allowing AI agents to seamlessly write Python code regardless of the underlying backend.

• Arthur (Default): A pure, minimal Chromium environment with exact DOM fidelity, interacting natively via CDP WebSockets. Optimal for token limits and standard browsing.
• Gloria-Headless: An environment pre-configured with uBlock Origin Lite that interacts via the Chrome Bridge extension (Native Messaging). Use this for "hard stuff" like captcha evasion, since it behaves more like a real user browser.

Requirements

• Python 3.9+
• Docker or Podman installed and running. For Docker, ensure permissions to access the Docker daemon (/var/run/docker.sock). For Podman, rootful socket access is supported natively (unix:///run/podman/podman.sock) as a seamless fallback.

Installation

# From PyPI
pip install chrome-orchestrator

# Or without installing via uvx
uvx --from chrome-orchestrator orchestrator <command>

# Or from source
pip install -e .

Usage

1. Start the Daemon

First, start the background daemon proxy. This service must be running for the CLI and SDK to work.

uvx --from chrome-orchestrator orchestrator daemon

By default, the daemon runs on http://0.0.0.0:3000.

2. CLI Usage

You can manage arthur and gloria containers via the CLI:

# Provision an Arthur container
uvx --from chrome-orchestrator orchestrator arthur up

# Stop an Arthur container
uvx --from chrome-orchestrator orchestrator arthur down

# Provision a Gloria-headless container
uvx --from chrome-orchestrator orchestrator gloria up

# Stop all running orchestrator containers
uvx --from chrome-orchestrator orchestrator down

When you run up, the orchestrator will provision the container and output a static MCP HTTP URL you can connect your client to, such as http://localhost:3000/arthur/mcp.

3. Python SDK Usage

AI agents and Python scripts can use the SDK to programmatically provision and tear down environments:

from chrome_orchestrator import sdk

# Provision the environment (defaults to Arthur)
manifest = sdk.up(sdk.ContainerImage.ARTHUR)

print(f"Connected! MCP URL: {manifest.mcp_url}")
print(f"Agent Instructions:\n{manifest.instructions}")

# Your automation/MCP client connects to `manifest.mcp_url` here...

# Tear down the session when finished
sdk.down(sdk.ContainerImage.ARTHUR)

Testing

The project uses pytest for testing. The tests target the highest seams (CLI and SDK) and simulate HTTP proxy interactions.

pytest tests/