Chrome Orchestrator

chrome-orchestrator는 헤드리스 브라우저 환경(특히 Arthur와 gloria-headless)에서 Docker 관리를 추상화하는 경량 Python SDK 및 CLI입니다.

오래 실행되는 백그라운드 데몬이 통합 HTTP 프록시 역할을 수행합니다. AI 에이전트가 브라우저 세션을 요청하면, 데몬은 요청된 Docker 컨테이너를 동적으로 생성하고 영구 저장소를 마운트하며 포트 3000의 무상태 HTTP/SSE MCP(Model Context Protocol) 엔드포인트를 끊김 없이 프록시합니다.

기능

• 데몬 프록시 아키텍처: 단일 통합 포트(기본값 3000)를 노출하고 MCP 트래픽을 동적으로 할당된 Docker 컨테이너(Arthur는 8000, Gloria는 8787 포트)로 프록시합니다.

• 에이전트 매니페스트: SDK가 환경 지침을 포함한 ContainerManifest를 반환하므로, AI 에이전트는 방금 프로비저닝한 환경의 기능을 자동으로 이해합니다.

• 영구 저장소: 로컬 디렉터리(~/.chrome-orchestrator/data/<image>)를 자동으로 마운트하여 브라우저 세션 간에 상태를 유지합니다.

• 능동 상태 모니터링: 데몬은 백그라운드에서 컨테이너 상태를 능동적으로 모니터링하고 응답이 없으면 재시작을 시도합니다.

Related MCP server: hronaut

환경

두 환경 모두 chrome 브라우저 객체를 사용하는 동일한 execute_python 도구를 제공하므로, AI 에이전트는 기본 백엔드에 관계없이 Python 코드를 자연스럽게 작성할 수 있습니다.

• Arthur(기본값): 정확한 DOM 충실도를 제공하는 순수하고 최소한의 Chromium 환경으로, CDP WebSocket을 통해 네이티브하게 상호작용합니다. 토큰 한도와 일반적인 브라우징에 적합합니다.

• Gloria-Headless: uBlock Origin Lite가 사전 구성된 환경으로, Chrome Bridge 확장(Native Messaging)을 통해 상호작용합니다. 실제 사용자 브라우저처럼 동작하므로 캡차 우회와 같은 "어려운 작업"에 사용합니다.

요구 사항

• Python 3.9 이상

• Docker 또는 Podman이 설치되어 실행 중이어야 합니다. Docker를 사용한다면 Docker 데몬(/var/run/docker.sock)에 접근할 수 있는 권한이 있는지 확인하세요. Podman은 rootful 소켓(unix:///run/podman/podman.sock)에 대한 네이티브 접근이 지원되며, 대체재로 자연스럽게 사용할 수 있습니다.

설치

# From PyPI
pip install chrome-orchestrator

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

# Or from source
pip install -e .

사용법

1. 데몬 시작하기

먼저 백그라운드 데몬 프록시를 시작하세요. CLI와 SDK가 작동하려면 이 서비스가 반드시 실행 중이어야 합니다.

uvx --from chrome-orchestrator orchestrator daemon

기본적으로 데몬은 http://0.0.0.0:3000에서 실행됩니다.

2. CLI 사용법

CLI를 통해 arthur 및 gloria 컨테이너를 관리할 수 있습니다.

# 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

up을 실행하면 오케스트레이터가 컨테이너를 프로비저닝하고 http://localhost:3000/arthur/mcp과 같은 정적 MCP HTTP URL을 출력하므로, 클라이언트를 그 주소로 연결할 수 있습니다.

3. Python SDK 사용법

AI 에이전트와 Python 스크립트는 SDK를 사용해 환경을 프로그램 방식으로 프로비저닝하고 종료할 수 있습니다.

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)

테스트

이 프로젝트는 테스트에 pytest를 사용합니다. 테스트는 가장 높은 접점(CLI와 SDK)을 대상으로 하며 HTTP 프록시 상호작용을 시뮬레이션합니다.

pytest tests/