jo-inc/camofox-browser

camofox‑browser – AI 에이전트를 위한 반 탐지 브라우저 서버

무엇인가요 – 특수하게 패치된 Firefox 빌드(Camoufox)를 실행하고 AI 에이전트가 봇으로 식별되지 않고 실제 웹을 탐색할 수 있도록 REST API를 노출하는 매우 작은 Node.js 서버입니다. 브라우저의 지문은 C++ 수준에서 가짜로 설정되므로, 사이트는 헤드리스 또는 인스트루먼트된 브라우저가 아니라 일반적인 Firefox로 인식합니다.

에이전트에게 왜 중요한가요 – 현대의 웹 스크래핑 도구(Playwright, 헤드리스 Chrome)는 Cloudflare, Google 등 다양한 봇 탐지 서비스에 의해 점점 더 차단되고 있습니다. camofox-browser는 다음을 통해 이 문제를 해결합니다:

• JavaScript 실행 전에 CPU 코어 수, WebGL, AudioContext, 화면 크기, WebRTC 등 저수준 속성을 가짜로 설정합니다.
• 접근성 스냅샷(페이지의 컴팩트하고 스크린 리더 친화적인 표현)을 제공하여, 원시 HTML보다 약 90% 작아져 LLM 기반 에이전트의 토큰 예산을 절약합니다.
• 안정적인 요소 참조(e1, e2, …)를 제공하여, 에이전트가 취약한 CSS/XPath 선택자에 의존하지 않고 신뢰할 수 있게 클릭하거나 입력할 수 있습니다.

주요 기능 (README에 설명됨)

기능	기능 설명
C++ 반 탐지	Firefox의 바이너리 수준에서 패치하여 Google, Cloudflare 및 대부분의 봇 탐지기를 우회합니다.
요소 참조	인터랙티브 요소에 대해 안정적인 짧은 ID를 반환하여 에이전트 명령을 결정론적으로 만듭니다.
토큰 효율적인 스냅샷	전체 HTML이 아닌 접근성 트리를 전송하여 페이로드 크기를 크게 줄입니다.
저자원 사용	지연 시작과 비활성 종료로 메모리 사용량을 약 40 MiB로 유지하며, 저가 VPS나 Raspberry Pi에서도 실행 가능합니다.
세션 격리 및 지속성	사용자별로 별도의 쿠키/저장소를 제공하며, ~/.camofox/profiles/에 선택적으로 지속 가능합니다.
쿠키 임포트	Netscape 형식의 쿠키 파일을 수락하여 에이전트가 기존 로그인(예: LinkedIn, Amazon)을 재사용할 수 있습니다.
파일 업로드	설정된 디렉터리에서 파일을 네이티브 OS 대화상자 없이 에이전트가 첨부할 수 있습니다.
프록시 + GeoIP	주거용 프록시를 통해 트래픽을 라우팅하며, 프록시 IP에 따라 로케일, 타임존, 지리적 위치를 자동으로 동기화합니다.
YouTube 자막	yt‑dlp를 통해 자막을 가져오며 API 키가 필요 없습니다.
검색 매크로	@google_search, @youtube_search, @amazon_search 등 내장된 단축키입니다.
스냅샷 스크린샷	접근성 스냅샷과 함께 base64 인코딩된 PNG를 반환합니다.
대규모 페이지 처리	오프셋 기반 페이지네이션으로 스냅샷을 자르며 응답을 관리 가능하게 유지합니다.
다운로드 캡처	브라우저가 다운로드한 파일을 캡처하고 API를 통해 이용 가능하게 하며, base64 인라인은 선택 사항입니다.
DOM 이미지 추출	<img> 소스/alt 텍스트 목록을 제공하고, data-URL 형식으로 반환할 수 있습니다.
어디서든 배포 가능	Docker, Fly.io, Railway, 또는 직접 npm start로 실행 가능합니다.
VNC 인터랙티브 로그인	NoVNC UI를 통해 사람이 시각적으로 로그인할 수 있으며, 결과 저장 상태를 에이전트가 재사용할 수 있습니다.
OpenAPI 문서	/openapi.json에 자동 생성된 사양과 /docs에 인터랙티브한 Swagger UI가 있습니다.
구조화 추출	/tabs/:tabId/extract에 JSON 스키마를 POST하여 필드를 스냅샷 참조(x‑ref)에 매핑합니다.
세션 트레이싱	선택적으로 각 세션마다 Playwright 트레이스(스크린샷, DOM, 네트워크)를 제공하며, zip 파일로 다운로드 가능합니다.
테레메트리	익명의 크래시/정지 보고는 Cloudflare Worker에 전송되어 GitHub 이슈가 생성되며, 비활성화 가능합니다.

