🤖 Wbrowser

당신의 AI는 로그인 뒤에 있는 것을 볼 수 없습니다. 이 도구가 해결해 줍니다 — 당신이 실제로 쓰는 OS에서.

어시스턴트는 웹을 검색할 수 있지만, 당신의 받은 편지함, 대시보드, 회사 내부 도구는 열지 못합니다. 쓸모 있는 것은 핵심 모두 어시스턴트가 가지지 못한 로그인 뒤에 있습니다.

Wbrowser는 그것에 당신이 이미 로그인한 당신의 Chrome — 그 창에 자리를 마련해 줍니다. 같은 창, 같은 탭. 클릭이 어디에 닿는지 하나하나 지켜볼 수 있고, 작업 중간에 마우스를 다시 가져올 수도 있습니다.

비밀번호는 당신 곁을 떠나지 않습니다. 로그인은 손으로 직접, Chrome이 보관, Wbrowser는 이미 열려 있는 창을 구동할 뿐입니다.

Windows, macOS, Linux 및 WSL에서 실행됩니다 — 각 플랫폼별로 해당 부분을 작성한 사람이 아닌 다른 사람이 다른 머신에서 실제 하드웨어로 측정했습니다:

2026-08-24 측정. 모든 검사가 모든 환경에서 실행된 것은 아닙니다 — 자세한 내용은 Platform notes 참조.

JavaScript, Python, 셸 약 2,600줄입니다. MIT. 오후 한나절이면 다 읽고 용도에 맞게 창조로 바꿀 수 있는 크기입니다.

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

왜 이런 도구가 필요한가

AI 브라우저는 전부 비슷비슷한 모양을 하고 있습니다. 어시스턴트가 들어 있는 새 브라우저를 설치하는 겁니다 — Aside, Comet, Dia. 이 모양에는 세 가지 대가가 있습니다:

우리는 반대 선택을 했습니다. 새 브라우저 없이 — 지금 쓰는 Chrome, 기존 로그인을 그대로 쓰고, 어시스턴트는 당신이 이미 보고 있는 그 창 안에서 일 합니다. 클릭이 들어가는 것을 하니씩 보고, 작업 중 마우스를 다시 가져올 수 있습니다. 대익사항도, 넘겨줄 것도 없습니다.

그 선택 덕분에 Windows, macOS, Linux, WSL 모두에서 실행될 수 있습니다. 플랫폼마다 브라우저를 새로 만들 일이 없었으니까요, 정할 플랫폼도 없었고 말입니다.

필요한 게 있습니까? 직접 만들면 됩니다.

그것이 전부입니다. 다른 사람의 로드맵을 기다리는 제품이 아니라, 이미 쓰고 있는 머신에서, 이미 로그인된 브라우저 속에서 저희가 개발하던 작은 도구를 당신이 소유하는 것입니다. JavaScript, Python과 셸, 약 2,600줄 — 오후에 읽을 수 있는 정도입니다. 읽고, 바꾸고, 당신 것으로 만드세요.

Wbrowser는 Windows, macOS, Linux 및 WSL을 지원합니다 — "어떤 OS를 쓰는 중이야?"라는 질문이 이 브라우저 자동화 못 할 이유가 돼때가되면 안 되기 때문입니다. macOS, 네이티브 Linux, WSL2, Windows 네이티브에서 검증했습니다 — 검사는 전부 모든 플랫폼에서 실시되지 는 않았습니다 (Platform notes 참조).

Related MCP server: Chrome DevTools MCP

이게 무엇인가?

대부분의 자동화 도구는 AI에게 새로 만든 비어 있는 브라우저를 건네줍니다. 그래서 이메일, 대시보드, 로그인 뒤의 어떤 것도 못 보입니다 — 비밀번호가 넘겨지거나, 사이트마다 API 통합이 되어 있지 않는 한.

Wbrowser는 반대로 접근합니다. 일반 Chrome 창에 손으로 한 번 로그인해 두면, 그 후에는 터미널(혹은 AI 어시스턴트)가 그 동일한 창을 제어할 수 있습니다 — 이미 모든 곳에 로그인된 채로.

./wb go https://mail.example.com   # opens in YOUR logged-in session
./wb read                          # tells you what's on screen
./wb click '#compose'              # clicks it

Wbrowser는 비밀번호를 절대 알지 못합니다. 당신이 직접 입력하고 Chrome이 보관하고, Wbrowser는 그 이미 열려 있는 창을 몰 뿐입니다.

