# 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

```bash
# 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.

```bash
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:

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

```python
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.

```bash
pytest tests/
```