브라우저 자동화

Revka는 실제 웹 브라우저를 직접 제어할 수 있어, 에이전트가 페이지를 열고 렌더링된 콘텐츠를 읽으며 요소를 클릭하고, 폼을 작성하고, 스크린샷을 촬영할 수 있습니다. 이 페이지에서는 browser 도구 활성화, 백엔드 선택, 허용 목록으로 탐색 범위 제한, VNC 또는 Chrome 원격 데스크톱을 통한 가시적 브라우저 디버깅, 그리고 browser_delegate를 사용하여 복잡한 웹 앱 작업을 외부 CLI에 위임하는 방법을 다룹니다.

JavaScript로 콘텐츠를 렌더링하거나, 로그인이 필요하거나, 상호작용이 필요한 페이지에서는 브라우저 자동화를 사용하십시오. 단순한 정적 페이지라면 더 가벼운 웹 도구(web_fetch, text_browser)가 더 빠르고 비용 효율적입니다.

브라우저 접근 구조

Revka는 여러 웹 관련 도구를 제공합니다. 자동화에서 핵심적으로 사용되는 두 가지 도구는 다음과 같습니다.

• browser_open — 승인된 HTTPS URL을 시스템 브라우저에서 엽니다. 스크래핑이나 상호작용은 지원하지 않습니다.
• browser — 플러그 가능한 백엔드를 사용하는 완전한 자동화 도구입니다. DOM 작업(open, snapshot, click, fill, type, get_text, get_title, get_url, screenshot, wait, press, hover, scroll, is_visible, close, find)을 지원하며, computer_use 백엔드가 활성화된 경우 OS 수준 작업(mouse_move, mouse_click, mouse_drag, key_type, key_press, screen_capture)도 사용할 수 있습니다.

두 도구 모두 [browser] 설정 섹션에 의해 제어되며, allowed_domains 허용 목록을 공유합니다.

참고

browser 및 browser_open 도구는 일반적으로 OTP 게이팅 뒤에 배치됩니다. 기본 security.otp.gated_actions 목록에는 browser와 browser_open이 포함되어 있습니다. 자세한 내용은 OTP 게이팅 & 긴급 정지를 참조하십시오.

[browser] 설정 섹션

~/.revka/config.toml에서 브라우저 접근을 구성합니다.

[browser]
enabled = true
allowed_domains = ["*"]
backend = "agent_browser"
native_headless = true

키	타입	기본값	설명
enabled	bool	false	browser 및 browser_open의 마스터 스위치
allowed_domains	array	[]	탐색 허용 목록; "*"은 모든 공개 도메인을 허용
backend	string	"agent_browser"	agent_browser, rust_native, computer_use, 또는 auto
session_name	string	미설정	agent-browser의 명명된 브라우저 세션 (인증 상태 유지)
native_headless	bool	true	rust-native 백엔드의 헤드리스 모드
native_webdriver_url	string	http://127.0.0.1:9515	rust-native 백엔드의 WebDriver 엔드포인트
native_chrome_path	string	미설정	rust-native 백엔드의 선택적 Chrome/Chromium 실행 파일 경로

주의

스키마 기본값에서 enabled는 false입니다. 일부 설치본은 브라우저 도구가 이미 활성화된 상태로 제공될 수 있으므로, 반드시 자신의 config.toml에서 해당 값을 직접 확인하십시오.

allowed_domains

allowed_domains는 모든 브라우저 탐색에 대한 보안 경계입니다. 기본적으로 모든 접근이 차단됩니다.

• 빈 목록([])은 모든 URL을 차단합니다.
• "*"은 모든 공개 도메인을 허용하지만, 로컬 및 사설 호스트는 여전히 차단됩니다.
• 특정 항목은 정확한 도메인 또는 서브도메인 일치 방식으로 동작합니다.

[browser]
enabled = true
# 에이전트를 두 개의 도메인으로만 제한:
allowed_domains = ["example.com", "docs.example.com"]

브라우저 접근을 완전히 비활성화하려면:

[browser]
enabled = false

백엔드 선택

사용 환경에 맞는 backend를 설정하십시오.

agent_browser (기본값, 권장)

기본 백엔드로, agent-browser CLI를 통해 Chrome for Testing을 구동합니다. 샌드박스 환경에서 헤드리스로 실행되며, 서버 또는 컨테이너 환경에서 가장 쉽게 사용할 수 있습니다.