로그인 한 번이 여러 사이트를 여는 일

각개 작업을 못 물리 아낄 기키에 셋업을 제대로 으로 충분치가 할 만한 부분입니다. 그 창에서 구글로 한 번 로그인하면:

Google itself       google.com · youtube.com · your Workspace apps
Sites using Google SSO   your CRM, your booking system, your dashboards —
                         whatever "Sign in with Google" reaches
Everything else     log in by hand once; it stays

실제 프로파일에서 측정해 보았습니다. 구글 로그인 하나에 YouTube를 비롯한 Google SSO를 쓰는 업무 시스템 2개가 같이 풀렸습니다 — 그것들만은 별도로 로그인하지 않았습니다. 나머지(GitHub, Reddit, 은행 비슷한 포털)는 일일이 손으로 한 번 로그인해 두었고, 그것으로 충분히 이 후 로 유지되고 있습니다라는 것입니다.

즉, 설치적으로는 구글 로그인 한 번 + 구글을 쓰지 않는 서비스는 하나 하나당 한 번 정도의 로그인 전부입니다. 그 이후에는 에이전트가 모두에 접근합니다.

🔴 반대도 같은 사실입니다. 이 브라우저를 제어할 수 있는 존재라면, 그 모든 사이트에서 아무 일이나 할 수 있다는 뜻입니다. Security 절 참고하세요.

하지 않는 일

• 비밀번호를 요구하거나 저장하지 않습니다. 본인이 직접 입력 Chrome이 저장하면, Wbrowser는 이미 열린 창을 몰 것이다. type은 타이핑을 그 일기에 남기지 않습니다.

• 쿠키 값을 인쇄하지 않습니다. 출력에도 없고, 로그에도 없어 — 쿠키는 게 무엇보다도 로그인 자체이니까요.

• 어느 계정인지 맞추지 않습니다. 열려 있지 않은 계정을 이름으로 대면 그냥 실패합니다. 잘못된 계정에서 메일을 보내는 것이 오히려 오류 메시지보다 더 나쁩니다. — 오류 메시지가 가짜이니까요.

• 예약 시간 제출 / 결제 / 잊혀짐을 클릭하지 않습니다. 무인 작업은 해당 작업이 자체적으로 옵트인하지 않는 한 그런 단계를 거부합니다. 작업이 잘못되어도 아무도 보고 않습니다. 그런 와중에 크론잡이 망가지면… 그거니깐 거부하는 것입니다.

우리가 측정해서 감추지 않는 한 가지 제약

Chrome 디버깅 포트에는 인증이 없습니다. 해당 머신에서 당신 사용자로 실행되는 어떤 프로세스라도 접속해서 세션을 몰 수 있습니다 — 이것은 무관한 프로세스에서 접속해 탭 목록을 조회하는 방식으로 직접 확인했습니다. 127.0.0.1은 울타리가 없습니다. "당신으로 실행되는 것은 무엇든 지나갈 수 있습니다"를 의미하지요.

그건 Chrome의 설계로, 우리가 의도한 게 아니라 추가하지 않았습니다. 작업을 주는 모든 도구가 물려받는 사양입니다. 나중에 발견할 일을 견디는 것보다 어디쯤에 써두는 편이 낫다고 판단했다. — 전체 위협 모델은 Security 편을 보십시오.

시작하기

git clone https://github.com/<you>/Wbrowser.git
cd Wbrowser
# Wbrowser drives your *system* Chrome, so Playwright's own browser
# download is unnecessary — skip it and save ~400MB:
PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm install

node launch.js       # 1. opens a dedicated Chrome window
                     # 2. log into your sites in that window (by hand!)
node engine.js       # 3. start the control engine
./wb go https://example.com

네 된은 알입니다. 단계 2만 손으로 해주시면 됩니다.

wb를 실행하며 "Permission denied"가 나오면 — 클로닝 과정에서 실행 실행 파일 비트가 살지 못한 것일 수 있습니다(어떤 구성에서는 없애버리기도 합니다). 이렇게 한 번만 고치면 됩니다:

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

헤드리스(디스플레이 없는) 서버의 경우: Wbrowser가 $DISPLAY 변수의 부재를 감지하고 자동으로 헤드리스 모드로 띄웁니다. WBROWSER_HEADLESS=1 또는 =0으로 쓰여는 방향으로 강객 수 있습니다. 수동 로그인할 화면이 없으므로, 데스크톱 머신에서 ./sync-session.sh import로 세션을 가져오면 됩니다.

