agent-browser

AI 에이전트를 위한 하드닝된 로컬 브라우저. 제로 의존성. 이미 설치된 Chrome을 DevTools Protocol로 구동하고, 토큰 효율적인 Markdown을 추출하며, 자동화로 쉽게 탐지되지 않습니다.

npx -y @truenix/agent-browser markdown https://news.ycombinator.com

모든 것이 로컬에서 실행됩니다. 계정, API 키, 원격 서비스, 할당량이 없습니다.

왜

에이전트에게 원시 HTML을 넣으면 대부분의 컨텍스트가 낭비됩니다. 실제 페이지에서 측정:

그리고 자동화라고 스스로 밝히는 브라우저는 차단되거나, 성능이 저하되거나, 다른 콘텐츠를 제공받습니다 — 이는 에이전트가 내린 결론을 조용히 오염시킵니다.

Related MCP server: Browser-MCP Navigator

설치

MCP 서버로

claude mcp add browser -- npx -y @truenix/agent-browser mcp

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": ["-y", "@truenix/agent-browser", "mcp"]
    }
  }
}

도구: browser_markdown, browser_text, browser_html, browser_links, browser_screenshot, browser_evaluate, browser_accessibility_tree, browser_pdf, browser_probe.

라이브러리로

npm install @truenix/agent-browser

import { withBrowser } from '@truenix/agent-browser';

const md = await withBrowser({}, async (session) => {
  await session.navigate('https://example.com');
  return session.markdown();
});

DSH / Cordis 플러그인으로

*한 줄 (권장 — DSH를 의도하면 자동 연결):*

npx -y @truenix/agent-browser install          # edits ~/.dsh/profiles/web/cordis.patch.yml + package.json, then pnpm install
# npx -y @truenix/agent-browser install --profile web --dry-run  # preview
# npx -y @truenix/agent-browser uninstall      # remove again

dsh를 재시작하면 — browser_markdown, browser_text, browser_links, browser_evaluate, browser_screenshot, browser_probe가 네이티브 도구로 나타납니다. 일반 npm install에서는 핸들러가 실행되지 않습니다. 의도적인 install이 필요합니다.

수동 (composition을 직접 편집하려는 경우):

npm i -g @truenix/agent-browser
# or inside the harness checkout: pnpm add @truenix/agent-browser

Node ≥ 18과 Chrome/Chromium 설치가 필요합니다. 그런 다음 호스트 composition에 추가하세요 (도구 레지스트리는 에이전트별이 아니라 호스트에 있습니다):

# ~/.dsh/profiles/web/cordis.patch.yml  — persists for every web session
- insert:
  - id: agent-browser
    name: '@truenix/agent-browser/cordis'
    config:
      timeoutMs: 180000   # per-tool call budget; default respects AGENT_BROWSER_BIN / ENDPOINT
      # cli: 'npx -y @truenix/agent-browser'  # override only if needed

짧은 형식 (composition이 이미 insert를 감싸는 경우):

- '@truenix/agent-browser/cordis':
    timeoutMs: 180000

환경 변수 오버라이드: AGENT_BROWSER_BIN (Chrome 바이너리), AGENT_BROWSER_ENDPOINT (--endpoint로 장기 실행 브라우저에 연결), 또는 config.cli.

CLI

agent-browser <command> [options]

  markdown <url>     Extract the page as Markdown (main content by default)
  text <url>         Visible text only
  html <url>         Full serialized DOM after JavaScript runs
  links <url>        Every anchor as JSON
  screenshot <url>   PNG/JPEG   (-o file, --full)
  pdf <url>          PDF        (-o file)
  a11y <url>         Filtered accessibility tree
  eval <url> <expr>  Evaluate JS in the page
  probe              Browser, GPU and capability report
  mcp                Run as an MCP server on stdio

옵션: --headful, --no-stealth, --block-images, --gpu/--no-gpu, --width, --height, --viewport WxH, --main, --raw, --full, --endpoint <ws>, --timeout, --json, -o.

--endpoint는 새 브라우저를 시작하는 대신 이미 실행 중인 브라우저에 연결합니다 — 많은 호출에서 단일 장기 실행 브라우저를 재사용하는 데 유용합니다.

봇 탐지

직접 실행: npm run test:bot. 최신 결과:

일반 headless Chrome은 sannysoft의 4개 행을 실패합니다 (HEADCHR_UA, CHR_MEMORY, WebGL SwiftShader, 이전 UA) 그리고 봇으로 보고됩니다.

도달할 수 없는 탐지기는 SKIP으로 계산되며, 통과로 계산되지 않습니다. 게이트는 3개의 도달 가능한 통과를 요구합니다 — 테스트 사이트가 다운된 날은 성공으로 오인될 수 없습니다.

환경이 패치보다 중요합니다

동일한 코드, 두 곳에서 측정:

모든 CDP 수준 신호는 둘 모두에서 깨끗합니다 — 그 부분은 코드이고, 코드는 옳습니다. 판정을 뒤집는 것은 환경입니다: 데이터센터 ASN과 소프트웨어 렌더링은 어떤 지문 패치로도 해결되지 않는 약한 신호 복합을 유발합니다.

이것이 문제의 정직한 형태입니다. 브라우저를 하드닝하면 사소한 신호를 제거합니다. 어디서 실행하느냐가 나머지를 결정합니다.

하드닝이 무엇을 하는지, 왜

모든 항목은 탐지기가 우리가 틀렸다고 알려준 데서 나왔습니다:

• --enable-automation 없음. 이 플래그 — Puppeteer와 Playwright가 추가하는 것 — 는 navigator.webdriver = true를 설정합니다. 원시 CDP는 설정하지 않으므로 패치 없이 false로 유지됩니다.

