Browser Harness

LLM을 실제 Chrome/CDP에 얇게 연결하고 실행 중 helper를 스스로 고치게 하는 브라우저 harness

uv tool install --python 3.12 --upgrade --force browser-harness

Browser Harness는 LLM을 로컬 Chrome 또는 Browser Use Cloud에 CDP WebSocket으로 연결하는 Python harness입니다. helper와 domain skill을 축적해 브라우저 작업을 반복 학습하게 합니다.

판단

이럴 때 씁니다

  • 에이전트가 실제 로그인된 로컬 Chrome 프로필을 사용해 업무 사이트를 조작해야 할 때.
  • 브라우저 자동화 실패를 매번 프롬프트로 때우지 않고 helper/domain skill로 축적하고 싶을 때.
  • Codex나 Claude Code에 global skill로 브라우저 제어 절차를 상시 로드하고 싶을 때.
  • Browser Use Cloud 브라우저와 로컬 Chrome을 같은 harness 관점에서 다루고 싶을 때.

이럴 땐 쓰지 마세요

  • bot detection 회피를 위해 별도 stealth browser가 필요하면 camofox-browser가 더 직접적입니다.
  • 단순 스크린샷이나 E2E 테스트만 필요하면 Playwright나 Playwright MCP가 더 표준적입니다.
  • 개인 Chrome 프로필 접근을 에이전트에게 허용할 수 없는 보안 환경에는 맞지 않습니다.
  • 에이전트가 파일을 생성·수정하는 self-improving 구조를 review할 여력이 없으면 부담이 큽니다.

차별점

  • 브라우저와 에이전트 사이를 얇은 CDP harness로 둡니다. README는 one websocket to Chrome, nothing between이라는 구조를 강조합니다.
  • 에이전트가 실행 중 필요한 helper를 `agent-workspace/agent_helpers.py`에 작성하고 다음 실행에서 재사용하는 self-improving loop를 둡니다.
  • Codex global skill 또는 Claude Code import로 등록해 새 세션에서도 harness 사용법이 자동 로드되게 합니다.
  • 로컬 Chrome의 remote debugging과 Browser Use Cloud 브라우저를 모두 지원합니다. cloud 경로는 API key와 profile sync 흐름을 따로 둡니다.

워크플로

  1. 01저장소를 durable path에 clone하고 `uv tool install -e .`로 editable global tool로 설치합니다.
  2. 02Codex 또는 Claude Code에 `SKILL.md`를 global skill/import로 등록합니다.
  3. 03로컬 Chrome에서 remote debugging을 허용하거나 `BU_CDP_WS`/`BU_CDP_URL`로 원격 브라우저를 지정합니다.
  4. 04`browser-harness --doctor`로 연결 상태를 확인하고, 실제 작업 중 생성된 helper/domain skill 변경을 review합니다.

주요 명령

명령설명
git clone https://github.com/browser-use/browser-harness && cd browser-harness && uv tool install -e .durable checkout을 editable global tool로 설치합니다
command -v browser-harness설치된 CLI 경로를 확인합니다
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills/browser-harness" && ln -sf "$PWD/SKILL.md" "${CODEX_HOME:-$HOME/.codex}/skills/browser-harness/SKILL.md"Codex global skill로 등록합니다
browser-harness --doctor버전, 설치 모드, daemon, Chrome 연결 상태를 진단합니다

설정

BU_CDP_WS=wss://...
BU_CDP_URL=http://127.0.0.1:9222
BH_DOMAIN_SKILLS=1

함정

설치 전에 확인하세요

  • README는 `/tmp`가 아니라 `~/Developer/browser-harness` 같은 안정적인 경로에 clone하라고 권합니다. editable install이 checkout을 참조하기 때문입니다.
  • 로컬 Chrome은 `chrome://inspect/#remote-debugging`에서 remote debugging 허용이 필요하고, Chrome 144+에서는 attach 허용 팝업이 뜰 수 있습니다.
  • `browser-harness --update -y`는 editable clone에 uncommitted changes가 있으면 거부합니다.
  • 에이전트가 helper와 domain skill을 쓰는 구조라, 저장소 권한과 생성 파일 review 규칙을 정해야 합니다.

직접 써본 메모

Browser Harness는 브라우저 자동화를 “완성된 API 세트”보다 “에이전트가 고치며 자라는 얇은 연결층”으로 봅니다. helper가 없으면 에이전트가 helper를 쓰고, domain skill을 만들어 다음 작업에서 재사용한다는 설계가 일반 Playwright wrapper와 다릅니다.

실제 Chrome 프로필을 쓰는 업무 자동화에는 이 구조가 매력적입니다. 이미 로그인된 브라우저, 확장, 북마크, 세션을 쓸 수 있고, 필요하면 Browser Use Cloud로 원격 브라우저도 붙일 수 있습니다. Codex/Claude Code global skill 등록까지 포함해 에이전트 작업 습관에 깊게 들어오는 도구입니다.

대신 보안 경계는 더 신중해야 합니다. 실제 브라우저 프로필 접근은 민감하고, 에이전트가 helper 파일을 생성·수정하는 구조는 code review 대상입니다. 편의성만 보고 켜기보다 어떤 사이트와 계정에 허용할지 먼저 정해야 합니다.

비교

camofox-browser가 별도 Camoufox stealth browser 서버를 띄우는 방식이라면, Browser Harness는 내가 쓰는 Chrome 또는 Browser Use Cloud에 얇게 붙는 방식입니다. 실제 프로필과 로그인 상태가 중요하면 Browser Harness가 자연스럽고, anti-detection을 별도 브라우저 계층에서 풀어야 하면 camofox-browser가 더 맞습니다.

최근 변경

v0.1.8에서 Chromium 자동 시작, 기존 탭 재사용, 검사 탭 제한과 오류 메시지가 개선됐다.

공식 변경 내역