Windows 사용자: 커뮤니티 WSL 안에서 실행하거나 Windows 내에서 바로 node 명령을 쓰면 됩니다 — 두 방법 모두 작동합니다. Platform notes 참조.

왜 별도의 Chrome 창을 쓰는가

Chrome 136(2025년 3월)부터 Chrome 기본 사용자 데이터 디렉토리에 대해 --remote-debugging-port는 무시됩니다. Chrome이 이렇게 바꾼 것은 공격자가 디버깅 포트로 쿠키를 가져당가게 하는 이용을 막으려는 의도였기 때문입니다.

그래서 기본값이 아닌 --user-data-dir을 쓰는 것은 이제 필수입니다. Wbrowser는 이 값을 ~/.wbrowser에 만들어 두고 여기veness Chrome을 실행합니다.

결국 기존 로그인 그대로 옮겨지지는 않습니다. 새 창에서 한 번 더 로그인하면, 이후에는 그곳에서 유지됩니다.

⚠️ Chrome 프로필 폴더를 복사하면 동작하지 않습니다. 실제로 실험해 보면 685개 쿠키가 3개가 되고 세션 쿠키가 모두 폐기되었습니다. Chrome은 알지 못하는 프로필을 무효화합니다. 새로 하나 로그인 하는 것이 끝입니다. — 한 분만 걸리면 되고 실제로 되고요.

명령어

./wb go <url>              open a page, return its structure
./wb read                  summarize the current page
./wb click <selector>      click an element
./wb type <selector> <text>   fill an input
./wb press <key>           Enter, Tab, Escape, ArrowDown…
./wb eval '<js>'           run JavaScript in the page
./wb console [regex]       console logs + uncaught exceptions
./wb network               failed requests (4xx/5xx, CORS, timeouts)
./wb shot [file.png]       screenshot
./wb tabs                  open tabs, grouped by agent
./wb close                 close only the tabs you opened
./wb status                is everything up? which profile?
./wb show                  bring the browser window to the front

선택자를 추리지 말 것

./wb read는 페이지에 있는 실제의 클릭 가능한 엘리먼트를 돌려줍니다:

inputs(1):
  - #searchbox_input  (Search the web without being tracked)
buttons(3): Search, Sign in, Settings

거기서 복사하세요. (예전에 검색 칸을 input[name=q]라고 추측했는데, 그것은 textarea였습니다. read가 처음부터 정확히 말해줬죠.)

어시스턴트에게 방향 것만 말하세요

연결이 되고 나면 명령 하나씩 입력하기 대신 원하는 결과를 말하십시오:

"내 대시보드를 열고 오늘의 수치를 요약해 줘." "그 쇼핑 사이트에서 내 장바구니에 뭐가 들었어?" "예약이 실제로 확정된지 확인해 줘."

연결은 Model Context Protocol을 사용합니다 — MCP를 지원하는 어시스턴트에서(Claude, Cursor 등을 포함) 설정 몇 줄이면 바로 난다.

로컬(stdio):

{
  "mcpServers": {
    "wbrowser": {
      "command": "node",
      "args": ["/path/to/Wbrowser/mcp-server.js"]
    }
  }
}

원격(HTTP):

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

그 다음에는 그냥 어시스턴트에게 이야기하기만 하면 됩니다:

"내 대시보드를 열어서 오늘 수치 요약해 줘." "그 쇼핑 사이트의 장바구니에는 무엇이 들어 있지?"

도구: browser_open browser_read browser_click browser_type browser_press_Key browser_eval browser_console browser_screenshot browser_console browser_status

중요한 것은 상점 내용:

🔴 원격 서버는 토큰 없이 실행을 거부합니다. 이 개선 사항은 선택이 없습니다 — 모든 로그인의 브라우저를 구동하기 때문입니다. 해당 포트에 도달하는 사람은 그대로 당신이 됩니다.

에이전트가 몰고 가기 전에 알아 두어야 할 것

이 항목들은 실제 만들다가 저지른 실수에서 나왔습니다. Wbrowser용 스킬/프롬프트를 직접 잴 때 그대로 넣어두세요:

1. 선택자를 추측하지 말 것. browser_read는 그 페이지의 진짜 항목을 반환합니다. 검색창에 input[name=q]를 쓸 뻔했습니다; 정체는 textarea였고 .read가 처음부터 그걸 알려치 않고 있었습니다.