한 번만 설치하면 됩니다.

# CLI 설치
npm install -g agent-browser

# Chrome for Testing 다운로드
agent-browser install --with-deps   # Linux (시스템 의존성 포함)
agent-browser install               # macOS / Windows

설정에서 backend = "agent_browser" 및 enabled = true를 확인한 후, 에이전트를 통해 테스트합니다.

echo "Open https://example.com and tell me what it says" | revka agent

설치 상태를 확인하기 위해 CLI를 직접 실행할 수도 있습니다.

agent-browser open https://example.com
agent-browser get title
agent-browser snapshot -i
agent-browser screenshot /tmp/test.png
agent-browser close

rust_native

Revka에 내장된 WebDriver 기반 백엔드입니다. agent-browser CLI 대신 기존 WebDriver/ChromeDriver 인스턴스를 사용하고 싶을 때 활용하십시오.

[browser]
enabled = true
backend = "rust_native"
native_headless = true
native_webdriver_url = "http://127.0.0.1:9515"
native_chrome_path = "/usr/bin/chromium"   # optional

주의

rust-native 백엔드를 사용하려면 browser-native Cargo 기능이 빌드에 포함되어 있어야 합니다. Cargo 기능 플래그 & ADR을 참조하십시오.

computer_use

HTTP를 통해 별도의 computer-use 사이드카에 브라우저 작업을 위임하며, OS 수준의 마우스, 키보드, 스크린샷 작업을 수행합니다. DOM 스크립팅이 아닌 진정한 OS 수준 제어가 필요할 때 선택하십시오. mouse_move, mouse_click, mouse_drag, key_type, key_press, screen_capture 작업은 이 백엔드에서만 사용할 수 있습니다.

[browser]
enabled = true
backend = "computer_use"

[browser.computer_use]
endpoint = "http://127.0.0.1:8787/v1/actions"
timeout_ms = 15000
allow_remote_endpoint = false
window_allowlist = []
# api_key = "..."          # optional bearer token, stored encrypted
# max_coordinate_x = 1920  # optional coordinate boundary
# max_coordinate_y = 1080

키	기본값	설명
endpoint	http://127.0.0.1:8787/v1/actions	OS 수준 작업을 위한 사이드카 엔드포인트
api_key	미설정	선택적 bearer 토큰 (암호화 저장)
timeout_ms	15000	작업별 요청 타임아웃
allow_remote_endpoint	false	루프백이 아닌 엔드포인트 허용 여부
window_allowlist	[]	사이드카 정책에 전달되는 창 제목/프로세스 허용 목록
max_coordinate_x / max_coordinate_y	미설정	선택적 좌표 경계

주의

allow_remote_endpoint = false(기본값)를 유지하십시오. 네트워크 경로를 완전히 제어하지 않는 한 변경하지 마십시오. 이 설정은 루프백이 아닌 엔드포인트를 거부하여 사이드카가 의도치 않게 공개적으로 노출되는 것을 방지합니다.

auto

backend = "auto"로 설정하면 Revka가 사용 가능한 백엔드를 자동으로 선택합니다.

@ref 선택자 모델

open 이후 snapshot을 호출하면 상호작용 가능한 요소들이 @e1, @e2, @e3와 같은 안정적인 ref로 매핑됩니다. 이 ref를 click, fill, hover 등의 작업에 전달합니다. 일반적인 에이전트 흐름의 예시는 다음과 같습니다.

{"action": "open", "url": "https://example.com"}
{"action": "snapshot"}
{"action": "click", "selector": "@e3"}

선택자는 CSS(button.submit) 및 텍스트 매처(text=Accept)도 지원합니다. 페이지가 변경된 후에는 snapshot을 다시 실행하십시오. ref는 매번 새로 계산됩니다.

VNC를 통한 GUI 디버깅

시각적 디버깅을 위해 가상 디스플레이를 실행하고 VNC 클라이언트 또는 웹 브라우저의 noVNC를 통해 브라우저를 확인할 수 있습니다.

의존성 설치 (Ubuntu/Debian):

apt-get install -y xvfb x11vnc fluxbox novnc websockify

# 선택적 데스크톱 환경 (아래 Chrome 원격 데스크톱에 필요)
apt-get install -y xfce4 xfce4-goodies

