Rotunda

에이전트에게 웹 브라우징 능력을 부여하는 것은 초능력을 주는 것과 같습니다. 거의 모든 것을 자동화할 수 있습니다. Rotunda는 처음부터 에이전트를 위해 구축된 브라우저입니다. Chrome을 직접 열어 사용할 때보다 Claude에서 더 많은 캡차(CAPTCHA)를 마주치는 것에 지쳤나요? Rotunda를 사용해 보세요.

<p align="center"> <a href="https://rotunda.sh/#demo"> <img src="docs/media/amazon-demo.png" alt="Rotunda Amazon demo" width="480" /> </a> <br /> <em><a href="https://rotunda.sh/#demo">데모를 확인해 보세요!</a></em> </p>

시작하기

uv를 사용하여 Python 프로젝트에 Rotunda를 설치한 다음, 최신 Rotunda 브라우저 빌드를 가져오세요:

uv add rotunda
uv run rotunda fetch

rotunda fetch는 사용 가능한 브라우저 릴리스를 동기화하고 활성 채널에 대한 최신 빌드를 설치합니다.

그 다음, Rotunda 런칭 헬퍼(launch helper)를 교체하고 NewContext로 컨텍스트(context)를 생성하여 Playwright에서 Rotunda를 사용하세요:

from playwright.sync_api import sync_playwright
from rotunda import NewBrowser, NewContext

...

에이전트 (Agent)

프로젝트에 먼저 추가하지 않고도 uvx를 사용하여 명령줄(command line)에서 직접 Rotunda를 구동할 수 있습니다. 에이전트 명령어는 브라우저 프로필(browser profiles), 데몬 세션(daemon sessions), 그리고 짧은 리소스 인덱스(resource indexes)를 ~/.rotunda 아래에 유지하므로, 나중에 uvx rotunda ... 호출 시 동일한 프로필에 연결할 수 있습니다.

이 명령어들의 이면에 있는 데몬(daemon), 리소스 인덱스(resource-index), 하트비트(heartbeat), 그리고 싱글톤 프로세스 모델(singleton process model)에 대해서는 Agent CLI Architecture를 참조하세요.
브라우저를 먼저 수동으로 실행한 다음 다른 로컬 프로세스에서 브라우저에 연결하는 방법에 대해서는 Remote Juggler를 참조하세요.

먼저 활성 브라우저 빌드를 설치하고 프로필을 생성하세요:

uvx rotunda fetch
uvx rotunda agent new-profile --name agent-demo

new-context에 프로필 이름을 전달하여 브라우저 컨텍스트를 생성한 다음, 출력된 페이지 인덱스를 탐색하세요. 아래의 페이지 번호는 예시입니다. 명령어를 통해 출력된 인덱스를 사용하세요:

uvx rotunda agent new-context agent-demo
uvx rotunda agent navigate 3 https://pierce.dev

요소 참조 (element refs)를 얻기 위해 페이지를 설명(describe)하세요:

uvx rotunda agent describe 3

해당 참조를 액션(actions)에 직접 사용하세요. 참조가 설명된 후에는 페이지 인덱스를 전달할 필요가 없습니다:

uvx rotunda agent click <ref>
uvx rotunda agent hover <ref>
uvx rotunda agent info <select-ref>
...

info는 하나의 요소에 대한 전체 속성(attributes), 상태(state), 경계(bounds), 그리고 선택 옵션(select options)을 출력합니다. select는 기본적으로 값(value)에 따라 드롭다운 옵션을 선택합니다. 더 편리한 경우 --by label 또는 --by index를 사용하세요. fill은 필드 내용을 교체하며, type은 포커스된 커서 위치에 내용을 추가합니다. 두 방식 모두 Rotunda의 인간화된 텍스트 입력 경로(humanized text input path)를 사용하며, 마우스 액션은 인간화(humanization)가 활성화되었을 때 Rotunda의 경로 예측(path prediction)을 사용합니다.

액션 수행 후, CLI는 페이지가 전체 새로고침(full refresh)되었는지 또는 대부분 그대로 유지되었는지 보고합니다. 페이지 내 업데이트(Same-page updates)는 압축된 +/- 요소 델타(element delta)를 출력합니다. 현재의 전체 DOM을 원할 때는 describe를 다시 실행하세요.

에이전트 CLI에는 폼(form) 형태가 아닌 작업을 위한 더 광범위한 브라우저 프리미티브(browser primitives)도 포함되어 있습니다:

uvx rotunda agent pages
uvx rotunda agent screenshot 3 --full-page
uvx rotunda agent wait 3 --for text "Done"
...