• Runtime.enable 없음. 이는 가장 큰 CDP 신호이며, 고전적인 console/Error.stack 탐지기를 구동합니다. Runtime.evaluate는 그것 없이도 잘 작동합니다.

• 창과 화면이 함께 움직입니다. --window-size를 --ozone-override-screen-size 없이 사용하면 outerWidth > screen.width가 되어 물리적으로 불가능합니다 — 일반 headless보다 더 강한 신호입니다.

• 기본 device-metrics 오버라이드 없음. 일반적인 1280×720은 Playwright의 기본 뷰포트이며, 탐지기가 이름으로 플래그합니다. 필요할 때만 --viewport를 설정하세요.

• 가능할 때 실제 GPU, 진짜 ANGLE (NVIDIA …) 렌더러를 SwiftShader 대신 제공합니다.

• UA는 CDP가 아닌 시작 시에 설정. Emulation.setUserAgentOverride는 Web Workers에 도달하지 않으므로, 페이지가 깨끗한 UA를 보고하는 동안 worker는 headless UA를 계속 보고합니다 (hasInconsistentWorkerValues).

• acceptLanguage 오버라이드 없음. CDP는 navigator.languages를 해당 헤더를 분할하여 파생하므로, "en-US,en;q=0.9"는 ["en-US","en;q=0.9"]가 됩니다 — q-값이 법적으로 존재할 수 없는 곳에서, 그리고 또 다른 페이지/worker 불일치입니다. --lang이 올바르게 수행합니다.

• Client Hints는 바이너리 자체 버전에서 파생되므로 Sec-CH-UA가 navigator.userAgent와 불일치할 수 없습니다.

• 세션당 격리된 브라우저 컨텍스트, 닫힘 시 폐기 — 두 번째 브라우저 프로세스 없이 작업당 깨끗한 상태.

반복되는 교훈: 일관성이 커버리지보다 중요합니다. 그 중 4개는 부분 스푸핑이 탐지를 더 쉽게 만든 경우이며, 실제 탐지기를 실행해야만 발견됩니다.

WebGL 스푸핑이 기본적으로 꺼져 있는 이유

spoofWebgl은 존재하고 신중하게 구현되었습니다 — 네이티브 getParameter 주위의 Proxy이므로 Function.prototype.toString은 여전히 [native code]를 보고합니다. 꺼져 있습니다. 측정이 역효과를 낸다고 말하기 때문입니다. test/webgl-spoof-experiment.mjs에서:

가지고 있지 않은 하드웨어를 주장하면 하나의 미용적 행을 고치고 복합 탐지기를 실패시킵니다: 주입된 스크립트는 Web Workers에 도달하지 않으므로 worker는 여전히 SwiftShader를 보고하고, MAX_TEXTURE_SIZE는 소프트웨어 값으로 유지되는 동안 렌더러 문자열은 개별 GPU를 주장합니다.

정직한 SwiftShader는 통과합니다. 설득력 있는 거짓말은 그렇지 않습니다. 대신 브라우저에 실제 GPU를 주세요 — 무료입니다.

이것이 하지 않는 것

지문 수준 탐지가 전체 범위입니다. 다음을 물리치지 않으며, 시도하지도 않습니다:

• TLS/JA3-JA4 및 HTTP/2 지문 — JavaScript가 실행되기 전에 결정됨

• IP 평판 — 데이터센터 vs 주거 ASN, 종종 실제 차단 요인

• 행동 분석 — 마우스 경로, 타이밍, 체류 시간

상용 챌린지 제품은 그것들에 의존하므로, "게이트 통과"는 자동화로 쉽게 플래그되지 않음을 의미하며, 탐지 불가능을 의미하지 않습니다. 자신의 사이트, 테스트, 접근성 작업, 그리고 일반적인 에이전트 브라우징을 위한 것입니다.

메모리

Chrome 스택은 약 450 MB를 소비합니다. 레버는 플래그가 아니라 아키텍처입니다: 작업당 하나의 브라우저가 아니라 하나의 브라우저와 많은 격리된 컨텍스트를 실행하세요. 브라우저를 한 번 시작한 다음 --endpoint / AGENT_BROWSER_ENDPOINT로 모든 호출을 가리키세요. --block-images는 텍스트 작업에 도움이 됩니다.

제로 의존성

dependencies는 WebSocket 전송을 포함하여 비어 있습니다.

Node의 전역 WebSocket (WHATWG)은 요청 헤더를 보낼 수 없으며, 인증되거나 프록시된 CDP 엔드포인트에 필요합니다. undici는 독립적으로 가져올 수 없습니다. 그래서 src/ws.mjs는 node:http(s) 위에 RFC 6455를 직접 구현합니다 — 핸드셰이크, 마스킹, 연속 조각, 64비트 길이, ping/pong — CDP가 요구하는 모든 것입니다.

Markdown 변환기는 명시적 스택으로 DOM을 탐색하며, 중첩에 관계없이 JS 호출 깊이를 O(1)로 유지하고, 리프 수준 인라인 노드에 네이티브 innerText를 사용합니다. 이는 깊게 중첩된 문서에서 재귀 안전하고, 큰 페이지에서 훨씬 빠릅니다.

환경

요구 사항

Node ≥ 18과 Chrome/Chromium 설치. 빌드 단계 없음.

크레딧

이 프로젝트의 하드닝은 거의 전적으로 다른 사람들의 공개 탐지 연구에서 파생되었습니다 — CREDITS.md 참조. 특히 rebrowser-bot-detector, bot.sannysoft.com, deviceandbrowserinfo.com, 그리고 Camoufox에게 감사합니다.

라이선스

MIT