Skip to content
프로젝트

w-partners/Wbrowser has 31 GitHub stars and 7 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-14 20:27 UTC. Last push 2026-11-07.

이 수치를 측정하는 방법

측정된 스타 증가

in 24h
0
in 7 days
기록 수집 중
in 15 days
기록 수집 중
in 1 month
기록 수집 중

서로 겹치는 기간의 순증가량이며 일별 합계가 아닙니다. 측정값이 없으면 비워 둡니다. 스타는 관심도를 나타내며 품질을 보장하지 않습니다.

소개

Drive the Chrome you are already logged into - from your terminal or any AI assistant. Cross-platform, MCP-ready.

개발 도구

docs/README.ko.md

Original

🤖 Wbrowser

AI 는 로그인 뒤를 못 봅니다. 그걸 해결합니다 — 내가 쓰는 그 운영체제에서.

AI 는 웹 검색은 하지만 내 메일함도, 관리자 화면도, 회사 내부 시스템도 못 엽니다. 쓸모 있는 건 전부 로그인 뒤에 있고, AI 에게는 그 로그인이 없습니다.

Wbrowser 는 내가 한 번 직접 로그인해 둔 진짜 크롬에 AI 의 자리를 내줍니다.

🔵 설치를 정확히 적습니다: 크롬 136+ 는 기본 프로파일에서 원격 디버깅을 막아서, 이 도구는 전용 프로파일을 띄우고 거기서 한 번 로그인합니다. 그 뒤로는 세션이 계속 삽니다 — 실측한 프로파일에서 구글 한 번으로 유튜브와 '구글로 로그인'을 쓰는 사내 시스템 두 개까지 같이 열렸습니다. 설정 0분이 아니라 설정 1회입니다. 같은 창, 같은 탭. 클릭이 어디에 떨어지는지 다 보이고, 그 클릭은 에이전트가 자기 탭에서 합니다 — 당신이 보고 있는 탭이 아니라.

AI 는 내 비밀번호를 절대 보지 않습니다. 직접 로그인해 크롬이 보관하거나, 한 번만 로컬 암호화 vault(wb login)에 저장하면 엔진이 — AI 가 아니라 — 그걸 읽습니다. vault 는 AES-256-GCM(scrypt 키유도)이고 소유자만 읽는 0600 권한으로 내 기기에 있습니다. 어느 쪽이든 Wbrowser 는 이미 열린 창을 조종만 하고, 모델은 비밀번호를 받지 않습니다.

윈도우·맥·리눅스·WSL 에서 됩니다 — 각각 다른 머신에서, 그 부분을 만들지 않은 사람이 실기로 쟀습니다:

환경 크롬 검증자
윈도우 10 151 다른 머신·다른 사람 · E2E 포함
macOS 15 151 다른 머신·다른 사람
리눅스 (화면 없음) 148 다른 머신·다른 사람 · 보안 검토 포함
WSL2 151 관리자 (자기검증)

2026-08-24 측정. 모든 항목을 모든 환경에서 잰 것은 아닙니다 — 플랫폼 참고.

자바스크립트·파이썬·셸 합쳐 약 2,600줄. MIT. 하루면 다 읽고, 고쳐서 내 것으로 만들 수 있는 크기입니다.

English · 한국어 · 中文 · Español

check License: MIT Node Platforms


왜 만들었나요

AI 브라우저는 전부 같은 모양입니다 — Aside, Comet, Dia. 새 브라우저를 설치하고 그 안에 AI 가 들어 있습니다. 그 모양에는 대가가 셋 있습니다:

그들의 방식 치러야 하는 것
새 브라우저를 깐다 새 프로파일 · 새 로그인 · 새 설정
AI 가 그 안에 산다 내 세션이 남의 빌드 안에 놓인다
플랫폼은 그들이 정한다 Aside·Dia 는 지금 맥 전용

우리는 반대로 했습니다. 설치할 브라우저도, 옮길 것도 없습니다 — 이미 컴퓨터에 있는 크롬을, 내가 보면서 같이 쓸 수 있는 창에서 몰 뿐입니다. 클릭이 어디에 떨어지는지 눈으로 보되, 그 클릭은 에이전트가 스스로 연 탭에서 일어납니다. 옮길 것도, 넘겨줄 것도 없습니다.