screenshot은 뷰포트(viewport), 전체 페이지, 또는 --element <ref>를 사용하여 설명된 하나의 요소를 캡처할 수 있습니다. 경로가 제공되지 않으면 시스템 임시 디렉토리에 무작위로 이름이 지정된 PNG 파일을 작성하고 절대 경로를 출력합니다. wait는 로드 상태(load states), URL 패턴, 가시적 텍스트(visible text), 셀렉터(selectors), 그리고 고정된 타임아웃(fixed timeouts)을 지원합니다. extract는 텍스트, HTML, 마크다운(markdown), 링크, 또는 폼 메타데이터(form metadata)를 반환할 수 있습니다. dialog는 페이지의 다음 브라우저 다이얼로그(browser dialog)를 어떻게 처리할지 설정합니다. 설정되지 않은(unarmed) 다이얼로그는 브라우저가 멈추지 않도록 닫히고 기록됩니다.

작업이 끝나면 프로필 데몬(profile daemon)을 중지하세요:

uvx rotunda agent stop 1

스텔스 브라우징(stealth browsing)에 대하여

웹 자동화(Web automation)는 놀랍습니다. 불행하게도, 과거에 너무 많은 사람들이 브라우저의 자동화 기능을 악용했기 때문에(티켓 되팔이, 신발 리셀러 등), 사이트들은 인간이 아닌 모든 것을 탐지하는 데 수십억 달러를 쏟아부었습니다. 만약 Playwright를 통해 CDP(Chrome DevTools Protocol) 위에서 Chrome을 실행해 본다면 제가 무슨 말을 하는지 알게 될 것입니다. reCAPTCHA가 나타나거나, 로그인이 거부되거나, 혹은 동작 방식이 미묘하게 변하는 것을 경험하게 됩니다.

"스텔스(Stealth)" 플러그인들은 이러한 탐지를 회피할 수 있다고 광고합니다. 하지만 모든 스텔스 플러그인에는 결함이 있습니다. 이들은 종종 다른 브라우저를 시뮬레이션하는 가짜 값을 반환하기 위해 JavaScript 속성(properties)을 재정의(overriding)하는 방식에 의존합니다. 지문 채취기(Fingerprinters)는 이러한 함수 구현이 네이티브(native)인지 비네이티브(non-native)인지 확인합니다. 실제 환경에서 비네이티브는 발생하지 않으므로 당신은 봇으로 분류됩니다. 다른 플러그인들은 Chromium을 포크(fork)하여 백엔드에서 동일한 작업을 수행하는 코드를 패치하며, 이 경우 JavaScript 상태를 스니핑(sniffing)하여 탐지할 수 없습니다. 그러면 지문 채취기들은 canvas나 오디오 드라이버와 같은 브라우저 액세서리를 사용하여 알려진 장치와의 이상 징후를 탐지합니다. 그리고 결국 당신은 봇으로 분류됩니다. 이런 식으로 계속됩니다.

이 쫓고 쫓기는 게임은 웹의 시작부터 존재해 왔습니다. 지문 채취(fingerprinting) 방식이 임시방편(adhoc)에서 통계적(statistical) 방식으로 전환됨에 따라, 그 부담은 스텔스 구현자들에게 급격히 전가되었습니다. Rotunda의 관점은 _브라우저 지문(browser fingerprint)에 대해 설득력 있게 거짓말을 하는 것은 불가능하다_는 것입니다. 대수의 법칙(law of large numbers)과 브라우저가 지원해야 하는 API의 표면적(surface area)을 고려할 때, 당신이 비정상적이라는 것을 탐지할 방법은 반드시 존재합니다. 사이트들은 당신이 전체 정체성을 속이고 있다는 것을 증명하기 위해 단 한 가지의 오류만 찾아내면 됩니다. 모든 표면적을 패치하고, 모든 GPU 드라이버의 미묘한 차이를 시뮬레이션해야 하는데, 솔직히 말해서 이는 충분히 해볼 만한 게임이 아닙니다.

대신 Rotunda는 자신의 근본적인 정체성을 속이지 않으면서도, 완전히 인간처럼 보이는 브라우저를 제공하는 데 집중합니다. 우리는 실제로 당신의 노트북에서 실행되고 있는 것처럼 보이기를 원하며, 대신 어떤 자동화 시그니처(automation signatures)도 탐지되지 않도록 만드는 데 집중합니다. 여기에는 Playwright가 화면을 제어하는 드라이버로 탐지되지 않도록 보장하는 것, 커서의 움직임이 마치 마우스를 움직이는 것처럼 보간(tween)되는 것, 그리고 키보드 클릭에 가끔씩 오류가 발생하는 것 등이 포함됩니다. 지문(fingerprint)에 대해 거짓말을 하는 대신, 약간의 허위 사실을 말하는 것이 더 낫습니다. 사용 중인 GPU와 오디오 드라이버가 무엇인지는 말해주되, 사용 가능한 폰트나 확장 프로그램, 또는 화면 크기와 같은 세부 사항에 대해서는 거짓말을 하는 식입니다. 10개의 M1 칩이 동시에 해당 사이트를 브라우징하는 것은 흔한 일이지만, Linux GPU가 macOS라고 주장하는 것은 불가능합니다.