2. 제출 전에 폼을 다시 읽을 것. 여러 개를 동시에 넣는 어떤 폼에서, 행 2~10에 거래처 필드가 비어 있었는데 "유지" 체크 박스가 그 행들을 덮고 있지 않았기 때문이었습니다. 클릭하기 전에 그 행을 전부 읽어보는 과정에서 발견했습니다. 먼저 클릭이 되어 있었렸다면 못 됐던 레코드 9개가 쌓였을 것입니다 돌 수 있스.

3. 반복할 때는 횟수를 세어 본다. 엔터 연속 8회를 보내니 행이 40개가 만들어졌습니다 — 페이지가 생각보다 빨랐 처리하는 것입니다. 한 번 누르고, 세어 보고, 목표해서 멈추세요.

4. 프레임워크 폼은 eval이 type보다 우세하고, eval이 효용이 없을 때는 type가 낫습니다. React는 직접 value 세팅을 무시합니다. — 기본 네이티브 setter와 input/change 이벤트를 쓰세요. 그래도 바뀌지 않면 browser_type가 실제 키 입력으로 해결해 줍니다.

5. 자기가 붙어 있는 곳을 확인할 것. browser_status는 그 창에 실제 로그인 정보가 있는지 알려줍니다. 텅 빈 프로필은 아무것도 하지 않으면서 모든 명령에 성공했다고 회신합니다.

크론 작업

jobs/morning-check.json 파일을 만들어 주세요:

{
  "schedule": "0 9 * * 1-5",
  "tab": "morning",
  "steps": [
    { "goto": "https://dashboard.example.com", "wait": 2000 },
    { "eval": "document.querySelector('.total').innerText" },
    { "shot": true }
  ]
}

node cron.js list      # what's registered
node cron.js next      # when each job runs next
node cron.js run <name>   # run once, now
node cron.js daemon    # run on schedule

0 9 * * 1-5 = 0분, 9시, 평일. 표준 5필드 크론 정보입니다.

되돌리지 못할 작업은 기본적으로 막아놓음

무인 자동화는 잘못되면 아무가 지켜주지 않는 다는 것을 뜻합니다. 그래서 제출 / 결제 / 삭제처럼 보이는 행동들을 **거부합니다 **:

