agent-browser

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

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

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

이유

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

그리고 자동화임을 스스로 밝히는 브라우저는 차단되거나, 성능이 저하되거나, 다른 콘텐츠를 제공받게 됩니다. 이는 에이전트가 내린 결론을 조용히 왜곡합니다.

무거운 사이트 벤치마크 (실시간, curl vs markdown)

두 차트와 이 표의 기반 측정값은 npm run charts로 다시 생성할 수 있습니다. 이 명령은 실시간으로 측정한 후 agent-browser 자체를 사용하여 PNG를 그리므로, 이미지의 숫자가 코드가 생성하는 결과와 어긋날 수 없습니다.

같은 페이지에서 더 적은 토큰 사용

URL은 Wikipedia 기사에서 출력의 1/3, github.com/trending에서는 4/5를 차지합니다. 에이전트가 탐색보다는 읽기에 집중할 때는 URL을 제거하세요:

agent-browser markdown https://github.com/trending --links text      # 69 kB -> 13 kB
agent-browser markdown https://en.wikipedia.org/wiki/Rust --links relative

YC 체크당 토큰 비용 (HN + YC 블로그를 --links text로 읽음, 51.1k → 1.5k 토큰, +500 출력) — 2026년 8월 목록 가격: Anthropic Haiku 4.5 $1/$5, Sonnet 5 $3/$15, Opus 5 $5/$25 • OpenAI GPT-4o $2.50/$10, GPT-4o mini $0.15/$0.60

로드 후 렌더링되는 페이지

탐색은 load 이벤트를 기다리며, 폴링 루프와 고정 지연 대신 CDP 수명주기 이벤트로 구동됩니다. 실제 페이지에서 바이트 단위로 동일한 출력에 대해 2~3배 더 빠릅니다:

로드 이후에 콘텐츠가 도착하는 클라이언트 렌더링 앱은 더 큰 추측이 아닌 실제 신호가 필요합니다. 기존 250ms 대기로는 해당 콘텐츠도 놓쳤습니다:

agent-browser markdown https://some-spa.example --wait idle

Related MCP server: Browser-MCP Navigator

다른 하네스

프레임워크가 JSON Schema를 지원한다면, 이 프로젝트가 프레임워크의 존재를 알지 못해도 agent-browser를 구동할 수 있습니다. agent-browser tools는 필요한 형태로 카탈로그를 출력합니다:

agent-browser tools                     # MCP:       {name, description, inputSchema}
agent-browser tools --format openai     # OpenAI:    {type:"function", function:{...}}
agent-browser tools --format anthropic  # Anthropic: {name, description, input_schema}

그런 다음 각 도구는 하네스가 지원하는 방식으로 실행됩니다:

import { findTool, TOOLS } from '@truenix/agent-browser/tools';
import { withBrowser } from '@truenix/agent-browser';

// in-process: the harness can hold a CDP session
const tool = findTool('browser_markdown');
const text = await withBrowser({}, async (session) => {
  await session.navigate('https://example.com');
  return tool.run(session, { url: 'https://example.com', links: 'text' });
});

// out-of-process: the harness can only run a command (sandboxes, shells)
tool.cli({ url: 'https://example.com', links: 'text' });
// => ['markdown', 'https://example.com', '--links', 'text']

설치

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.

모든 표면은 하나의 공유 카탈로그에서 동일한 9개 도구를 노출하므로, CLI, MCP 서버, DSH 플러그인이 서로 어긋날 수 없습니다.

라이브러리로

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          # adds the bundle to ~/.dsh/profiles/web/package.json, then pnpm install (the mount ships in the package's own cordis.patch.yml layer)
# npx -y @truenix/agent-browser install --profile web --dry-run  # preview
# npx -y @truenix/agent-browser uninstall      # remove again

dsh를 재시작하면 9개의 browser_* 도구가 네이티브 도구로 나타납니다. 일반 npm install에서는 핸들러가 실행되지 않습니다. 의도적인 install이 필요합니다.

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

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

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

# ~/.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

