jo-inc/camofox-browser

<div align="center"> <img src="fox.png" alt="camofox-browser" width="200" /> <h1>camofox-browser</h1> <p><strong>AI 에이전트를 위한 안티-탐지 브라우저 서버, Camoufox 기반</strong></p> <p> <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a> <a href="https://github.com/jo-inc/camofox-browser/stargazers"><img src="https://img.shields.io/github/stars/jo-inc/camofox-browser" alt="GitHub stars" /></a> <a href="https://www.npmjs.com/package/camofox-browser"><img src="https://img.shields.io/npm/v/camofox-browser" alt="npm version" /></a> <a href="https://github.com/jo-inc/camofox-browser/commits"><img src="https://img.shields.io/github/last-commit/jo-inc/camofox-browser" alt="GitHub last commit" /></a> </p> <p> <a href="https://camoufox.com">Camoufox</a>의 강력한 어깨 위에 서 있습니다 - C++ 수준에서 핑거프린트 스푸핑을 수행하는 Firefox 포크입니다. </p> </div>

<br/>

<a href="https://askjo.ai?ref=camofox"><img src="jo-logo.png" alt="Jo" width="80" height="80" align="left" /></a>

>

<a href="https://askjo.ai?ref=camofox"><strong>jo, 개인 AI 에이전트</strong></a> 팀이 제작했습니다. Mac의 절반과 전용 클라우드 머신에서 실행되며 유지보수가 필요 없습니다. macOS, Telegram, WhatsApp, 이메일에서 사용 가능합니다. <a href="https://askjo.ai?ref=camofox">베타 버전 무료 체험 -></a>

<br/>

git clone https://github.com/jo-inc/camofox-browser && cd camofox-browser
npm install && npm start
# -> http://localhost:9377

Why

AI 에이전트는 실제 웹을 탐색해야 합니다. Playwright는 차단됩니다. Headless Chrome은 핑거프린팅됩니다. 스텔스 플러그인은 그 자체로 핑거프린트가 됩니다.

Camoufox는 C++ 구현 수준에서 Firefox를 패치합니다 - navigator.hardwareConcurrency, WebGL 렌더러, AudioContext, 화면 지오메트리, WebRTC - 모두 JavaScript가 보기도 전에 스푸핑됩니다. 쉼(shim), 래퍼, 흔적이 없습니다.

이 프로젝트는 해당 엔진을 AI 에이전트를 위해 설계된 REST API로 감쌉니다: 비대한 HTML 대신 접근성 스냅샷, 클릭을 위한 안정적인 요소 참조, 일반 사이트를 위한 검색 매크로.

Features

• C++ Anti-Detection - Google, Cloudflare 및 대부분의 봇 탐지를 우회합니다.
• Element Refs - 안정적인 e1, e2, e3 식별자로 안정적인 상호작용을 제공합니다.
• Token-Efficient - 접근성 스냅샷은 원시 HTML보다 약 90% 더 작습니다.
• Runs on Anything - 지연 브라우저 실행 + 유휴 종료로 유휴 시 메모리를 약 40MB로 유지합니다. 나머지 스택과 상자를 공유하도록 설계되었습니다 -- Raspberry Pi, $5 VPS, 공유 인프라.
• Session Isolation - 사용자별로 별도의 쿠키/스토리지를 제공합니다.
• Cookie Import - 인증된 브라우징을 위해 Netscape 형식 쿠키 파일을 주입합니다.
• Proxy + GeoIP - 자동 로케일/시간대 설정과 함께 리지덴셜 프록시를 통해 트래픽을 라우팅합니다.
• Structured Logging - 프로덕션 관찰 가능성을 위해 요청 ID가 포함된 JSON 로그 라인을 제공합니다.
• YouTube Transcripts - yt-dlp를 통해 모든 YouTube 동영상에서 자막을 추출하며, API 키가 필요 없습니다.
• Search Macros - @googlesearch, @youtubesearch, @amazonsearch, @redditsubreddit 등 10개 이상의 매크로를 제공합니다.
• Snapshot Screenshots - 접근성 스냅샷과 함께 base64 PNG 스크린샷을 포함합니다.
• Large Page Handling - 오프셋 기반 페이지네이션으로 자동 스냅샷 잘라내기를 수행합니다.
• Download Capture - 브라우저 다운로드를 캡처하고 API를 통해 가져옵니다 (선택적으로 인라인 base64).
• DOM Image Extraction - <img> src/alt를 나열하고 선택적으로 인라인 데이터 URL을 반환합니다.
• Deploy Anywhere - Docker, Fly.io, Railway.
• VNC Interactive Login - noVNC를 통해 사이트에 시각적으로 로그인하고, 에이전트 재사용을 위해 스토리지 상태를 내보냅니다.
• OpenAPI Docs - /openapi.json에서 자동 생성된 스펙과 /docs에서 대화형 문서를 제공합니다.
• Structured Extract - POST /tabs/:tabId/extract는 x-ref를 통해 스냅샷 참조에 속성을 매핑하는 JSON Schema를 사용합니다.
• Session Tracing - 선택적 세션별 Playwright 트레이스 캡처 (스크린샷 + DOM 스냅샷 + 네트워크)와 트레이스 zip을 나열, 가져오기, 삭제하는 API 엔드포인트를 제공합니다.
• Telemetry - GitHub Issues를 통한 자동 익명화된 충돌/중단 텔레메트리. 어떤 사이트가 실패를 유발하는지와 일반적인 실패 패턴을 식별합니다. 개인 도메인은 HMAC-해시되고, 경로/매개변수는 제거되며, 토큰/IP는 수정됩니다. CAMOFOXCRASHREPORT_ENABLED=false로 옵트아웃할 수 있습니다.

