Chrome Relay는 Claude Code, Codex, Cursor, Paseo가 명령줄에서 실제 로그인 정보가 있는 Chrome의 백그라운드 탭을 조작하게 해주는 오픈소스 도구다. 제작자는 이 도구를 MIT 라이선스로 공개했다.
필요한 기능
제작자는 여러 코딩 에이전트를 Mac에서 동시에 실행할 때, 브라우저가 필요한 에이전트가 작업 중인 Chrome 창을 앞으로 가져오거나 원격 디버깅 허용 창을 띄우는 문제를 겪었다. 별도의 헤드리스 브라우저를 쓰면 로그인 정보가 없어 관리 콘솔이나 스테이징 환경, Google SSO 뒤에 있는 페이지에 접근할 수 없었다.
Chrome Relay를 만들 때 요구한 조건은 네 가지였다. 모든 에이전트가 실행할 수 있도록 명령줄 인터페이스(CLI)로 동작해야 하고, 다시 로그인하거나 프로필을 복사하지 않고 실제 Chrome 프로필을 사용해야 한다. 브라우저 창의 포커스를 빼앗지 않아야 하며, 페이지 확인이 빠르게 끝나야 한다.
기존 방식의 제약
Chrome 디버깅 포트에 연결하는 대부분의 브라우저 도구는 ‘원격 디버깅을 허용할까요?’라는 창을 띄운다. Chrome 프로필을 별도 브라우저에 복사하는 방식도 Google 세션이 기기에 연결돼 있어 쿠키가 유효하지 않게 되고, 원하는 앱에서 로그아웃되는 문제가 있었다. 제작자는 Playwright 확장 프로그램과 로그인된 별도 브라우저도 시험했지만 네 가지 조건을 모두 충족하지 못했다고 설명했다.
Codex와 Claude의 Chrome 확장 프로그램은 Chrome의 chrome.debugger API를 사용한다. 다만 각 확장 프로그램은 해당 앱에만 연결되므로, 제작자는 같은 방식을 어떤 CLI 에이전트에서나 사용할 수 있도록 표준 DevTools 엔드포인트로 제공하려 했다.
작동 방식
연결 구조는 다음과 같다.
agent-browser (CLI) ──ws──▶ relay (127.0.0.1:9333) ──ws──▶ Chrome Relay extension ──chrome.debugger──▶ agent tab
확장 프로그램은 Manifest V3(MV3) 기반이며, 각 Chrome 프로필에서 한 번 불러온다. 에이전트가 여는 탭은 비활성 상태로 접힌 ‘Agents’ 탭 그룹에 추가되고, 확장 프로그램은 chrome.debugger를 통해 DevTools 명령을 실행한다. 디버깅 포트를 사용하지 않으므로 Chrome의 ‘원격 디버깅을 허용할까요?’ 창이 뜨지 않는다고 제작자는 설명했다.
중계 서비스는 로컬에서 실행되며 에이전트마다 별도의 DevTools 엔드포인트를 제공한다. 브라우저 창을 띄우거나 포커스를 가져오는 명령은 차단한다. 각 에이전트에는 자신이 연 탭만 보이므로 여러 에이전트를 동시에 실행할 수 있다.
설정과 프로필 연결 URL 확인에는 chrome-relay CLI를 사용한다. 이 도구는 진단을 실행하고 감사 로그도 읽는다. 에이전트는 Vercel의 agent-browser CLI를 중계 서비스에 연결해 사용한다.
agent-browser --cdp "$(chrome-relay url you@company.com)" open https://app.example.com/ agent-browser snapshot -i # the page's buttons, links and fields, each with a ref agent-browser click @e5 agent-browser close
이메일 주소로 Chrome 프로필을 선택한다. 제작자는 대부분 업무 프로필을 쓰고, 에이전트가 콘솔을 확인해야 할 때는 관리자 프로필을 사용한다고 밝혔다.
팝업과 ‘새 탭에서 열기’ 링크는 해당 에이전트가 소유하는 숨겨진 탭이 된다. OAuth 팝업은 이를 연 페이지로 결과를 전달할 수 있다.
Google 로그인 과정에서는 사이트가 Google로 이동했을 때 올바른 계정이 이미 로그인돼 있으면 확장 프로그램이 계정과 ‘계속’을 직접 선택한다. 에이전트는 로그인 정보를 입력하지 않는다. 비밀번호, 패스키 또는 2단계 인증 화면이 나오면 작업을 멈추고, 에이전트는 사용자가 직접 로그인 창에서 인증하라고 알린다.
1Password에서는 다른 문제가 생길 수 있다. 로그인 양식의 1Password 메뉴처럼 다른 확장 프로그램의 프레임이 포함된 페이지에서는 Chrome이 확장 프로그램의 디버거 연결을 끊는다. 중계 서비스는 확장 프로그램이 다시 연결될 때까지 기다리므로 에이전트 명령이 조금 느려진다.
제작자가 가장 중요하게 여긴 속도와 관련해, 명령 실행에는 약 0.15초, 페이지를 여는 데는 약 0.6초가 걸린다고 밝혔다. Chrome이 이미 열려 있어 브라우저를 새로 실행할 필요는 없다.
접근 제어와 한계
에이전트는 사용자가 로그인한 브라우저를 사용하므로, 제작자는 어떤 프로세스가 연결할 수 있는지와 연결 후 에이전트가 한 일을 확인할 수 있도록 설계했다.
연결하려면 두 가지 검사를 통과해야 한다. 먼저 설정 과정에서 생성돼 사용자만 읽을 수 있도록 저장되는 기기별 비밀값이 필요하다. 또한 연결 프로세스는 Claude Code, Codex, Cursor 또는 Paseo여야 한다. 중계 서비스는 프로세스를 확인하고 해당 앱이 하위 프로세스에 설정하는 표시값을 검사한다. 비밀값이 있어도 웹페이지의 연결은 거부된다.
확장 프로그램 연결은 사용자가 설치한 확장 프로그램만 허용한다. 중계 서비스는 연결 출처를 확인하고 연결 프로세스가 Chrome인지도 검사한다. 제작자는 이 검사들이 다른 로컬 도구나 웹페이지의 접근을 막고 실수로 인한 연결을 방지한다고 설명했다. 다만 사용자 권한으로 이미 실행 중인 악성코드는 비밀값을 읽고 표시값을 위조할 수 있으므로, 이 방식은 그런 악성코드에 대한 보안 경계를 제공하지 않는다.
에이전트가 작업하는 동안 Chrome에는 ‘이 브라우저의 디버깅을 시작했다’는 표시줄이 나타난다. Codex 확장 프로그램을 사용할 때와 같은 표시다.
모든 에이전트 작업은 감사 로그에 기록된다. 로그에는 페이지와 클릭, 키 입력, 에이전트가 실행한 스크립트가 포함된다. 스크린샷과 로그인 화면에서의 클릭도 기록하지만, 입력한 텍스트는 길이만 저장하고 실제 내용은 로그 파일에 남기지 않는다. 에이전트가 무언가를 확인했다고 말하면 로그에서 수행한 작업을 확인할 수 있다.
설치 및 사용 조건
현재 macOS와 Chrome만 지원한다. Node.js 20 이상과 agent-browser가 필요하다. 원문은 설치에 약 2분이 걸린다고 안내한다.
npm i -g agent-browser
저장소를 복제하고 설정을 실행한다.
git clone https://github.com/aindeev/agent-chrome-relay cd agent-chrome-relay bin/chrome-relay setup
에이전트가 사용할 각 Chrome 프로필에서 chrome://extensions를 열고 Developer mode를 켠 다음, ‘Load unpacked’를 눌러 extension 폴더를 선택한다. 이후 chrome-relay doctor를 실행해 설정을 확인한다. 또는 사이트에서 설정 안내를 복사해 에이전트에 붙여 넣고 안내에 따라 설정할 수도 있다.
설정 과정에서는 Claude Code가 사용할 스킬 파일을 각 저장소에 연결한다. Codex와 Cursor에서는 같은 스킬 파일을 가리키는 한 줄을 전역 에이전트 지침에 추가해야 한다.
프로젝트 저장소는 GitHub의 agent-chrome-relay에서 확인할 수 있고, 도구 사이트에서도 설정 안내를 볼 수 있다.
댓글 (0)
로그인하면 이 기사에 내 생각을 남길 수 있어요