실행 방법

1. 클론 및 설치

   git clone https://github.com/jo-inc/camofox-browser && cd camofox-browser
   npm install   # 첫 실행 시 Camoufox 바이너리 (~300 MiB) 다운로드
   npm start     # http://localhost:9377에서 리스닝
   

2. 옵션 – Docker (생산 환경 추천)

   make up            # 이미지 빌드, 바이너리 다운로드, 컨테이너 시작
   # 중지/제거
   make down
   

   Makefile은 CPU 아키텍처(x86_64 또는 aarch64)를 자동 감지하고, Camoufox + yt‑dlp를 미리 다운로드하여 빌드를 빠르게 합니다.
3. 설정 – 대부분의 동작은 환경 변수로 제어됩니다. 예:
   • CAMOFOX_API_KEY – 특권 엔드포인트(쿠키 임포트, VNC 로그인)에 필요한 비밀 토큰.
   • PROXY_HOST, PROXY_PORT, PROXY_USERNAME, PROXY_PASSWORD – 프록시 라우팅 활성화.
   • CAMOFOX_CRASH_REPORT_ENABLED=false – 테레메트리 비활성화.
   • CAMOFOX_EXECUTABLE – 직접 관리하는 경우 사전 다운로드한 Camoufox 바이너리 경로 지정.

일반적인 에이전트 워크플로우

1. 탭 생성 – POST /tabs에 {userId, sessionKey, url}를 전송하여 tabId를 반환받습니다.
2. 스냅샷 가져오기 – GET /tabs/:tabId/snapshot으로 접근성 트리와 base64 PNG를 반환받습니다.
3. 상호작용 – POST /tabs/:tabId/click, .../type, .../scroll 등을 사용하여 안정적인 ID(e1, e2)로 요소를 참조합니다.
4. 구조화된 데이터 추출 – 원하는 필드를 x‑ref ID에 매핑하는 JSON 스키마를 정의하고 /tabs/:tabId/extract에 POST합니다.
5. 종료 – DELETE /tabs/:tabId (또는 전체 세션 종료)로 리소스를 해제하고, 선택적으로 트레이스를 저장합니다.

통합 포인트

• OpenClaw 플러그인 – README에는 openclaw 플러그인(@askjo/camofox-browser)이 언급되어 있으며, HTTP 호출을 편리한 CLI 명령어(camofox_create_tab, camofox_click 등)로 래핑합니다. OpenClaw 에이전트 프레임워크를 이미 사용하는 개발자에게 유용합니다.
• 스탠드얼론 CLI – npx @askjo/camofox-browser로 리포지토리 클론 없이 서버를 실행할 수 있습니다.
• OpenAPI – 생성된 사양을 통해 어떤 언어로든 클라이언트 라이브러리를 생성할 수 있어, 커스텀 LLM 오케스트레이터에 쉽게 통합할 수 있습니다.

개발자 – 이 프로젝트는 사용자의 맥과 클라우드 머신에서 부분적으로 작동하는 개인용 AI 어시스턴트 "Jo"를 만든 팀이 유지 관리하고 있습니다. 동일한 팀이 기반의 지문 가짜 설정 Firefox 포크인 Camoufox도 개발했습니다.

---

TL;DR

• camofox‑browser = 지문 가짜 설정 Firefox(Camoufox)를 래핑한 가벼운 REST 인터페이스입니다.
• 블록되지 않고 오픈 웹을 탐색해야 하는 AI 에이전트를 위한 것입니다.
• 작고 구조화된 스냅샷, 안정적인 요소 ID, 쿠키 임포트, 프록시 지원, 선택적 트레이싱을 제공합니다.
• npm install && npm start 또는 Docker/Make로 설치; 환경 변수로 설정합니다.