<p>
<img src="https://raw.githubusercontent.com/nicobailon/surf-cli/HEAD/surf-banner.png" alt="surf" width="1100">
</p>
Surf
AI 에이전트가 Chrome을 제어하기 위한 CLI 도구입니다. 설정 불필요(Zero config), 특정 에이전트에 구애받지 않음(agent-agnostic), 실전 검증됨(battle-tested).
npm version
License: MIT
Platform
현재 릴리스 노트는 CHANGELOG를 확인하세요.
surf go "https://example.com"
surf read
surf click e5
...
Surf가 필요한 이유 (Why Surf)
AI 에이전트를 위한 브라우저 자동화는 보이는 것보다 어렵습니다. 대부분의 도구는 복잡한 설정이 필요하거나, 특정 AI 제공업체에 종속되거나, 실제 웹 페이지에서 작동하지 않는 문제가 있습니다.
Surf는 다른 접근 방식을 취합니다:
Agent-Agnostic (에이전트에 구애받지 않음) - Unix 소켓을 통한 순수 CLI 명령어입니다. Claude Code, GPT, Gemini, Cursor, 사용자 지정 에이전트, 셸 스크립트 등 명령어를 실행할 수 있는 모든 것과 작동합니다.
Zero Config (설정 불필요) - 확장 프로그램을 설치하고 명령을 실행하기만 하면 됩니다. 설정해야 할 MCP 서버도 없고, 리레이 프로세스도 없으며, 구독료도 필요 없습니다.
Battle-Tested (실전 검증됨) - 프로덕션 브라우저 확장 프로그램을 역설계(reverse-engineering)하여 Discord 설정과 같은 에이전트가 방해하기 쉬운 페이지들을 체계적으로 테스트했습니다. CDP(Chrome DevTools Protocol)가 실패할 경우에도 우아하게 폴백합니다.
Smart Defaults (스마트 기본값) - 스크린샷은 자동으로 1200px로 크기가 조정되어 토큰을 절약합니다. 액션 수행 시 자동 스크린샷 캡처를 통해 왕복(round-trips)을 절약합니다. 제한된 페이지에서의 오류는 실패 처리 대신 경고 메시지를 표시합니다.
AI Without API Keys (API 키가 필요 없는 AI) - 기존 브라우저 로그인 정보를 사용하여 ChatGPT, Gemini, Perplexity, Grok에 질의할 수 있습니다. 별도의 API 키가 필요하지 않습니다.
Network Capture (네트워크 캡처) - 활성화된 동안 모든 네트워크 요청을 자동으로 기록합니다. 요청 가로채기(request interception)를 수동으로 설정할 필요 없이 API 호출을 필터링, 검색 및 재생할 수 있습니다.
비교 (Comparison)
| 기능 | Surf | Manus | Claude Extension | DevTools MCP | dev-browser |
|---|
| Agent-agnostic | Yes | No (Manus only) | No (Claude only) | Partial | No (Claude skill) |
| ... | | | | | |
설치 (Installation)
빠른 시작 (Quick Start)
npm install -g surf-cli
...
모든 Surf 빌드는 동일한 확장 프로그램 ID (oaclimdkkglbnpekeignmjenkodkaaka)를 가지고 있으므로, surf install은 ID가 필요하지 않습니다. 만약 다른 ID를 가진 포크(fork)나 다른 빌드를 로드하는 경우, 다음과 같이 전달합니다: surf install <extension-id>.
surf install은 또한 이 패키지의 skills/surf에 ~/.claude/skills/surf와 ~/.pi/agent/skills/surf (해당 폴더가 존재하는 경우)를 연결합니다. 사용자가 직접 만든 스킬 폴더는 절대 대체하지 않습니다.
surf update는 surf를 재설치하거나 (또는 git 체크아웃을 다시 빌드) 네이티브 호스트 및 스킬 링크를 새로 고치고, 확장 프로그램을 다시 로드하며, 이전 버전과 이후 버전을 출력합니다. 처음 사용할 때는 chrome://extensions에서 수동으로 Surf를 한 번 다시 로드하십시오.
chrome://extensions에서 개발자 모드(Developer mode)를 켜 두십시오: 이 기능이 꺼져 있으면 Chrome은 스스로 재로드하는 언패키지 확장 프로그램(unpacked extension)을 비활성화합니다. 재로드는 세션마다 Surf를 재시작하므로, 다른 세션에서 실행되는 명령어는 실패합니다.
다중 브라우저 지원 (Multi-Browser Support)
surf install
surf install --browser brave
surf install --browser helium
...
지원되는 브라우저: chrome, chromium, brave, edge, arc, helium
브라우저 자동 시작 설정 (Start the browser automatically)
Surf가 실행되고 있지 않을 때 브라우저를 시작하도록 하려면, 이 내용을 surf.json(현재 디렉토리 또는 홈 디렉토리)에 추가하십시오:
{ "browser": { "autostart": true, "app": "chrome" } }
대부분의 명령어는 실행 중인 브라우저를 찾지 못하면 이를 시작하고, Surf 확장 프로그램이 연결될 때까지 기다린 후 (최대 30초 또는 timeoutMs) 실행됩니다. 스트림(streams), record, 그리고 extract와 같은 복합 명령어는 브라우저를 시작하지 않습니다. surf go <url>은 해당 페이지에서 브라우저를 엽니다. app은 위의 브라우저 중 하나입니다 (기본값: chrome); Linux에서는 Surf가 PATH에 있는 브라우저의 일반 바이너리를 실행합니다. 다른 방식으로 시작하려면, 대신 전체 명령어를 제공하십시오. 예를 들어 `
WSL2와 Windows Chrome 사용 시
WSL2 내부에서 surf install을 실행하면, Surf는 WSL2를 감지하고 기본적으로 Windows Chrome/Brave/Edge용 Windows 측 네이티브 메시징 매니페스트(native messaging manifest)를 설치합니다. 생성된 Windows 래퍼(wrapper)가 wsl.exe로 WSL2 호스트를 실행하므로, WSL2 내부에서 실행되는 surf 명령어는 여전히 WSL 소켓에 연결됩니다.
만약 대신 WSLg 내의 리눅스 브라우저를 사용한다면, 다음 명령어로 설치하세요:
surf install --target linux
설치 후 Windows Chrome을 재시작해야 합니다. 만약 확장 프로그램에서 Access to the specified native messaging host is forbidden 오류가 보고되면, 동일한 WSL 배포판(distro)에서 surf install을 다시 실행하고, chrome://extensions에 Surf의 ID가 oaclimdkkglbnpekeignmjenkodkaaka로 표시되는지 확인하거나 (또는 표시된 ID를 전달하세요).
패키지 관리자 설치 (Nix, Homebrew 등)
만약 surf가 표준적이지 않은 위치에 바이너리를 저장하는 패키지 관리자를 통해 설치되었다면, surf install을 실행하기 전에 다음 환경 변수들을 설정하세요:
export SURF_NODE_PATH=/path/to/node
export SURF_HOST_PATH=/path/to/native/host.cjs
export SURF_EXTENSION_PATH=/path/to/extension/dist
자세한 내용은 환경 변수를 참조하세요.
제거 (Uninstall)
surf uninstall
surf uninstall --all
surf uninstall --target linux
Tailscale을 통한 원격 Surf 연결 (Remote Surf over Tailscale)
원격 Surf는 브라우저와 네이티브 호스트를 하나의 Tailnet 머신에서 실행하고, CLI는 다른 머신에서 실행합니다. 리스너(listener)는 브라우저 확장 프로그램의 네이티브 메시징 연결(native-messaging connection)이 활성화된 동안에만 사용할 수 있습니다. Tailnet 도달 가능성(reachability)은 권한 부여(authorization)를 의미하지 않습니다: 모든 원격 클라이언트는 자체 Surf 자격 증명(credential)을 필요로 합니다.
브라우저 호스트에서 리스너를 설치하기 전에 클라이언트를 승인하세요:
surf remote authorize agent-macbook --output ~/agent-macbook.surf-credential.json
surf remote list
surf install --listen 100.101.102.103:4321
authorize는 클라이언트의 Ed25519 개인 식별자(private identity)와 고정된 호스트 식별자를 포함하는 mode-0600 자격 증명(credential)을 생성합니다. 이를 기존 보안 채널을 통해 해당 클라이언트로 이동한 다음, 더 이상 필요하지 않은 경우 호스트에서 생성된 사본을 제거해야 합니다. 호스트는 ~/.surf/remote/remote-clients.json에 오직 클라이언트의 공개 식별자(public identity)만 유지합니다.
승인된 클라이언트에서:
surf --remote 100.101.102.103:4321 \
--remote-credential ~/.config/surf/agent-macbook.json \
tab.list
...
네이티브 호스트의 기존 clear-TCP 리스너 앞에 위치하는 TLS 종료형(TLS-terminating) 리버스 프록시를 사용하려면 클라이언트에서 옵트인해야 합니다:
surf --remote surf.example.com:443 --remote-tls \
--remote-credential ~/.config/surf/agent-macbook.json tab.list
...
--remote-tls-ca는 Node의 시스템 루트에 추가하는 대신 이를 대체합니다. DNS 엔드포인트는 SNI(Server Name Indication) 및 인증서 검증을 위해 호스트 이름을 사용하며, IP 엔드포인트는 --remote-tls-server-name이 DNS 식별자를 제공하지 않는 한 SNI를 생략하고 인증서의 IP SAN(Subject Alternative Name)을 검증합니다. TLS 인증서 검증은 필수적인 Ed25519 인증 이전에 완료됩니다. Surf에는 안전하지 않은 모드(insecure mode), 다운그레이드, 또는 평문 재시도 기능이 없습니다. SURF_REMOTE_TLS=1만이 허용되는 환경 변수 표기법이며, 이를 해제하면 TLS가 비활성화됩니다. 환경 변수로 활성화된 TLS에 대한 CLI 부정(negation)은 없습니다. CLI 값은 SURF_REMOTE_TLS_CA와 SURF_REMOTE_TLS_SERVER_NAME을 독립적으로 덮어씁니다. SURF_LISTEN은 리버스 프록시 뒤에서 평문 리스너로 남아 있으며, Surf는 브라우저 호스트에서 TLS를 종료하지 않습니다.
Surf는 신선한 nonce를 사용한 상호 Ed25519 챌린지-응답(challenge-response)을 수행하며 연결 전반에 걸쳐 권한을 확인합니다. 자격 증명은 신뢰할 수 있는 로컬 Surf 사용자에게 부여되는 것과 동일한 브라우저 및 호스트 파일 권한을 부여합니다. 각 클라이언트에는 고유한 자격 증명을 제공하고, 공유하지 않으며, 클라이언트나 파일이 분실되면 즉시 폐기해야 합니다:
surf remote revoke agent-macbook
surf remote list
--remote <호스트>:<포트>는 SURF_REMOTE보다 우선하며, --remote-credential은 SURF_REMOTE_CREDENTIAL보다 우선합니다. 선택된 원격 엔드포인트는 SURF_SOCKET 및 기본 로컬 소켓을 재정의합니다. 로컬 요청과 원격 요청은 동일한 호스트 스케줄러를 공유합니다: 각 탭은 FIFO 레인을 가지며, 여러 탭이 동시에 실행될 수 있고, 브라우저 전체 쓰기 작업(browser-wide writers)은 독점적입니다. 연결 끊김 및 시간 초과는 대기 중이거나 진행 중인 작업을 중단시키고, 요청 소유의 정리(cleanup)가 완료되거나 하드 데드라인에 도달할 때까지 진입을 유지합니다. 이미 완료된 브라우저 측 부작용은 롤백되지 않습니다.
surf install --listen은 명시적인 Tailnet 주소를 네이티브 호스트 래퍼(native-host wrapper)에 영구 저장합니다. --listen 없이 surf install을 다시 실행하여 이를 제거할 수 있습니다. 이 주소는 포트가 포함된 Tailscale IPv4 또는 IPv6 주소여야 하며, Surf는 모든 인터페이스에 바인딩하지 않습니다. 원격 리스너는 현재 POSIX 브라우저 호스트를 필요로 하며 Windows 네이티브 호스트 래퍼에서는 지원되지 않습니다.
고급 로컬 전용 공유의 경우, surf install --socket-mode 660 --socket-group <그룹>을 사용하여 옵트인 그룹 소켓(opt-in group-owned socket)을 영구 저장합니다. 기본값은 모드 600으로 유지되며, 모드 660은 해당 그룹의 모든 계정에 완전한 Surf 권한을 부여하므로 전용의 좁은 그룹을 사용해야 합니다. 이 플래그 없이 surf install을 다시 실행하여 영구 저장된 소켓 설정을 지울 수 있습니다. 원격 Surf 자격 증명(credentials)은 여전히 취소 가능한 클라이언트별 대안으로 남아 있습니다.
Tailscale 정책 제한을 깊이 방어(defense in depth)로 유지하십시오. 예를 들면:
태그와 포트를 Tailnet에 맞게 조정하십시오. Surf 인증은 Tailnet 정책을 대체하지 않습니다. 선택적 아웃바운드 원격 TLS는 클라이언트-프록시 연결을 보호하며, Surf가 SSH 터널이나 TLS 리스너를 추가하는 것은 아닙니다.
작동 및 문제 해결(Operations and troubleshooting)
tailscale status
tailscale ping 100.101.102.103
surf doctor --remote 100.101.102.103:4321 \
...```
`tailscale status`와 `tailscale ping`을 사용하여 도달 가능성(reachability)을 확인한 다음, `doctor`를 사용하여 엔드포인트 선택 및 인증을 검증하십시오.
**원격 파일 시스템 및 전송 의미론(Remote filesystem and transfer semantics)**
접두사가 없는 경로와 `local:` 경로는 클라이언트를 참조합니다. 오직 `remote:/절대/경로`만이 브라우저 호스트를 직접 참조합니다. 예를 들면:
```bash
surf --remote "$SURF_REMOTE" --remote-credential "$SURF_REMOTE_CREDENTIAL" \
upload --ref e5 --files ./client-file.pdf
surf --remote "$SURF_REMOTE" --remote-credential "$SURF_REMOTE_CREDENTIAL" \
...
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
클라이언트 로컬 입력값은 호스트에 비공개로 스테이징되며 요청 후 제거됩니다. 클라이언트 로컬 출력값은 크기/해시 검증을 거쳐 원자적(atomic) 목적지 교체 방식으로 다운로드됩니다. surf js --file과 perf-audit --output은 클라이언트 자체에서 처리됩니다. network.export는 기본적으로 생성된 클라이언트 로컬의 .json, .jsonl, 또는 .har 경로를 사용합니다. Gemini 편집본은 기본적으로 클라이언트 로컬의 edited.png로 지정됩니다. 성공적인 원격 작업은 자동 스크린샷을 생성된 클라이언트 로컬 경로로 전송하며, 실패 시 --auto-capture는 별도의 스크린샷 및 콘솔 진단으로 남습니다.
원격 단일 파일 경계(single-file boundary)는 upload 파일 1개, ChatGPT 첨부파일 1개, 또는 Gemini 첨부/편집 입력 1개, 그리고 스크린샷, 네트워크 내보내기, 또는 Gemini 이미지 출력 중 하나를 지원합니다. 전송은 파일당 256 MiB, 연결당 512 MiB 및 최대 32개의 파일을 제한하며, 디코딩된 청크는 256 KiB입니다. 원격 record, video, aistudio.build 스모크 스크린샷 디렉토리, 디렉토리 전송, 다중 파일 입력은 의도적으로 거부됩니다. remote: 경로는 전송을 우회하며 신뢰할 수 있는 클라이언트에게 해당 절대 호스트 경로에 대한 직접적인 권한을 부여합니다.
개발 환경 설정(Development Setup)
git clone https://github.com/nicobailon/surf-cli.git
cd surf-cli
npm install
...
사용법(Usage)
surf <command> [args] [options]
surf --help
surf --llm-context
...
탐색(Navigation)
surf go "https://example.com"
surf back
surf forward
...
페이지 읽기(Reading Pages)
surf read
surf read --all
surf read --include-hidden
...
Claude 아티팩트나 다른 렌더링된 DOM의 정적 내보내기(static export)가 필요할 때는 페이지 로드 후에 surf page.html --strip-scripts를 사용하십시오. 하나의 요소를 내보내려면 --selector <css>를 사용하십시오.