⛔ step 2 blocked — looks irreversible (click: #submit-payment)
   If you meant it, add "allowIrreversible": true to the job file.

작업이 하나 하나 그렇게 옵트인하는 형태이지, 전역으로 풀지 않습니다.

누가 운영하고 있나? (시각 표시)

에이전트가 브라우저를 조작 중이면 눈에 보입니다.

영역을 처리 중:

• 페이지 주변에 반투명 테두리와 표지: 🤖 my-agent in control

• 탭 제목에 앞자리가 붙음: [my-agent] Dashboard

테두리는 6초동안 움직임이 없으면 사라지므로, "제어 중"이라는 것은 바로 지금을 의미합니다. 색은 에이전트 이름에서 계산되기 때문에 여러 에이전트가 한눈에 구분됩니다.

탭 접두도 탐색이 갈아 치워져도 살아남습니다 — 페이지가 자기 제목을 스스로 다시 쓰는(단일 화면 응용 프로그램, SPA들이 자주 하는) 일이 있어도 MutationObserver가 다시 적용합니다.

여러 계정 운영

Chrome의 프로필 전환기처럼 같은 창에 여러 Chrome 프로필을 연 다음 Wbrowser가 그것들을 가리켜라 따로 지정할 수 있습니다:

./wb -a work@example.com go https://mail.example.com
./wb windows                    # list open profiles

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

{
  "sites": {
    "mail.example.com": { "account": "work@example.com" }
  }
}

🔴 열려 있지 않은 계정을 이름으로 대면, 사이좋게 알아듣지 않고 Wbrowser는 아예 실패 합니다. 틀린 계정으로 메일을 보내는 것은 오류 메시지보다 더 나은 것이 아닙니다.

플랫폼 노트

으로 감지되지 않으면 WBROWSER_CHROME=/path/to/chrome로 지정할 수 있습니다.

실제 하드웨어에서 테스트함 (2026-08-24):

플랫폼	Chrome	검증자	측정 항목
macOS 15	151	별도 검증자	실행 · 엔진 · CLI · 상태 경로
Linux (네이티브, 헤드리스)	148	별도 검증자	위와 동일 + 보안 검토
WSL2 + Windows Chrome	151	메인테이너	위와 동일
Windows 10 (네이티브)	151	별도 검증자	위와 동일 + 엔드투엔드

모든 플랫폼에서 모든 검사가 실행된 것은 아닙니다. 보안 검토(토큰 없는 MCP 거부를 ss로 확인, 루프백 밖에서는 엔진 접근 불가)는 Linux에서 수행했습니다. 엔드투엔드 실행(/health → /act → 실제 페이지 추출)은 Windows에서 수행했습니다. UNC 경로(\\wsl.localhost\...)도 동작합니다 — 예상과 달리, 측정으로 확인했습니다.

보안 검토는 별도 머신의 Linux에서 수행했습니다. 즉, 토큰이 없으면 MCP HTTP 서버는 종료되고 소켓을 절대 열지 않습니다(ss로 확인). 엔진은 127.0.0.1에만 바인딩되므로 tailnet을 통해서는 접근할 수 없습니다.

Security

이 도구는 당신의 모든 로그인 이 담긴 브라우저를 제어합니다. 그에 맞게 취급하세요.

• 🔴 127.0.0.1은 벽이 아닙니다 — 즉 "당신 권한으로 실행되는 프로세스는 모두 들어온다"는 뜻입니다. Chrome 디버깅 포트(9222)에는 인증이 없습니다. 그 머신의 어떤 로컬 프로세스든 — 다른 앱, npm postinstall 훅, 방치된 스크립트 — 로그인되어 있는 모든 세션에 붙어 조종할 수 있습니다. 실제 측정 결과: 무관한 프로세스가 자격 증명 없이 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 HTTP 서버는 토큰을 필수로 요구하며, 토큰이 없으면 시작을 거부합니다.

• ./wb type 명령은 입력된 내용을 기록하지 않습니다 — 비밀번호일 수 있기 때문입니다.

• 쿠키 값은 어떤 명령에서도 절대 출력하거나 기록하거나 반환되지 않습니다.

• 비밀번호, 카드 번호, 정부 발급 신분증을 입력하는 데에 이 도구를 사용하지 마세요. 직접 로그인하세요. Wbrowser가 그 세션을 이어받습니다.

세션 백업

./sync-session.sh export   # cookies → encrypted store
./sync-session.sh import   # restore on another machine
./sync-session.sh status

🔴 쿠키는 비밀번호만큼 민감합니다 — 쿠키가 곧 로그인 자체입니다. 스크립트는 대상이 실제로 암호화되어 있지 않으면 기록을 거부하고, 해독할 수 없는 암호문에서 복원하는 것도 거부합니다.

환경 변수

부팅 시 실행

# Linux / WSL (systemd user service)
./install.sh
systemctl --user status wbrowser

엔진은 자동으로 시작됩니다. 브라우저는 여전히 직접 실행해야 합니다 — 데스크톱 프로세스이므로, 언제 켤지는 당신의 선택이어야 합니다.

알려진 제한 사항

• 자동화된 테스트 스위트가 없습니다. CI는 문법과 몇 가지 불변 조건을 검사하며, 실제 브라우저를 다루는 모든 것은 네 플랫폼에서 수동으로 측정했습니다. 그 방식은 확장이 어렵고, 따라서 자동화 테스트 스위트가 기여자가 추가할 수 있는 가장 유용한 것입니다.

• 자연어 루프는 내장되어 있지 않습니다. 에이전트가 셀렉터를 고르고, read가 실제 셀렉터를 제공하므로 추측할 필요가 없습니다.

• Chrome/Chromium 전용입니다. Firefox에는 CDP가 없습니다.

• CDP 포트 하나 = Chrome 프로세스 하나입니다. 그 창 안에서 열린 프로필은 보이지만, 별도로 실행한 Chrome은 보이지 않습니다.

기여 및 보안

• CONTRIBUTING.md — 이 코드를 규정한 규칙과 시험하는 방법

• SECURITY.md — 🔴 위협 모델. 공유 머신에서 실행하기 전에 미리 읽으세요. Chrome 디버깅 포트는 인증이 없으므로, 여러 사용자로 실행되는 어떤 로컬 프로세스든 당신의 세션을 조종할 수 있습니다.

보안 문제를 발견하셨나요? 공개 이슈 대신 private advisory를 열어 주세요.

라이선스

MIT — LICENSE 참조.