짧은 형식 (구성이 이미 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 whole 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, return only its value (cheapest)
  probe              Browser, GPU and capability report
  mcp                Run as an MCP server on stdio
  tools              Print tool schemas (--format mcp|openai|anthropic)

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

읽기에는 markdown, 조회에는 eval

이 도구로 에이전트가 저지르는 가장 비싼 실수는 한 줄짜리 질문에 답하기 위해 전체 페이지를 렌더링하는 것입니다. 세 개의 무거운 페이지에 대한 세 가지 목표 질문은 eval로 235바이트가 들지만, Markdown으로는 77kB가 듭니다:

agent-browser eval https://github.com/trending \
  "JSON.stringify(Array.from(document.querySelectorAll('article h2 a')).slice(0,3).map(a=>a.innerText.trim()))"
# ["openai / codex","mattpocock / skills","affaan-m / ECC"]   -> 58 bytes

textContent가 아닌 innerText를 사용하세요. textContent는 원시 소스 공백을 그대로 반환합니다 ("openai /\n\n codex"); innerText는 실제 렌더링된 내용을 제공합니다 ("openai / codex"). 이를 잘못 이해한 에이전트는 전체 재시도 왕복을 지불하게 되며, 이는 절약한 바이트보다 훨씬 비쌉니다.

실제로 페이지를 읽거나, 요약하거나, 검색해야 할 때는 markdown을 사용하세요.

각 호출은 자체 브라우저를 시작합니다 (~1.4초). 연속으로 여러 번 조회할 때는 하나의 브라우저를 유지하고 --endpoint로 연결하세요. 동일한 세 질문은 콜드 스타트 3회에 5.9초, 웜 브라우저에 3.2초가 걸립니다.

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

메모리

Chrome의 최소 사용량은 아무것도 로드하기 전에 18개 프로세스에서 약 420MB PSS입니다. 이 최소값은 이 패키지가 아니라 Chrome의 것입니다. 플래그 조정은 약 5%만 움직이며, 더 줄이는 플래그(--enable-low-end-device-mode)는 24코어 옆에 navigator.deviceMemory: 2를 보고합니다. 이는 불가능한 머신이며, 브라우저가 플래그될 수 있는 바로 그런 불일치입니다. 따라서 해결책은 더 작은 브라우저가 아니라 더 적은 브라우저입니다.

MCP 서버는 하나의 브라우저를 유지하고 각 도구 호출에 자체 격리된 컨텍스트를 제공합니다. 세 개의 무거운 페이지를 동시에 가져올 때:

격리는 동일합니다. 호출별 브라우저 컨텍스트가 항상 이를 제공했기 때문입니다. 브라우저는 30초 유휴 후 종료됩니다 (AGENT_BROWSER_IDLE_MS, 0은 즉시 종료). 따라서 장기 실행 서버가 대화 사이에 420MB를 점유하지 않습니다. 웜 상태에서 반복 호출하면 시작을 건너뛰고 약 2배 빠르게 실행됩니다.

단점: 작업이 프로세스 트리를 공유하므로 브라우저 수준 충돌은 한 호출이 아니라 진행 중인 모든 작업을 중단시킵니다. 죽은 브라우저는 감지되어 다음 호출에서 다시 시작됩니다. 작업별 폭발 반경 격리가 필요하면 withBrowser를 사용하세요. 이는 각 호출에 자체 브라우저를 제공합니다.

import { withPooledSession, shutdownPool } from '@truenix/agent-browser/pool';

await withPooledSession({}, async (session) => {
  await session.navigate('https://example.com');
  return session.markdown();
});
await shutdownPool();   // or let it idle out

CLI의 경우 각 호출은 자체 프로세스이므로 재사용은 직접 유지하는 브라우저에 --endpoint를 지정하는 것을 의미합니다.

데몬: 모든 CLI 호출에 하나의 브라우저

각 CLI 호출은 자체 프로세스이므로 기본적으로 각각 자체 Chrome을 콜드 스타트합니다. 10개의 동시 호출은 10개의 브라우저를 의미합니다. --daemon은 대신 하나의 상주 브라우저를 공유하며, 각 호출은 여전히 자체 격리된 컨텍스트를 얻습니다:

agent-browser markdown https://example.com --daemon
agent-browser daemon --status
agent-browser daemon --stop

명령보다 오래 지속되는 백그라운드 프로세스를 시작하는 것은 요청할 가치가 있는 부작용이므로 옵트인입니다 (--daemon 또는 AGENT_BROWSER_DAEMON=1). 필요 시 시작되고 5분 유휴 후 종료됩니다 (AGENT_BROWSER_DAEMON_IDLE_MS). 환경 변수를 설정하면 MCP 서버도 해당 데몬으로 라우팅됩니다. 여러 MCP 클라이언트가 한 머신을 공유할 때 유용합니다.

--headful, --width, --height, --block-images, --gpu는 브라우저가 시작될 때 고정되므로 공유 브라우저는 이를 존중할 수 없습니다. 이 중 하나라도 전달하면 해당 호출은 조용히 자체 전용 브라우저를 얻고 stderr에 알립니다.

이를 중심으로 구축된 네 가지 실패 모드, 각각 테스트로 검증됨:

• 정확히 하나의 데몬. 10개의 동시 첫 호출자가 모두 하나를 생성합니다. 9개는 소켓 바인딩 경쟁에서 지고 아무것도 시작하지 않고 종료됩니다. 소켓 바인딩 자체가 잠금이므로 오래된 잠금 파일이 없습니다.

• 열린 소켓이 참조 카운트입니다. 클라이언트는 작업하는 동안 연결을 유지하므로 SIGKILL로 죽은 클라이언트도 해제됩니다. 커널이 소켓을 닫기 때문입니다. "해제 요청" 메시지는 참조를 영원히 누출했을 것입니다.

• 유휴 종료로 대화 사이에 ~420MB를 점유하지 않습니다.

• SIGKILL된 데몬은 아무것도 남기지 않습니다: 프로필 마커가 pid를 명명하므로 아래 정리가 다음 시작 시 브라우저를 회수합니다.

스스로 정리

모든 시작은 임시 프로필에 소유자 마커를 쓰고, 소유자가 죽은 프로필을 정리하여 여전히 연결된 브라우저를 종료합니다. SIGINT/SIGTERM/SIGHUP 핸들러와 결합하면:

그래서 하드 킬(hard kill)은 중단된 호출당 하나가 아니라 최대 하나의 유령 브라우저(stranded browser)만 남긴다. 동시 CLI 호출 10개를 반복해도 아무것도 남지 않는다. 살아있는 브라우저는 절대 정리되지 않는다 — 소유 프로세스가 여전히 실행 중이며, 귀속되지 않은 프로필은 아무도 열지 않고 60초 동안 유휴 상태가 될 때까지 그대로 둔다.

봇 탐지

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

일반 headless Chrome은 sannysoft의 4개 항목(HEADCHR_UA, CHR_MEMORY, WebGL SwiftShader, 이전 UA)에서 실패하며 봇으로 보고된다.

연결할 수 없는 탐지기는 통과가 아닌 SKIP으로 처리되며, 게이트는 연결 가능한 3개의 통과를 요구한다 — 따라서 테스트 사이트가 다운된 날이 성공으로 오인될 수 없다.

패치보다 환경이 더 중요하다

동일한 코드를 두 곳에서 측정한 결과:

모든 CDP 레벨 신호는 두 환경 모두에서 깨끗하게 유지된다 — 그 부분은 코드의 영역이고, 코드는 올바르다. 판정을 뒤집는 것은 환경이다: 데이터센터 ASN에 소프트웨어 렌더링이 더해지면, 어떤 지문 패치로도 해결되지 않는 약한 신호 복합(weak-signal composite)이 발동한다.

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

하드닝이 하는 일과 그 이유

모든 항목은 탐지기가 우리가 틀렸다고 알려준 데서 비롯되었다:

• --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 사용. SwiftShader 대신 진짜 ANGLE (NVIDIA …) 렌더러를 얻는다.

• UA는 CDP로만이 아니라 실행 시에 설정. Emulation.setUserAgentOverride는 Web Worker에 도달하지 않으므로, 페이지가 깨끗한 UA를 보고하는 동안 worker는 계속 headless UA를 보고하게 된다 (hasInconsistentWorkerValues).

• acceptLanguage 오버라이드 없음. CDP는 그 헤더를 분할하여 navigator.languages를 파생하므로, "en-US,en;q=0.9"는 ["en-US","en;q=0.9"]가 된다 — q-value가 법적으로 존재할 수 없는 형태이며, 또 다른 페이지/worker 불일치가 된다. --lang이 올바르게 처리한다.

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

• 세션별 격리된 브라우저 컨텍스트, 닫을 때 폐기 — 두 번째 브라우저 프로세스 없이 작업별로 깨끗한 상태를 유지한다.

반복되는 교훈: 커버리지보다 일관성이 중요하다. 위 네 가지는 부분적인 스푸핑이 탐지를 더 쉽게 만든 사례로, 실제 탐지기를 실행해야만 발견할 수 있었다.

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

spoofWebgl은 존재하며 신중하게 구현되어 있다 — 네이티브 getParameter를 감싸는 Proxy이므로 Function.prototype.toString은 여전히 [native code]를 보고한다. 측정 결과 역효과가 나기 때문에 꺼져 있다. test/webgl-spoof-experiment.mjs에서:

가지고 있지 않은 하드웨어를 주장하면 표면적인 한 줄은 고쳐지지만 복합 탐지기에서 실패한다: 주입된 스크립트는 Web Worker에 도달하지 않으므로 worker는 여전히 SwiftShader를 보고하고, 렌더러 문자열이 개별 GPU를 주장하는 동안 MAX_TEXTURE_SIZE는 소프트웨어 값에 머문다.

정직한 SwiftShader는 통과한다. 그럴듯한 거짓말은 통과하지 못한다. 대신 브라우저에 실제 GPU를 주어라 — 공짜다.

이것이 하지 않는 것

지문 레벨 탐지가 전체 범위다. 다음을 무력화하지 않으며, 시도하지도 않는다:

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

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

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

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

메모리

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

제로 의존성

dependencies는 비어 있으며 WebSocket 전송도 포함한다.

Node의 전역 WebSocket(WHATWG)은 요청 헤더를 보낼 수 없는데, 인증되거나 프록시된 CDP 엔드포인트에는 이것이 필요하며, undici는 단독으로 import할 수 없다. 그래서 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