🔵 오해가 없도록 정확히 적습니다: 에이전트는 당신이 보던 탭을 가져가지 않고, 창을 앞으로 끌어오지도 않습니다. 그래서 옆에서 계속 일하실 수 있습니다. 다만 마우스를 움직인다고 에이전트가 멈추지는 않습니다 — 방해해서 비켜주는 게 아니라, 애초에 같은 탭을 쓰지 않는 것입니다. 지금 보고 있는 페이지를 맡기고 싶으면 ./wb take <번호> 로 직접 건네주십시오.

그 선택 덕에 윈도우·맥·리눅스·WSL 어디서든 됩니다 — 브라우저를 안 만들었으니 플랫폼을 고를 일도 없었습니다.

필요하면 만들어 쓴다.

이게 전부입니다. 누군가의 개발 일정을 기다리는 제품이 아니라, 내가 이미 쓰는 컴퓨터에서, 내가 직접 로그인해 둔 브라우저로 돌아가는 내 도구요. 자바스크립트·파이썬·셸 합쳐 2,600줄쯤 됩니다. 하루면 다 읽을 분량이에요. 읽고, 고치고, 내 것으로 만드세요.

Wbrowser 는 윈도우·맥·리눅스·WSL 을 지원합니다. 맥·네이티브 리눅스·WSL2·윈도우 네이티브 네 환경에서 실기 검증했습니다. 다만 모든 항목을 모든 환경에서 잰 것은 아닙니다(아래 표 참고). "무슨 운영체제 쓰세요?" 가 내 브라우저를 자동화 못 하는 이유가 되면 안 되니까요.


이게 뭔가요?

보통의 자동화 도구는 AI 에게 텅 빈 새 브라우저를 줍니다. 그래서 내 메일도, 내 관리자 화면도 못 봐요. 로그인이 필요한 건 전부 막힙니다. 비밀번호를 넘겨주거나, 사이트마다 API 연동을 하지 않는 한요.

Wbrowser 는 반대로 합니다. 내가 직접 한 번 로그인하면, 그다음부터는 터미널이나 AI 가 그 창을 그대로 조종합니다. 그때부터는 로그인된 상태 그대로요.

./wb go https://mail.example.com   # 내가 로그인해 둔 그 상태로 열림
./wb read                          # 화면에 뭐가 있는지 알려줌
./wb click '#compose'              # 버튼 누르기

Wbrowser 는 비밀번호를 절대 보지 않습니다. 여러분이 입력하고 — 크롬에, 또는 한 번만 엔진이 읽는 로컬 암호화 vault(wb login, 옵트인)에. 어느 쪽이든 AI 는 그 값을 받지 않고, Wbrowser 는 이미 열린 창을 조종할 뿐입니다.


복사하는 게 아닙니다 — 계정에 그대로 연결됩니다

이 부분은 정확히 짚어둘 만합니다. 비슷한 도구들과 갈리는 지점이니까요.

Wbrowser 는 데이터를 복사해두지 않습니다. 프로파일 폴더에 있는 건 쿠키뿐이고, 그건 "이 사람이 로그인했다"는 증명입니다. 메일도 파일도 대시보드도 전부 그대로 서비스 서버에 있습니다 — 마스터 휴대폰과 똑같습니다. 에이전트도 같은 방식으로 봅니다. 그 증명을 내밀고 서버에 물어보는 겁니다.

구글 서버              계정과 데이터
    |
    +-- 노트북 크롬      세션 하나
    +-- 휴대폰          세션 하나
    +-- Wbrowser        세션 하나   <- 로그인하실 때 생긴 것

여기서 나오는 결론 두 개인데, 둘 다 같이 보셔야 합니다:

  • 🔵 낡은 사본도, 동기화도, 따로 지킬 저장소도 없습니다. 구글 쪽에서 로그아웃하면 이 세션도 같이 끝납니다. 폴더에 남아서 털릴 것이 없습니다.
  • 🔴 살아있는 계정이지 샌드박스가 아닙니다. 에이전트가 메일을 열면 그건 진짜 메일입니다. 접근 범위는 마스터가 가진 것과 정확히 같습니다 — 더도 덜도 아닙니다.

