브라우저 자동화

daemon은 두 가지 브라우저 표면을 제공합니다.

angski-web: 데스크톱 Patchright 기반 자동화
angski-mobile-web: 실제 모바일 WebView 기반 자동화

데스크톱 모드는 Patchright 브라우저를 daemon 쪽에서 직접 실행합니다.

현재 문서에서 고정해도 되는 범위:

페이지 이동, 클릭, 입력, 선택, 스크롤
AI용 ARIA snapshot과 브라우저 발급 ref 기반 읽기
스크린샷과 attachment 전달
쿠키, localStorage, IndexedDB 저장/실행 중 복원
agent browser 설정에 따른 viewport, device, action policy 적용
native screencast 우선, CDP fallback 기반 실시간 미리보기

프로덕션 capability와 fallback

browser_capabilities는 현재 엔진 버전, 실제 사용된 snapshot backend, fallback 횟수, hot storage-state 지원 여부, CDP console 진단, 암호화 상태, 브라우저 launch/state telemetry, native screencast 지원 여부와 Prompt API availability를 반환합니다.

snapshot backend 기본값은 auto입니다. AI snapshot이 실패하면 기존 ARIA 파서로 자동 복귀합니다.
자체 실행 브라우저 미리보기는 native screencast를 우선 사용하고 시작 실패 시 CDP로 복귀합니다.
미리보기 소비자의 전송 버퍼가 밀리면 세션별 프레임 간격을 자동으로 늘리고, 안정화되면 단계적으로 복구합니다.
daemon /health의 browserRuntime에서 프레임 전달·백프레셔·throttle·무소비자 drop과 screencast fallback을 확인할 수 있습니다.
browser.bind()는 런타임에서 지원되더라도 인증 없는 추가 연결면을 만들지 않도록 기본 비활성화합니다.
Prompt API가 사용할 수 없거나 모델을 내려받는 중이면 cloud provider를 사용합니다.

Stealth 모드

balanced: 기본값입니다. Patchright stealth와 CDP console 진단 수집을 함께 사용합니다.
strict: 페이지 JavaScript나 console 객체를 변경하지 않습니다. console 메시지는 페이지 외부 CDP 세션에서 계속 수집됩니다.
off: Angski의 추가 stealth init script와 launch argument를 적용하지 않습니다.

기존 stealth: false 설정은 off로 계속 해석되어 이전 설정과 호환됩니다.

쿠키 등록 흐름

로그인이 필요한 사이트는 agent별 쿠키를 저장해 두는 흐름이 있습니다.

session manager 열기

/api/browser/:agentId/session-manager를 열어 등록 도우미 페이지로 들어갑니다.

브라우저에서 직접 로그인

대상 사이트 로그인까지 수동으로 진행합니다.

쿠키 저장

/api/browser/:agentId/cookies/register 흐름으로 현재 쿠키를 저장합니다.

상태 확인

/api/browser/:agentId/cookies/status로 등록 여부와 만료 상태를 확인합니다.

실행 중인 MCP 브라우저에서는 browser_storage_state_save로 현재 상태를 원자적으로 저장하고, browser_storage_state_reload로 새 context를 만들지 않고 다시 적용할 수 있습니다. 두 작업은 기본 action policy에서 확인이 필요한 state 작업이며, 상태 값 자체는 tool 결과에 노출하지 않습니다.

storage-state는 AES-256-GCM으로 인증 암호화됩니다. macOS에서는 키를 Keychain에 저장하고, 다른 플랫폼에서는 ~/.angski/browser-state.key 보호 파일을 사용합니다. 배포 환경에서 ANGSKI_BROWSER_STATE_KEY에 base64 32-byte 키를 지정하면 플랫폼 저장소 대신 해당 키를 사용합니다. 기존 평문 storage-state는 최초 읽기와 검증이 성공한 직후 암호화 형식으로 자동 마이그레이션됩니다.

agent별 저장

저장된 쿠키는 agent 기준으로 관리됩니다. 같은 사이트라도 agent가 다르면 별도 상태로 봅니다.

스크린샷과 산출물

브라우저 도구의 임시 스크린샷은 ~/.angski/agents/<agentId>/browser-captures/ 아래에 저장됩니다.
Codex 세션 attachment는 bridge asset 경로로 다시 노출될 수 있습니다.
비활성 세션 산출물은 정리 작업의 대상이 됩니다.

기본 보안 경계

모든 데스크톱/모바일 액션은 동일한 action policy 검사를 거칩니다.
쿠키 값은 기본적으로 가려지며 명시적으로 요청한 경우에만 반환됩니다.
storage-state 파일은 크기와 origin schema를 검증하고 AES-256-GCM으로 인증 암호화한 뒤, 파일·상위 디렉터리를 fsync하고 0600 권한으로 원자 교체합니다.
쿠키 상태, 파일, network interception 액션은 기본 확인 대상입니다.
브라우저 이동은 HTTP/HTTPS만 허용하고 클라우드 metadata endpoint와 URL 내장 자격 증명을 거부합니다.
업로드와 PDF 경로는 실제 경로 기준으로 검사하여 허용 디렉터리 밖으로 나가는 symbolic link를 거부합니다.
모바일 모드는 JavaScript evaluation을 지원하지 않습니다.

문서에서 의도적으로 고정하지 않는 것

아래 항목은 구현 옵션이 자주 바뀌므로 UI나 코드 기준으로 확인하는 편이 정확합니다.

세부 stability 수치와 내부 launch flag
실시간 브라우저 미리보기 품질 값
특정 tool의 enable/disable 조합
개별 action policy 파일 경로

브라우저 자동화

On this page