그 결과, 이 브라우저는 크롤링(crawling)에는 적합하지 않습니다. 공개된 사이트의 경우, 어차피 Browserbase, Kernel, 또는 ScrapingBee를 통해 클라우드에서 자동화해야 합니다. 하지만 당신의 에이전트(Agents)에게 작업을 위임할 때는 매우 적합합니다. 마치 당신의 홈 네트워크에서 유용한 일을 수행하는 인턴 군단을 보유하는 것과 같습니다.

지문(Fingerprint)이 차단되었나요?

우리의 호스트 패스스루(host-passthrough) 접근 방식으로는 봇으로 플래그(flag)가 지정될 가능성이 훨씬 낮습니다. 하지만 그것이 불가능하다는 뜻은 아닙니다. 우선 동일한 사이트를 Chrome/Firefox에서 열어보고 여전히 플래그가 나타나는지 확인하는 것을 권장합니다. 만약 그렇다면, 그것은 당신의 IP 평판(IP reputation) 때문일 수 있습니다.

만약 다른 브라우저들은 정상적으로 작동하는데 Rotunda 수준의 문제라고 의심된다면, 저희의 디버깅 핸들러 (debugging handlers)를 사용하여 동일한 사이트를 실행해 보세요. 이는 사이트가 JavaScript VM으로 보내는 호출, 해당 호출의 반환 값 (return values), 콘솔 출력 (console output), 그리고 서버로 전송되는 외부 페이지 요청 (outgoing page requests)을 에코(echo)하여 보여줍니다. 99.99%의 경우, 이러한 페이로드 (payloads)를 통해 사이트가 무언가 비정상적인 요소를 감지했음을 알 수 있습니다. 이들이 실제로 다루지 않는 유일한 것은 TCP 핸드셰이크 (TCP handshake)이지만, 어쨌든 저희는 이를 위해 실제 Firefox 프로토콜을 사용하고 있습니다.

export ROTUNDA_DEBUG_DUMP_DIR=/tmp/rotunda-fingerprint-debug
export ROTUNDA_DEBUG_DUMP=manifest,network,console,vm,returns
export ROTUNDA_VM_ACCESS_SAMPLE_RATE=10
...

rotunda-fingerprint-debug.zip 파일을 사이트 URL, 예상했던 동작, 그리고 대신 사이트가 보고한 내용과 함께 GitHub Issue에 첨부해 주세요. 덤프 (dump)에는 요청/응답 본문 (request/response bodies)이 포함되어 있으므로, 공유하기 전에 검토하시기 바라며 유지 관리자 (maintainer)가 요청하지 않는 한 ROTUNDA_DEBUG_DUMP_RAW=1을 설정하지 마세요.

도움을 주고 싶으신가요?

크레딧 (Credits)

이 리포지토리 (repository)는 daijro의 독창적인 Firefox 패칭 (patching) 작업을 기반으로 구축되었습니다. 그의 작업은 수많은 시행착오를 거쳐 이곳에서 사용되는 브라우저 패칭 기술의 토대를 마련했습니다. 그는 Juggler가 (CDP와 달리) 브라우저 컨텍스트 (browser context)로부터 격리되어 있다는 점을 들어 Firefox를 사용하는 근거를 제시했습니다.

하지만 그들의 주요 초점은 스텔스 (stealth)에 있는 반면, 저희의 초점은 자동화 (automation)에 있습니다. 저희는 여러분의 에이전트 (Agents)가 여러분이 일상적으로 사용하는 브라우저와 거의 동일하게 작동하는 브라우저에 접근할 수 있도록 하고자 합니다.

camoufox

FAQ

컴퓨터 비전 (computer vision)으로 Chrome을 제어하면 안 되나요?

물론 시도해 볼 수는 있습니다! 하지만 컴퓨터 비전은 너무 느리고, 컨텍스트 윈도우 (context window)를 가득 채우며, 에이전트가 뷰포트 (viewport)에 없는 콘텐츠를 볼 수 없게 만들기 때문에 완벽한 해결책이 아닙니다. 현재의 DOM을 가져와서 LLM 친화적인 페이지 표현 방식으로 파싱하는 것이 훨씬 더 편리합니다. 하지만 이러한 표현을 가져오는 것은 우리가 피하려고 했던 Playwright/CDP 제어와 동일한 문제에 직면하게 만듭니다.

컴퓨터 비전 (Computer Vision)을 사용하기 위해 대부분의 클라우드 VM (Virtual Machine)에서 실행하는 것은 기본 호스트 (Host)에 대한 상태를 유출할 위험이 있습니다. 대부분은 탐지하기 매우 쉬운 동일한 스텔스 플러그인 (Stealth plugins)을 사용하는데, 이는 이를 자연스럽게 사용할 경우 결국 플래그 (Flagged)가 지정될 것임을 의미합니다.

게다가 컴퓨터 비전 (Computer Vision)은 때때로 일부 웹사이트에서 클릭을 어렵게 만드는데, 이는 직접적인 클릭 이벤트 (Click events)를 깔끔하게 변환하기 어렵기 때문입니다 (예: Claude가 양식 목록에서 드롭다운 (Dropdowns)을 선택하지 못한다는 보고 참조).