Optional Dependencies

Docker 이미지에는 yt-dlp가 포함되어 있습니다. 로컬 개발의 경우 /youtube/transcript 엔드포인트를 위해 설치하세요. 없으면 엔드포인트는 느린 브라우저 기반 방식으로 대체됩니다.

Quick Start

OpenClaw Plugin

openclaw plugins install @askjo/camofox-browser

Tools: camofoxcreatetab | camofoxsnapshot | camofoxclick | camofoxtype | camofoxnavigate | camofoxscroll | camofoxscreenshot | camofoxclosetab | camofoxlisttabs | camofoximportcookies

Standalone

npm에서 실행:

npx @askjo/camofox-browser

또는 소스에서:

git clone https://github.com/jo-inc/camofox-browser
cd camofox-browser
npm install
npm start  # 첫 실행 시 Camoufox 다운로드 (~300MB)

기본 포트는 9377입니다. 모든 옵션은 Environment Variables를 참조하세요.

참고: postinstall 스크립트는 Camoufox 바이너리를 가져오기 전에 자체적으로 PLAYWRIGHTSKIPBROWSERDOWNLOAD를 해제합니다. 이 재정의가 없으면 내보낸 PLAYWRIGHTSKIPBROWSERDOWNLOAD=1 (Playwright가 시스템 Chrome을 사용하도록 구성된 경우 일반적)이 자동으로 바이너리 다운로드를 건너뛰고 런타임에 서버를 충돌시킵니다.

>

외부 Camoufox 실행 파일: npm install 전과 서버 시작 시 CAMOUFOXEXECUTABLE=/path/to/camoufox-bin을 설정하여 번들 다운로드를 건너뛰고 해당 실행 파일을 실행합니다. 호환성 별칭은 CAMOUFOXEXECUTABLEPATH 및 CAMOFOXEXECUTABLE_PATH입니다. 이는 /nix/store/.../camoufox-bin과 같은 NixOS 경로에 유용합니다. 실행 파일은 properties.json, version.json, fontconfig/를 포함하는 Camoufox 번들에서 가져와야 합니다.

>

에어갭 또는 사용자 정의 바이너리 관리: 이미 Camoufox 번들이 있는 경우 CAMOUFOXEXECUTABLE을 선호합니다. 그렇지 않으면 npm install --ignore-scripts (모든 종속성에 대해 라이프사이클 스크립트를 건너뜀 -- 가장 무딘 옵션) 또는 더 정교하게 npm install --omit=optional과 미러에 대한 수동 npx camoufox-js fetch 단계를 사용하여 자동 가져오기를 비활성화합니다. PLAYWRIGHTSKIPBROWSERDOWNLOAD=1 npm install은 더 이상 Camoufox 다운로드를 건너뛰지 않습니다 (postinstall이 로컬에서 env를 정리함). 이를 위해서는 --ignore-scripts 또는 CAMOUFOX_EXECUTABLE을 사용하세요.

Docker

포함된 Makefile은 CPU 아키텍처를 자동 감지하고 Docker 빌드 외부에서 Camoufox + yt-dlp 바이너리를 미리 다운로드하므로 재빌드가 빠릅니다 (~30초 vs ~3분).

# 빌드 및 시작 (M1/M2에서 aarch64, Intel에서 x86_64 자동 감지)
make up

# 컨테이너 중지 및 제거
make down

# 완전 재빌드 강제 (예: VERSION/RELEASE 업그레이드 후)
make reset

# 바이너리만 다운로드 (빌드 없이)
make fetch

# 아키텍처 또는 버전 명시적 재정의
make up ARCH=x86_64
make up VERSION=135.0.1 RELEASE=beta.24

Windows

Windows에서는 make를 사용할 수 없습니다. 대신 포함된 build.ps1 PowerShell 스크립트를 사용하세요:

# 빌드 및 시작.\build.ps1 up

# 컨테이너 중지 및 제거.\build.ps1 down

# 이미지만 빌드.\build.ps1 build

# 완전 재빌드 강제.\build.ps1 reset

# 바이너리만 다운로드 (빌드 없이).\build.ps1 fetch

# 아키텍처 재정의.\build.ps1 up -Arch x86_64.\build.ps1 up -Arch aarch64

참고: PowerShell 7+ (pwsh)를 권장하지만 powershell.exe (Windows PowerShell 5.1)도 작동합니다. 스크립트는 WSL2 백엔드가 있는 Docker Desktop for Windows가 필요합니다.

>