⚠️ 프로파일 폴더를 복사하는 건 애초에 안 됩니다. 해봤습니다 — 쿠키 685개가 3개가 됐습니다. 크롬이 모르는 프로파일을 무효화합니다. 직접 로그인하는 건 그 우회책이 아니라, 유일하게 성립하는 방식입니다.

로그인 한 번이 여러 사이트를 엽니다

이게 설치할 값어치를 만드는 부분입니다. 그 창에서 구글에 한 번 로그인하면:

구글 자체        google.com · youtube.com · 워크스페이스 앱들
구글 SSO 사이트   "구글로 로그인" 이 닿는 곳 전부 —
                 사내 시스템·예약 시스템·관리자 화면
그 외            한 번만 손으로 로그인하면 계속 유지됩니다

실제 프로파일에서 잰 결과: 구글 로그인 한 번에 유튜브와 따로 로그인한 적 없는 업무 시스템 두 곳이 함께 열렸습니다. 나머지(GitHub·네이버·Reddit 등)는 한 번씩 손으로 로그인했고 그대로 남아 있습니다.

즉 초기 비용은 구글 로그인 1회 + 구글을 안 쓰는 사이트만 각각 1회입니다. 그 뒤로는 AI 가 전부에 닿습니다.

🔴 뒤집으면 같은 말입니다 — 이 브라우저를 조작할 수 있는 것은 그 사이트 전부에서 나로 행동할 수 있습니다. 보안 절을 보십시오.

하지 않는 것

  • 비밀번호를 AI 에 노출하지 않습니다. 내가 직접 로그인하거나, 엔진만 읽는 로컬 암호화 vault(wb login, 옵트인)에 한 번 저장합니다 — 어느 쪽이든 모델은 값을 받지 않습니다. type 은 입력한 내용을 로그에 안 남깁니다.
  • 쿠키 값을 출력하지 않습니다. 화면에도 로그에도 — 쿠키가 곧 로그인입니다.
  • 어느 계정인지 짐작하지 않습니다. 안 열린 계정을 지정하면 실패합니다. 엉뚱한 계정으로 메일 보내는 게 오류 메시지보다 나쁩니다.
  • 예약 실행에서 제출·결제·삭제를 안 누릅니다. 그 작업에 명시적으로 허용하지 않는 한요. 자동 실행은 잘못돼도 아무도 안 보고 있다는 뜻입니다.

우리가 재서 밝히는 한계 하나

크롬 디버깅 포트에는 인증이 없습니다. 그 컴퓨터에서 나로 실행되는 아무 프로세스나 붙어서 내 세션을 조작할 수 있습니다 — 무관한 프로세스로 붙어 열린 탭을 조회해 확인했습니다. 127.0.0.1 은 울타리가 아니라 "나로 실행되면 통과" 입니다.

이건 크롬의 설계이지 우리가 만든 게 아니고, 이 부류의 도구는 전부 물려받습니다. 나중에 알게 되시는 것보다 적어두는 편이 낫다고 봤습니다 — 전체 위협 모델은 보안 절에 있습니다.

시작하기

맥 · 리눅스 · WSL — 한 줄이면 됩니다:

curl -fsSL https://raw.githubusercontent.com/w-partners/Wbrowser/main/setup.sh | bash

필요한 게 깔려 있는지 확인하고, 내려받고, 설치하고, wb 를 어디서든 쓸 수 있게 걸고, 에이전트 스킬을 넣고 W브라우저를 MCP 서버로 등록해 어시스턴트의 '도구 목록'에 뜨게 하고 (내장 브라우저 도구와 나란히), 브라우저 창까지 띄웁니다. 그 창에서 평소처럼 직접 로그인하시면 설치는 끝입니다.