가상 디스플레이, 윈도우 매니저, VNC 서버, noVNC 브리지를 시작합니다.

#!/bin/bash
DISPLAY_NUM=99
VNC_PORT=5900
NOVNC_PORT=6080
RESOLUTION=1920x1080x24

Xvfb :$DISPLAY_NUM -screen 0 $RESOLUTION -ac &
sleep 1
fluxbox -display :$DISPLAY_NUM &
sleep 1
x11vnc -display :$DISPLAY_NUM -rfbport $VNC_PORT -forever -shared -nopw -bg
sleep 1
websockify --web=/usr/share/novnc $NOVNC_PORT localhost:$VNC_PORT &

연결 방법:

• VNC 클라이언트: localhost:5900
• 웹 브라우저: http://localhost:6080/vnc.html

자동화 동작을 실시간으로 확인하려면 가상 디스플레이에서 브라우저를 실행합니다.

DISPLAY=:99 google-chrome --no-sandbox https://example.com &

주의

이 예시에서 VNC 포트(5900, 6080)는 인증 없이(-nopw) 열려 있습니다. 방화벽이나 터널과 같은 사설 네트워크 뒤에 두십시오. 공개 인터넷에 절대 노출하지 마십시오.

Chrome 원격 데스크톱

Google 계정을 통한 관리형 원격 GUI를 사용하려면 서버에 Chrome 원격 데스크톱을 설치합니다.

wget https://dl.google.com/linux/direct/chrome-remote-desktop_current_amd64.deb
apt-get install -y ./chrome-remote-desktop_current_amd64.deb

# 세션 구성
echo "xfce4-session" > ~/.chrome-remote-desktop-session
chmod +x ~/.chrome-remote-desktop-session

이후 절차:

1. https://remotedesktop.google.com/headless에 접속합니다.
2. “Debian Linux” 설정 명령을 복사하여 서버에서 실행합니다.
3. 서비스를 시작합니다: systemctl --user start chrome-remote-desktop.
4. https://remotedesktop.google.com/access에서 모든 기기로 접속합니다.

browser_delegate

browser_delegate는 자연어로 작성된 브라우저 작업을 외부 브라우저 지원 CLI 서브프로세스(예: claude-in-chrome MCP를 사용하는 Claude Code)에 위임합니다. 직접 API가 없고 헤드리스 백엔드로 처리하기 까다로운 기업용 웹 앱(Teams, Outlook, Jira, Confluence 등)에 유용합니다.

[browser_delegate]
enabled = true
cli_binary = "claude"
chrome_profile_dir = "~/.config/chrome-corp-profile"
allowed_domains = ["teams.microsoft.com", "outlook.office.com"]
blocked_domains = []
task_timeout_secs = 120

이 도구는 단일 task 인자를 받습니다.

{"task": "Check my unread Teams messages"}

주의

browser_delegate는 CLI 서브프로세스를 생성하기 위해 셸 접근이 필요하므로, 셸이 비활성화된 제한적 런타임 환경에서는 사용할 수 없습니다. agent_browser 백엔드가 적합하지 않을 때만 사용하십시오.

문제 해결

• “Element not found”: 페이지가 완전히 로드되지 않았을 수 있습니다. 스냅샷 전에 대기를 추가하십시오 — agent-browser wait --load networkidle, 이후 agent-browser snapshot -i.
• 쿠키 배너가 콘텐츠를 가리는 경우: 스냅샷을 찍고, 동의 ref(예: @accept_cookies)를 클릭한 후, 실제 콘텐츠를 위해 다시 스냅샷을 찍으십시오.
• Docker 샌드박스 내에서 web_fetch가 차단되는 경우: 브라우저 백엔드를 대신 사용하십시오 — agent-browser open <url> 후 agent-browser get text body.
• 로그인 상태 유지: [browser].session_name을 설정하거나(또는 CLI에 --session-name을 전달하여) 실행 간에 인증 쿠키가 유지되도록 하십시오.

관련 페이지

• 브라우저 & 웹 도구 — web_fetch 및 text_browser를 포함한 전체 도구 참조
• 설정: 채널, 도구 & 통합 — [browser] 및 [browser_delegate] 전체 키 참조
• OTP 게이팅 & 긴급 정지 — 일회용 비밀번호로 브라우저 작업 게이팅
• Cargo 기능 플래그 & ADR — rust-native 백엔드를 위한 browser-native 기능