줄 끝: 이 프로젝트에는 .sh 파일에 대해 Unix (LF) 줄 끝을 강제하는 .gitattributes 파일이 포함되어 있습니다. 이미 리포지토리를 클론했고 docker build 중에 sh: not found 또는 set: Illegal option - 오류가 발생하면 다음을 실행하세요:

```powershell

Get-ChildItem -Recurse *.sh | ForEach-Object { (Get-Content $) -join "n" + "n" | Set-Content $ -NoNewline }

```

이렇게 하면 셸 스크립트가 LF 줄 끝으로 변환됩니다. 향후 클론은 .gitattributes 덕분에 자동으로 처리됩니다.

경고: docker build를 직접 실행하지 마십시오. Dockerfile은 바인드 마운트를 사용하여 dist/에서 미리 다운로드된 바이너리를 가져옵니다. 항상 make up (또는 make fetch 후 make build)을 사용하세요 -- 먼저 바이너리를 다운로드합니다.

Fly.io

Fly.io 또는 기타 원격 CI의 경우 바인드 마운트 대신 빌드 시 바이너리를 다운로드하는 Dockerfile이 필요합니다.

Railway

railway.toml이 포함되어 있습니다. Dockerfile.ci (빌드 시 바이너리 다운로드)를 사용하고 Railway의 PORT 환경 변수를 CAMOFOX_PORT에 자동으로 매핑합니다.

# Railway CLI 설치 후:
railway link
railway up

Railway 대시보드 또는 CLI를 통해 시크릿 설정:

railway variables set CAMOFOX_API_KEY="your-generated-key"

Usage

Cookie Import

브라우저에서 Camoufox로 쿠키를 가져와 LinkedIn, Amazon 등 사이트에서 대화형 로그인을 건너뜁니다.

Setup

1. 시크릿 키 생성:

# macOS / Linux
openssl rand -hex 32

2. OpenClaw 시작 전 환경 변수 설정:

export CAMOFOX_API_KEY="your-generated-key"
openclaw start

동일한 키가 플러그인 (요청 인증)과 서버 (요청 확인) 모두에서 사용됩니다. 둘 다 동일한 환경에서 실행됩니다 -- 한 번 설정하면 됩니다.

왜 env var인가? 키는 시크릿입니다. openclaw.json의 플러그인 구성은 일반 텍스트로 저장되므로 시크릿이 거기에 속하지 않습니다. 셸 프로필, systemd 유닛, Docker env 또는 Fly.io 시크릿에 CAMOFOXAPIKEY를 설정하세요.

쿠키 가져오기는 기본적으로 비활성화되어 있습니다. CAMOFOXAPIKEY가 설정되지 않으면 서버는 모든 쿠키 요청을 403으로 거부합니다.

3. 브라우저에서 쿠키 내보내기:

Netscape 형식 쿠키 파일을 내보내는 브라우저 확장 프로그램을 설치하세요 (예: Chrome/Firefox용 "cookies.txt"). 인증하려는 사이트의 쿠키를 내보냅니다.

4. 쿠키 파일 배치:

mkdir -p ~/.camofox/cookies
cp ~/Downloads/linkedin_cookies.txt ~/.camofox/cookies/linkedin.txt

기본 디렉토리는 ~/.camofox/cookies/입니다. CAMOFOXCOOKIESDIR로 재정의할 수 있습니다.

5. 에이전트에게 가져오기 요청:

Import my LinkedIn cookies from linkedin.txt

에이전트가 camofoximportcookies를 호출 -> 파일을 읽음 -> Bearer 토큰으로 서버에 POST -> 쿠키가 브라우저 세션에 주입됩니다. 이후 linkedin.com에 대한 camofoxcreatetab 호출은 인증된 상태로 수행됩니다.

How it works

~/.camofox/cookies/linkedin.txt          (Netscape 형식, 디스크에 저장)
        |
        v
camofox_import_cookies tool              (파일 파싱, 도메인별 필터링)
        |
        v  POST /sessions/:userId/cookies
        |  Authorization: Bearer <CAMOFOX_API_KEY>
        |  Body: { cookies: [Playwright cookie objects] }
        v
camofox server                           (유효성 검사, 정리, 주입)
        |
        v  context.addCookies(...)
        |
Camoufox browser session                 (인증된 브라우징)

• cookiesPath는 쿠키 디렉토리를 기준으로 확인되며, 외부로의 경로 탐색은 차단됩니다.
• 요청당 최대 500개 쿠키, 5MB 파일 크기 제한.
• 쿠키 객체는 Playwright 필드의 허용 목록으로 정리됩니다.

Session Persistence

기본적으로 camofox는 각 사용자의 쿠키와 localStorage를 ~/.camofox/profiles/에 유지합니다. 세션은 브라우저 재시작 후에도 유지됩니다 -- 한 번 로그인하면 (쿠키 또는 VNC를 통해) 이후 세션에서 인증된 상태가 자동으로 복원됩니다.

~/.camofox/
|-- cookies/          # 부트스트랩 쿠키 파일 (Netscape 형식)
\-- profiles/         # 유지된 세션