🔵 MCP 등록은 로컬 stdio 입니다 — 포트·토큰·네트워크 노출 0, 내 에이전트 프로세스만 닿습니다. (다른 머신에서 조종하는 별도 인증 HTTP 모드는 토큰이 필요하고 여기선 안 켭니다.) Claude CLI 면 자동 등록되고, 다른 런타임이면 붙이는 명령 한 줄을 화면에 알려줍니다.

윈도우에서 (WSL 없이 PowerShell 로)
git clone https://github.com/w-partners/Wbrowser.git
cd Wbrowser
$env:PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1; npm install
node launch.js          # 창이 뜨면 거기서 로그인하세요
node engine.js          # 이 창은 켜둔 채로
node bin\wbrowser.js go https://github.com

wb 는 bash 스크립트라 윈도우에서는 안 돕니다. 대신 node bin\wbrowser.js 를 쓰시면 나머지는 완전히 같습니다.

🔵 WSL 이 더 편합니다. wsl --install 한 번 하고 우분투 안에서 위의 한 줄을 실행하시면 됩니다. 어느 쪽이든 결국 윈도우 크롬을 조종합니다.

직접 하고 싶다면 (모든 플랫폼)
git clone https://github.com/w-partners/Wbrowser.git
cd Wbrowser
# Wbrowser 는 *시스템에 깔린* 크롬을 쓰므로 playwright 가 자기 브라우저를
# 따로 받을 필요가 없습니다. 건너뛰면 400MB 쯤 절약됩니다:
PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm install

node launch.js       # 1. 전용 크롬 창이 뜹니다
                     # 2. 그 창에서 직접 로그인하세요 (손으로!)
node engine.js       # 3. 조종 엔진 켜기
./wb go https://example.com

2번만 사람이 하는 일이고, 나머지는 한 번 켜두면 됩니다.

설치가 멈추면

어중간하게 끝내지 않고 멈추면서 이유를 말합니다. 자주 나오는 둘:

이런 말이 나오면 이렇게
several user folders (WSL) ls /mnt/c/Users 로 본인 계정 폴더를 확인한 뒤
WBROWSER_PROFILE_DIR=/mnt/c/Users/<계정>/.wbrowser ./wb up
크롬을 못 찾음 WBROWSER_CHROME=/크롬/경로 ./wb up

./wb 가 "Permission denied" 라고 하면 — 내려받는 과정에서 실행 권한이 빠진 것입니다. 한 번만 고치면 됩니다:

chmod +x wb install.sh autostart.sh sync-session.sh

화면 없는 서버라면 — $DISPLAY 가 없으면 자동으로 헤드리스로 띄웁니다. 강제하려면 WBROWSER_HEADLESS=1(켬) 또는 =0(끔). 🔵 화면이 없으면 직접 로그인을 할 수 없으니, 데스크톱에서 ./sync-session.sh export 한 것을 import 로 가져오십시오.


왜 평소 크롬이 아니라 새 창인가요?

크롬 136 버전(2025년 3월)부터 기본 크롬 창은 외부 조종을 막습니다. 나쁜 프로그램이 원격 조종으로 쿠키를 훔쳐가는 일이 늘어서 구글이 막았어요.

그래서 별도 폴더의 전용 창이 유일한 방법입니다. Wbrowser 가 ~/.wbrowser 에 만들어 줍니다.

즉, 평소 크롬의 로그인은 안 따라옵니다. 새 창에서 한 번 로그인하면 그다음부터 계속 유지됩니다.

⚠️ 크롬 폴더를 복사하는 방법은 안 됩니다. 실제로 해봤는데 쿠키 685개가 3개로 줄고 로그인이 전부 날아갔습니다. 크롬이 모르는 폴더는 무효로 처리해요. 그냥 새로 로그인하세요. 1분이면 되고, 확실히 됩니다.


명령어

