Skip to content

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Cursor Mobile Bridge

PC에서 실행 중인 개발 환경(파일 · 터미널 · Git · Agent · Remote View)을 Android 앱으로 원격 사용하는 개인용 브리지입니다.

Cursor를 폰에서 실행하지 않습니다. Cursor·코드는 PC에 그대로 두고, 폰은 Bridge를 통해 접근하는 클라이언트입니다.

누가 무엇을 설치하나요?

역할 필요한 것 이 레포?
폰 Releases APK ❌ 불필요
PC (Bridge) Node.js ≥ 20, pnpm + 이 레포 (지금은 Bridge 실행용) ✅ 필요
작업할 코드 PC에 있는 실제 프로젝트 폴더 (예: 다른 외주 레포) ❌ 그 폴더만 있으면 됨

나중에 Bridge만 단독 설치 파일로 배포하면 PC도 전체 레포 없이 쓸 수 있습니다. 현재는 이 레포 = Bridge 설치라고 보면 됩니다.


사용자 가이드 (빠른 시작)

1. 폰 — APK 설치

  1. Releases에서 cursor-bridge-*.apk 다운로드
  2. 최신: v0.1.3
  3. Android에서 “알 수 없는 앱” 설치 허용 후 설치

2. PC — Bridge 설치·실행

요구: Node.js ≥ 20, pnpm

git clone https://github.com/HaeunJang271/CursorBridge.git
cd CursorBridge
pnpm install
pnpm build

집 Wi-Fi

pnpm bridge

콘솔의 LAN URL 예: ws://192.168.x.x:8787/ws
최초 실행 시 페어링 토큰이 한 번만 표시됩니다. 반드시 저장하세요.

외출 (Tailscale)

  1. PC·폰에 Tailscale 설치 후 같은 계정 로그인, Connected 확인
  2. PC:
pnpm bridge:tailscale
  1. 콘솔 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 포트포워딩은 하지 마세요.

3. 프로젝트 등록 (PC에 있는 폴더)

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를 재시작하거나 앱에서 목록을 새로고침하세요.

4. 폰에서 연결

  1. PC에서 Bridge가 계속 실행 중인지 확인
  2. 앱에 입력:
    • URL: 콘솔에 나온 ws://…:8787/ws (http:// 아님, 끝 /ws 포함)
    • Token: 저장해 둔 페어링 토큰
  3. 연결 → 프로젝트 목록

연결 전 폰 브라우저로 http://PC_IP:8787/health 가 {"ok":true…} 인지 확인하면 네트워크 문제를 빨리 가릴 수 있습니다.

토큰 재발급

pnpm rotate-token

콘솔에 새 토큰이 한 번만 표시됩니다. 앱에 다시 입력하세요.
(앱 연결 화면 하단 「토큰 재발급」에도 PC에서 이 명령을 쓰라는 안내가 있습니다.)

연결이 안 될 때

  1. URL이 모드와 맞는지 (집=192.168…, 외출=100…)
  2. 폰·PC 같은 Wi-Fi 또는 Tailscale 둘 다 Connected
  3. Windows 방화벽에서 TCP 8787 인바운드 허용 (관리자 PowerShell):
powershell -ExecutionPolicy Bypass -File .\scripts\open-bridge-firewall.ps1
  1. Bridge 로그에 url: "/ws" 가 찍히는지 — 안 찍히면 폰→PC가 막힌 것
  2. 토큰을 재발급했다면 새 토큰을 쓰는지

Tailscale 트러블슈팅

증상 조치
WARN: Tailscale IPv4 not found PC Tailscale 설치·로그인 후 Bridge 재시작
Tailscale IP가 169.254… 터널 끊김. Tailscale 재연결
EADDRINUSE … :8787 이전 Bridge 프로세스 종료 후 재실행
집 URL로 외출 연결 LAN은 밖에서 안 됨. Tailscale URL 사용

Architecture

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)

Health: http://127.0.0.1:8787/health


개발자 가이드

모노레포 구조: apps/bridge, apps/mobile, packages/shared.

pnpm install
pnpm build
pnpm test

모바일 개발 (Expo Go)

pnpm mobile

Expo SDK 54. QR로 Expo Go 실행.

APK 빌드 (EAS)

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).

Agent (공식 SDK)

$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 | tailscale
  • BRIDGE_HOST / BRIDGE_PORT (기본 8787) / BRIDGE_DATA_DIR / LOG_LEVEL
  • CURSOR_API_KEY — @cursor/sdk
  • CURSOR_AGENT_MODEL — 기본 composer-2.5
  • CURSOR_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 (현재는 완료 후 폴링)

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages