PC에서 실행 중인 개발 환경(파일 · 터미널 · Git · Agent · Remote View)을 Android 앱으로 원격 사용하는 개인용 브리지입니다.
Cursor를 폰에서 실행하지 않습니다. Cursor·코드는 PC에 그대로 두고, 폰은 Bridge를 통해 접근하는 클라이언트입니다.
| 역할 | 필요한 것 | 이 레포? |
|---|---|---|
| 폰 | Releases APK | ❌ 불필요 |
| PC (Bridge) | Node.js ≥ 20, pnpm + 이 레포 (지금은 Bridge 실행용) | ✅ 필요 |
| 작업할 코드 | PC에 있는 실제 프로젝트 폴더 (예: 다른 외주 레포) | ❌ 그 폴더만 있으면 됨 |
나중에 Bridge만 단독 설치 파일로 배포하면 PC도 전체 레포 없이 쓸 수 있습니다. 현재는 이 레포 = Bridge 설치라고 보면 됩니다.
요구: Node.js ≥ 20, pnpm
git clone https://github.com/HaeunJang271/CursorBridge.git
cd CursorBridge
pnpm install
pnpm buildpnpm bridge콘솔의 LAN URL 예: ws://192.168.x.x:8787/ws
최초 실행 시 페어링 토큰이 한 번만 표시됩니다. 반드시 저장하세요.
- PC·폰에 Tailscale 설치 후 같은 계정 로그인, Connected 확인
- PC:
pnpm bridge:tailscale- 콘솔 Tailscale URL 예:
ws://100.x.x.x:8787/ws
| 장소 | 명령 | 앱 URL |
|---|---|---|
| 집 Wi-Fi | pnpm bridge |
ws://192.168.x.x:8787/ws |
| 밖 | pnpm bridge:tailscale |
ws://100.x.x.x:8787/ws |
공유기에서 8787 포트포워딩은 하지 마세요.
Bridge가 접근할 로컬 경로를 등록합니다.
명령은 항상 이(CursorBridge) 레포 루트에서 실행합니다.
cd C:\path\to\CursorBridge
pnpm --filter @cursor-mobile/bridge register -- --id my-app --name "My App" --path "C:\Users\me\projects\actual-app"--path에는 예시가 아니라 실제 프로젝트 폴더를 넣습니다.- cafestudy 같은 다른 레포도 PC에만 있으면 등록 가능합니다. (그 레포를 clone할 필요는 없고, 경로만 등록)
등록 후 Bridge를 재시작하거나 앱에서 목록을 새로고침하세요.
- PC에서 Bridge가 계속 실행 중인지 확인
- 앱에 입력:
- URL: 콘솔에 나온
ws://…:8787/ws(http://아님, 끝/ws포함) - Token: 저장해 둔 페어링 토큰
- URL: 콘솔에 나온
- 연결 → 프로젝트 목록
연결 전 폰 브라우저로 http://PC_IP:8787/health 가 {"ok":true…} 인지 확인하면 네트워크 문제를 빨리 가릴 수 있습니다.
pnpm rotate-token콘솔에 새 토큰이 한 번만 표시됩니다. 앱에 다시 입력하세요.
(앱 연결 화면 하단 「토큰 재발급」에도 PC에서 이 명령을 쓰라는 안내가 있습니다.)
- URL이 모드와 맞는지 (집=
192.168…, 외출=100…) - 폰·PC 같은 Wi-Fi 또는 Tailscale 둘 다 Connected
- Windows 방화벽에서 TCP 8787 인바운드 허용 (관리자 PowerShell):
powershell -ExecutionPolicy Bypass -File .\scripts\open-bridge-firewall.ps1- Bridge 로그에
url: "/ws"가 찍히는지 — 안 찍히면 폰→PC가 막힌 것 - 토큰을 재발급했다면 새 토큰을 쓰는지
| 증상 | 조치 |
|---|---|
WARN: Tailscale IPv4 not found |
PC Tailscale 설치·로그인 후 Bridge 재시작 |
Tailscale IP가 169.254… |
터널 끊김. Tailscale 재연결 |
EADDRINUSE … :8787 |
이전 Bridge 프로세스 종료 후 재실행 |
| 집 URL로 외출 연결 | LAN은 밖에서 안 됨. Tailscale URL 사용 |
Android (Expo / React Native)
│ WebSocket + JSON protocol (HELLO → AUTH → READY)
▼
PC Bridge (Fastify + WS) ── 등록된 project root만 접근
├── Filesystem / Terminal / Git
├── Remote View / Preview
└── Agent (공식 SDK / CLI)
- Threat model:
docs/THREAT_MODEL.md - Cloudflare Tunnel / WireGuard:
docs/EXTERNAL_ACCESS.md
Health: http://127.0.0.1:8787/health
모노레포 구조: apps/bridge, apps/mobile, packages/shared.
pnpm install
pnpm build
pnpm testpnpm mobileExpo SDK 54. QR로 Expo Go 실행.
cd apps/mobile
pnpm exec eas login
pnpm build:apk| 프로필 | 결과 | 용도 |
|---|---|---|
preview |
APK | Releases / 직접 설치 |
production |
AAB | Play Store |
빌드 후 APK는 GitHub Release에 올리는 것을 권장합니다.
pnpm 모노레포입니다. 루트에
package-lock.json이 있으면 EAS가 npm으로 잘못 설치합니다.
SDK 54 호환:expo-font@~14,expo-secure-store@~15(expo install --check).
$env:CURSOR_API_KEY="your-key"
# optional: $env:CURSOR_AGENT_MODEL="composer-2.5"
pnpm bridge키 없으면 CLI probe(CURSOR_AGENT_ENABLED=1)로 폴백. 비공개 Cursor API는 사용하지 않습니다.
| 명령 | 설명 |
|---|---|
pnpm bridge |
LAN 모드 Bridge |
pnpm bridge:tailscale |
Tailscale 모드 Bridge |
pnpm rotate-token |
페어링 토큰 재발급 |
pnpm mobile |
Expo 개발 서버 |
pnpm mobile:apk |
EAS APK 빌드 |
pnpm build / pnpm test |
빌드·테스트 |
BRIDGE_MODE—lan(기본) |localhost|tailscaleBRIDGE_HOST/BRIDGE_PORT(기본8787) /BRIDGE_DATA_DIR/LOG_LEVELCURSOR_API_KEY—@cursor/sdkCURSOR_AGENT_MODEL— 기본composer-2.5CURSOR_AGENT_ENABLED/CURSOR_AGENT_BIN— SDK 없을 때 CLI 폴백
- 인증 없는 명령 실행 금지
- project root jail + sensitive 파일 차단
- 터미널
shell: false+ 메타문자 거부 - 공인 인터넷에 Bridge 포트 직접 노출 금지 (외출은 Tailscale)
- commit / push / pull 은 앱에서 확인 필수
- 상세:
docs/THREAT_MODEL.md
| 영역 | 상태 |
|---|---|
| Monorepo + shared protocol | ✅ |
| Auth + WS protocol | ✅ |
| Filesystem / Terminal / Git | ✅ |
| Android UI (SDK 54, 다크 테마, KO/EN) | ✅ |
| EAS Build + GitHub Releases APK | ✅ |
| Tailscale bind + CGNAT filter | ✅ |
| Remote View / Preview / Secure token / Agent SDK | ✅ |
| Pairing token rotate | ✅ |
- Bridge 단독 설치 패키지 (레포 없이 PC 설치) — 다음 목표
- Cloudflare Access / IdP 앞단 강제
- Agent 스트리밍 UI (현재는 완료 후 폴링)