./wb go <주소>              사이트 열기
./wb read                  지금 화면에 뭐가 있는지 보기
./wb click <셀렉터>         버튼 누르기
./wb type <셀렉터> <글자>    입력칸에 글자 넣기
./wb press Enter           키 누르기
./wb eval '<자바스크립트>'   페이지에서 코드 실행
./wb console               콘솔 기록·에러 보기
./wb network               실패한 요청 보기 (404 등)
./wb shot 화면.png          스크린샷
./wb tabs                  번호 붙은 탭 목록 — 각 탭을 누가 몰고 있는지
./wb take <번호>            보고 있던 탭을 에이전트에게 넘긴다
./wb release               그 탭을 돌려받는다
./wb close                 내가 연 탭만 닫기
./wb status                지금 잘 돌아가나?
./wb show                  브라우저 창을 앞으로 가져오기

버튼 이름은 어떻게 아나요?

./wb read 하면 그 화면에 있는 버튼·입력칸 이름을 그대로 알려줍니다.

입력칸(1):
  - #searchbox_input  (검색어를 입력하세요)
버튼(3): 검색, 로그인, 설정

여기 나온 걸 복사해서 쓰면 됩니다. 외울 필요도, 찍을 필요도 없어요.

실제 있었던 일: 검색창을 input[name=q] 라고 짐작했다가 실패했습니다. textarea 였거든요. read 에는 정답이 처음부터 찍혀 있었습니다.


AI 에게 그냥 말하면 됩니다

Wbrowser 는 MCP 를 지원합니다. AI 비서에 연결하면 말로 시킬 수 있어요.

내 컴퓨터에서:

{
  "mcpServers": {
    "wbrowser": {
      "command": "node",
      "args": ["/설치경로/Wbrowser/mcp-server.js"]
    }
  }
}

원격에서:

export WBROWSER_MCP_TOKEN=$(openssl rand -hex 32)
node mcp-server.js --http --port 7982 --host 127.0.0.1

연결한 뒤엔 이렇게 말하면 됩니다:

"내 관리자 화면 열어서 오늘 숫자 정리해줘" "그 쇼핑몰 장바구니에 뭐 있는지 알려줘"

🔴 원격 서버는 토큰이 없으면 아예 안 켜집니다. 선택 사항이 아니에요. 이 서버는 내 로그인이 전부 들어있는 브라우저를 조종합니다. 그 포트에 닿는 사람은 곧 나 자신이 됩니다.


AI 에게 시킬 때 알려줘야 할 것

이 도구를 만들면서 실제로 겪은 것들입니다. 직접 스킬·프롬프트를 쓰신다면 여기 넣으십시오:

  1. 셀렉터를 추측하지 마라. browser_read 가 그 페이지의 진짜 셀렉터를 준다. 검색창을 input[name=q] 로 짐작했다가 실패했다 — textarea 였고, read 에 답이 있었다.
  2. 제출 전에 폼을 되읽어라. 일괄 입력 폼에서 2~10행의 고객 정보가 비어 있었다. 유지 체크박스가 그 항목을 안 덮었기 때문이다. 누르기 전에 전 행을 읽어서 잡았다.
  3. 반복할 때는 세면서 하라. 엔터를 8번 연속 보냈더니 40행이 생겼다. 한 번 누르고, 세고, 목표에 닿으면 멈춘다.
  4. 프레임워크 폼은 eval, 그게 안 되면 type. React 는 value 직접 대입을 무시한다. 네이티브 setter + input/change 이벤트를 쓰고, 그래도 안 되면 browser_type 이 실제 키를 보낸다.
  5. 무엇에 붙었는지 확인하라. browser_status 가 그 창에 로그인이 있는지 알려준다. 빈 프로파일은 모든 명령에 성공으로 답하면서 아무것도 안 한다.

정해진 시간에 자동으로 (크론)

jobs/아침체크.json 파일을 만드세요:

{
  "schedule": "0 9 * * 1-5",
  "tab": "morning",
  "steps": [
    { "goto": "https://내가볼사이트.com", "wait": 2000 },
    { "eval": "document.querySelector('.공지').innerText" },
    { "shot": true }
  ]
}
node cron.js list      등록된 작업 보기
node cron.js next      다음에 언제 도는지
node cron.js run 이름   지금 한 번 실행
node cron.js daemon    시간 맞춰 자동 실행

0 9 * * 1-5 는 "평일 아침 9시 0분" 이라는 뜻입니다. 순서대로 분 시 일 월 요일 이에요.

되돌릴 수 없는 건 자동으로 막힙니다

자동 실행은 잘못돼도 아무도 안 보고 있다는 뜻입니다. 그래서 결제·삭제·제출처럼 보이는 건 막습니다:

⛔ 2단계 차단 — 되돌릴 수 없어 보임 (click: #submit-payment)
   의도한 것이면 작업 파일에 "allowIrreversible": true 를 넣으십시오.

전체 설정이 아니라 작업 하나하나에 직접 허용해야 합니다.


지금 누가 조종 중인지 보입니다

AI 가 조종하는 동안 화면에 표시됩니다:

  • 반투명 테두리 + 이름표: 🤖 my-agent 제어 중
  • 탭 이름 앞에 [my-agent] 가 붙음

6초 동안 아무 동작이 없으면 테두리가 사라집니다. "지금 조종 중" 이라는 뜻이 정확히 유지되도록요. 색깔은 이름마다 다르게 나와서, 여러 AI 가 동시에 붙어도 누가 누군지 구분됩니다.

탭 이름은 페이지를 옮겨도 유지됩니다. 사이트가 제목을 바꿔 쓰면 바로 다시 붙이거든요.


하던 탭을 도중에 넘기기

세 페이지쯤 들어간 상태다. 목록을 걸러놨고 폼을 반쯤 채웠고 대시보드를 파고들었다. 앞으로 20분은 더 걸릴 것 같고, 직접 하고 싶지는 않다. 그 탭을 지목해서 넘기면 된다:

./wb tabs
  #  driven by      title                                url
  1  — (yours)      예약 — 3월                            https://…/bookings?from=03-01
  2  — (yours)      청구서 4417                           https://…/invoices/4417
  3  my-agent       [my-agent] GitHub                    https://github.com/…

./wb take 1          # 에이전트가 1번 탭을 그대로 이어받는다
./wb release         # 다시 돌려받는다

다시 로그인할 필요도, 처음부터 찾아 들어갈 필요도, 지금까지 뭘 했는지 설명할 필요도 없다. 만들어놓은 상태 그대로 넘어간다.

🔴 에이전트가 스스로 남의 탭을 가져가는 일은 없다. 자기가 연 탭만 몰고, 당신 탭에 손대는 유일한 경로는 당신이 번호로 건네주는 것뿐이다. 이건 정책이 아니라 조회 방식이 그렇다 — 에이전트는 자기가 열지 않은 페이지를 부를 이름이 없다.

0.2.0 이전에는 그렇지 않았다. 기본 탭이 이미 열려 있던 페이지를 물려받았고, 그건 대개 당신이 읽고 있던 탭이었다. 그 뒤로는 거기 클릭하고 입력하고 제목까지 덮었다. "안 쓰는 탭인지" 검사해서는 못 고친다 — 손으로 연 탭은 아무도 소유권을 주장하지 않아 어떤 검사로도 비어 보인다. 그래서 물려받기 자체를 없앴다.

./wb release 는 [에이전트] 라벨도 지운다. 돌려받은 탭에 누가 붙어 있는 것처럼 보이지 않게.


계정 여러 개 쓰기

크롬 창 안에서 프로파일을 여러 개 열면, 각각 따로 지정할 수 있습니다:

./wb -a [email protected] go https://mail.example.com
./wb windows                    # 열린 계정 목록

또는 accounts.json 에 사이트별로 정해두세요:

{
  "sites": {
    "mail.example.com": { "account": "[email protected]" }
  }
}

🔴 없는 계정을 지정하면 그냥 실패합니다. 비슷한 걸 골라주지 않아요. 엉뚱한 계정으로 메일을 보내는 것보다 오류 메시지가 낫습니다.


어느 운영체제에서 되나요?

운영체제 크롬 자동 찾기
윈도우 Program Files, AppData, Edge
맥 /Applications/Google Chrome.app, Chromium, Edge
리눅스 google-chrome, chromium, snap, Edge
WSL 윈도우 크롬 우선 (실제로 쓰는 브라우저니까)

못 찾으면 WBROWSER_CHROME=/크롬/경로 로 직접 알려주세요.

실제 기기에서 검증했습니다 (2026-08-24):

환경 크롬 검증자 그 환경에서 실제로 잰 것
macOS 15 151 별도 담당자 기동·엔진·CLI·상태경로
리눅스 (네이티브·화면 없음) 148 별도 담당자 위 + 보안 검토
WSL2 + 윈도우 크롬 151 관리자 위
윈도우 10 (네이티브) 151 별도 담당자 위 + E2E 실동작

🔵 모든 항목을 모든 환경에서 잰 것은 아닙니다. 보안 검토(무토큰 MCP 거부를 ss 로 확인, 엔진이 루프백 밖에서 안 닿음)는 리눅스에서, E2E(/health → /act → 실제 페이지 추출)는 윈도우에서 했습니다. UNC 경로(\\wsl.localhost\...)도 됩니다 — 안 될 거라 봤는데 실측으로 뒤집혔습니다.

보안 검토는 다른 머신의 리눅스에서 했습니다 — 토큰이 없으면 MCP HTTP 서버가 종료되고 소켓 자체를 열지 않습니다(ss 로 확인). 엔진은 127.0.0.1 에만 묶여 있어 같은 망에서도 안 닿습니다.


보안

이 도구는 내 모든 로그인이 들어있는 브라우저를 조종합니다. 그만큼 조심해야 해요.

  • 🔴 127.0.0.1 은 울타리가 아닙니다 — "나로 실행되는 프로세스면 통과"입니다. 크롬 디버깅 포트(9222)에는 인증이 없습니다. 그 컴퓨터의 아무 로컬 프로세스나 — 다른 앱, npm 설치 후크, 굴러다니는 스크립트 — 붙어서 내가 로그인한 모든 세션을 조작할 수 있습니다. 실측: 무관한 프로세스가 인증 없이 GET http://127.0.0.1:9222/json/list 로 열린 탭을 전부 조회했습니다. 그 컴퓨터에서 도는 것을 전부 신뢰할 때만 쓰십시오.
  • 엔진은 내 컴퓨터 안에서만(127.0.0.1) 열립니다. 절대 인터넷에 열지 마세요.
  • 🔴 mcp-server.js --host 0.0.0.0 옵션이 있고 모든 인터페이스에 열립니다. 코드가 경고를 내지만 그때는 이미 열린 뒤입니다. 신뢰하는 사설망(VPN/tailnet)이 아니면 127.0.0.1 을 쓰시고, 어느 쪽이든 토큰은 필수입니다.
  • MCP 원격 서버는 토큰이 없으면 안 켜집니다.
  • ./wb type 은 뭘 입력했는지 기록하지 않습니다 — 비밀번호일 수 있으니까요.
  • 쿠키 값은 어떤 명령으로도 화면에 나오지 않습니다.
  • 🔴 비밀번호·카드번호·주민번호를 이 도구로 넣지 마세요. 로그인은 직접 하시고, Wbrowser 는 그 세션을 재사용합니다.

로그인 백업

./sync-session.sh export   쿠키를 암호화해서 저장
./sync-session.sh import   다른 컴퓨터에서 복원
./sync-session.sh status   뭐가 저장돼 있나

🔴 쿠키는 비밀번호와 같은 급입니다 — 쿠키가 곧 로그인이에요. 저장할 곳이 실제로 암호화돼 있지 않으면 스크립트가 거부합니다.


환경변수

변수 기본값 용도
WBROWSER_CHROME 자동 크롬 실행파일 경로
WBROWSER_PROFILE_DIR ~/.wbrowser 프로파일 폴더
WBROWSER_PROFILE Default 그 안의 프로파일 이름
WBROWSER_CDP_PORT 9222 크롬 조종 포트
WBROWSER_PORT 7981 엔진 포트
WBROWSER_AGENT 자동 테두리·탭에 표시될 이름
WBROWSER_MCP_TOKEN — 원격 MCP 에 필수
WBROWSER_NOTES — 작업 일지를 남길 폴더 (선택)

재부팅한 다음에

한 줄이면 됩니다:

cd /path/to/Wbrowser && ./wb up

크롬과 엔진을 둘 다 켜고, 이미 떠 있으면 건드리지 않습니다. 그 다음 ./wb status 로 로그인이 살아있는지 보시면 됩니다 — 프로파일이 디스크에 있으니 보통은 그대로입니다.

엔진을 자동으로 켜두려면

# 리눅스 / WSL — systemd 사용자 서비스
./install.sh
systemctl --user status wbrowser

이건 엔진만 해당합니다. 브라우저는 직접 켜셔야 합니다 — 화면에 창이 뜨는 일이고, 로그인할 때마다 브라우저가 말없이 열리는 도구는 쓰고 싶지 않을 테니까요. 그래서 재부팅 후에는 여전히 ./wb up 이거나, 크롬을 직접 켜고 이미 떠 있는 엔진이 붙게 하면 됩니다.

맥과 윈도우에는 아직 설치 스크립트가 없습니다. 필요할 때 ./wb up 을 치십시오. (launchd plist 와 시작프로그램 바로가기 둘 다 어려운 건 아닙니다. 다만 실제 기기에서 재본 사람이 없어서 안 넣었습니다 — 이 문서는 실행해보지 않은 것을 적지 않습니다.)

🔴 평소 쓰는 프로파일에 --remote-debugging-port 를 붙이는 바로가기를 직접 만들지 마십시오. Chrome 136(2025년 3월)부터 거기서는 그 옵션이 무시됩니다 — 크롬은 뜨는데 포트는 안 열리고, 왜 안 되는지 아무 말도 안 해줍니다. launch.js 는 전용 --user-data-dir 을 넘기는데, 그게 지금 크롬이 유일하게 받아주는 방식입니다. ./wb up 에 맡기십시오.


아직 안 되는 것

  • 자동 테스트가 없습니다. CI 는 문법과 몇 가지 불변조건만 봅니다. 실제 브라우저를 건드리는 건 전부 네 환경에서 손으로 쟀습니다. 이 방식은 확장이 안 되고, 기여하실 수 있는 가장 값진 부분입니다.

  • 말을 알아듣는 기능은 없습니다. 셀렉터는 AI 가 정합니다. 다만 read 가 진짜 셀렉터를 알려주니 찍을 일은 없어요.

  • 크롬 계열만 됩니다. 파이어폭스는 이 방식(CDP)을 지원하지 않아요.

  • 크롬 프로세스 하나 = 포트 하나. 그 창 안에서 연 프로파일은 보이지만, 따로 실행한 크롬은 안 보입니다.


최신 상태 유지

./wb version          # 내 버전과, 새 릴리스가 있는지
wbrowser 0.4.0
🔵 A newer release is available: v0.5.0 (you have v0.4.0)

업데이트:

git pull && npm install                                  # clone 한 경우
git pull https://github.com/w-partners/Wbrowser main     # fork 한 경우

🔵 fork 는 이 저장소를 자동으로 따라오지 않습니다. GitHub 이 우리 커밋을 여러분의 사본으로 밀어주지 않기 때문입니다. 위 두 번째 명령이 원할 때 가져오는 방법입니다.

🔴 GitHub 에 못 닿으면 못 닿았다고 말합니다. 물어보지 못한 것을 "최신입니다"라고 하지 않습니다. 네트워크 확인을 아예 건너뛰려면 WBROWSER_NO_UPDATE_CHECK=1 — 어느 쪽이든 명령을 막지 않습니다.

아무것도 실행하지 않고 소식을 받으려면 저장소 페이지에서 Watch → Releases only 를 켜두면 됩니다.


기여하기 · 보안

  • CONTRIBUTING.md — 이 코드를 만든 규칙과 시험 방법
  • SECURITY.md — 🔴 위협 모델. 공용 컴퓨터에서 쓰기 전에 꼭 읽으십시오. 크롬 디버깅 포트에는 인증이 없어서, 나로 실행되는 아무 로컬 프로세스나 내 세션을 조작할 수 있습니다.

보안 문제를 찾으셨다면 공개 이슈 말고 비공개 advisory 로 알려주십시오.

라이선스

MIT — LICENSE 참고.