본문으로 건너뛰기

Windows에서의 Cursor Remote Control

Remote Control

Cursor Remote Control을 사용하면 원격 머신에서 Cursor 인스턴스를 제어할 수 있어, 헤드리스 서버, 클라우드 워크스테이션 또는 보조 머신에서 AI 지원 개발이 가능합니다. Windows에서 설정은 워커 프로세스, CLI 구성 및 SQLite 기반 상태 저장소를 포함합니다. 포럼 사용자는 better-sqlite3 및 NODE_MODULE_VERSION 불일치와 관련된 충돌을 자주 겪습니다. 이 가이드는 전체 설정을 다루고 가장 일반적인 Windows 특정 문제에 대해 테스트된 해결책을 제공합니다.

Cursor Remote Control이란?​

Remote Control은 두 가지 컴포넌트로 구성됩니다:

  1. 호스트 - 제어하려는 Cursor 인스턴스 (일반적으로 원격 또는 클라우드 Windows 머신)
  2. 컨트롤러 - 명령을 보내기 위해 Cursor CLI를 실행하는 로컬 머신

호스트는 다음을 수행하는 워커 프로세스를 실행합니다:

  • CLI로부터의 들어오는 명령을 수신
  • 로컬 SQLite 데이터베이스(better-sqlite3)에서 상태 유지
  • 파일 작업, 터미널 명령 및 agent 작업 실행
  • 결과를 컨트롤러로 스트리밍

사용 사례​

시나리오이점
클라우드 개발 워크스테이션가벼운 랩톱에서 강력한 클라우드 머신의 AI 사용
헤드리스 서버 관리디스플레이 없이 서버에서 Cursor agent 실행
멀티 머신 워크플로한 머신에서 여러 Cursor 인스턴스 제어
CI/CD 통합자동화된 파이프라인에서 agent 작업 트리거

전제 조건​

Windows에서 Remote Control을 설정하기 전에:

  1. Cursor가 호스트 머신(제어되는 측)에 설치됨
  2. **Node.js 18+**이 호스트와 컨트롤러 모두에 설치됨
  3. Windows 10 또는 11, PowerShell 5.1+ 또는 PowerShell 7 포함
  4. 호스트와 컨트롤러 간의 네트워크 액세스 (직접 TCP 또는 SSH 터널)
  5. 호스트에서 초기 설정을 위한 관리자 액세스 권한

Remote Control 워커 설정​

워커는 호스트 머신의 핵심입니다. 백그라운드 프로세스로 실행되며 모든 들어오는 명령을 처리합니다.

단계 1: 워커 설치​

호스트 Windows 머신에서:

# Cursor Remote Control 워커를 전역으로 설치
npm install -g @cursor/remote-worker

# 설치 확인
cursor-remote-worker --version

단계 2: 워커 초기화​

# 프로젝트 경로로 워커 초기화
cursor-remote-worker init --project "H:\Projects\my-app"

# 이것은 다음 위치에 구성 파일을 생성합니다:
# %USERPROFILE%\.cursor-remote\config.json

생성된 구성은 다음과 같습니다:

{
  "workerId": "win-worker-001",
  "projectPath": "H:\\Projects\\my-app",
  "port": 8473,
  "authToken": "auto-generated-token-here",
  "database": {
    "type": "sqlite",
    "path": "%USERPROFILE%\\.cursor-remote\\state.db"
  },
  "logLevel": "info",
  "maxConcurrentTasks": 3
}
팁

authToken 값을 기록해 두세요. 컨트롤러 CLI를 구성하는 데 필요합니다. 비밀번호처럼 취급하세요. 재생성해야 하는 경우 cursor-remote-worker regenerate-token을 실행하세요.

단계 3: 워커 시작​

# 포어그라운드에서 워커 시작 (테스트용)
cursor-remote-worker start

# Windows 서비스로 워커 설치 (프로덕션용)
cursor-remote-worker install-service
cursor-remote-worker start-service

프로덕션 사용의 경우, 재부팅 후에도 유지되도록 Windows 서비스로 설치합니다:

# 서비스가 실행 중인지 확인
Get-Service -Name "CursorRemoteWorker"

# 예상 출력:
# Status   Name               DisplayName
# ------   ----               -----------
# Running  CursorRemoteWorker Cursor Remote Worker

단계 4: 방화벽 구성​

워커는 기본적으로 포트 8473에서 수신합니다. 방화벽을 엽니다:

# Windows 방화벽에서 포트 열기
New-NetFirewallRule -DisplayName "Cursor Remote Worker" -Direction Inbound -Protocol TCP -LocalPort 8473 -Action Allow

# 규칙이 생성되었는지 확인
Get-NetFirewallRule -DisplayName "Cursor Remote Worker"
경고

포트 8473을 공용 인터넷에 노출하지 마세요. 워커의 인증은 토큰 기반이지만 신뢰할 수 없는 네트워크를 위해 설계되지 않았습니다. VPN, SSH 터널을 사용하거나 방화벽 규칙을 특정 IP 주소로 제한하세요. 포트를 공개적으로 노출하는 것은 보안 위험입니다.

컨트롤러에서의 CLI 구성​

로컬 머신(컨트롤러)에서 CLI를 설치하고 구성하여 호스트와 통신합니다.

단계 1: CLI 설치​

npm install -g @cursor/remote-cli

# 확인
cursor-remote --version

단계 2: 원격 호스트 추가​

# 원격 호스트 구성 추가
cursor-remote add-host `
  --name "win-cloud-dev" `
  --host "192.168.1.100" `
  --port 8473 `
  --token "auto-generated-token-here" `
  --project "H:\Projects\my-app"

이것은 %USERPROFILE%\.cursor-remote\hosts.json에 구성을 저장합니다:

{
  "hosts": [
    {
      "name": "win-cloud-dev",
      "host": "192.168.1.100",
      "port": 8473,
      "token": "auto-generated-token-here",
      "project": "H:\\Projects\\my-app"
    }
  ]
}

단계 3: 연결 테스트​

# 원격 호스트에 ping
cursor-remote ping --host win-cloud-dev

# 예상 출력:
# Connected to win-cloud-dev (192.168.1.100:8473)
# Worker version: 1.2.3
# Project: H:\Projects\my-app
# Status: ready

단계 4: 원격 세션 시작​

# 대화형 세션 열기
cursor-remote session --host win-cloud-dev

# 이제 원격 Cursor 인스턴스에 연결된 대화형 프롬프트에 있습니다
# 입력한 명령은 호스트 머신에서 실행됩니다

원격으로 Agent 작업 실행​

연결되면 원격 호스트에서 agent 작업을 실행할 수 있습니다:

# 단일 agent 작업 실행
cursor-remote agent --host win-cloud-dev --prompt "Refactor the authentication module to use JWT"

# 특정 모델로 실행
cursor-remote agent --host win-cloud-dev --model claude-sonnet-4-0 --prompt "Add input validation to all API endpoints"

# 파일 컨텍스트로 실행
cursor-remote agent --host win-cloud-dev --files "src/auth/auth.ts,src/api/routes.ts" --prompt "Add rate limiting to these routes"

스트리밍 출력​

기본적으로 agent 출력은 실시간으로 터미널에 스트리밍됩니다:

cursor-remote agent --host win-cloud-dev --prompt "Create a test file" --stream

파일 diff 및 도구 실행을 포함한 각 단계가 일어나는 대로 표시됩니다.

팁

장기 실행 작업의 경우 --detach 플래그를 사용하여 호스트에서 백그라운드로 작업을 실행합니다. 나중에 확인할 수 있습니다:

# 분리된 작업 시작
cursor-remote agent --host win-cloud-dev --prompt "Write comprehensive test suite" --detach

# 작업 상태 확인
cursor-remote tasks --host win-cloud-dev --status running

# 작업 출력 가져오기
cursor-remote tasks --host win-cloud-dev --id task_abc123 --output

better-sqlite3 NODE_MODULE_VERSION 충돌​

이것이 Windows 사용자가 직면하는 가장 심각한 문제입니다. 워커는 상태 데이터베이스로 better-sqlite3을 사용하며, 호스트의 Node.js 버전이 better-sqlite3이 컴파일된 버전과 일치하지 않을 때 워커는 다음과 같은 오류로 충돌합니다:

Error: The module 'H:\Projects\my-app\node_modules\better-sqlite3\build\Release\better_sqlite3.node'
was compiled against a different Node.js version using
NODE_MODULE_VERSION 127. This version of Node.js requires
NODE_MODULE_VERSION 137.

오류 이해​

better-sqlite3은 네이티브 애드온입니다. C++ 코드를 Node.js ABI 버전에 특정한 .node 바이너리로 컴파일합니다. NODE_MODULE_VERSION은 특정 Node.js 메이저 버전에 해당하는 숫자입니다:

NODE_MODULE_VERSIONNode.js 버전
115Node.js 18.x
120Node.js 20.x
127Node.js 22.x
137Node.js 24.x

워커가 Node.js 22(MODULE_VERSION 127)으로 설치되었지만 나중에 Node.js 24(MODULE_VERSION 137)로 업그레이드한 경우, 사전 컴파일된 바이너리가 더 이상 일치하지 않습니다.

해결 1: better-sqlite3 재빌드 (권장)​

# 워커 설치 디렉터리로 이동
cd "$env:APPDATA\npm\node_modules\@cursor\remote-worker"

# 현재 Node.js 버전용 네이티브 모듈 재빌드
npm rebuild better-sqlite3

# 또는 소스에서 강제 재빌드
npm rebuild better-sqlite3 --build-from-source
팁

네이티브 애드온을 재빌드하려면 Visual Studio Build Tools(또는 C++ 워크로드가 포함된 전체 Visual Studio)가 필요합니다. 설치되어 있지 않은 경우:

# npm을 통해 빌드 도구 설치
npm install --global windows-build-tools

# 또는 Visual Studio Build Tools를 수동으로 설치:
# https://visualstudio.microsoft.com/visual-cpp-build-tools/

설치 후 터미널을 재시작하고 재빌드를 재시도하세요.

해결 2: Node.js 다운그레이드​

재빌드가 선택 사항이 아닌 경우, Node.js 버전을 워커가 기대하는 버전에 맞춥니다:

# 워커가 빌드된 Node.js 버전 확인
# (NODE_MODULE_VERSION에 대한 오류 메시지 확인)

# 버전 관리를 위해 nvm-windows 설치
# https://github.com/coreybutler/nvm-windows
nvm install 22.0.0
nvm use 22.0.0

# 확인
node --version
# v22.0.0

# 워커 재시작
cursor-remote-worker stop-service
cursor-remote-worker start-service

해결 3: 사전 빌드 바이너리 사용​

일부 버전의 better-sqlite3은 일반 플랫폼용 사전 빌드 바이너리를 제공합니다. 조합이 사용 가능한 경우:

# 사전 빌드가 포함된 better-sqlite3 버전 설치
npm install [email protected] --build-from-source=false

# 또는 prebuild-install을 사용하여 올바른 바이너리 가져오기
npx prebuild-install --runtime node --target $(node -v)

해결 4: 워커용 Node.js 버전 고정​

이 문제가 재발하는 것을 방지하려면, 개발용 Node.js와 독립적으로 워커가 사용하는 Node.js 버전을 고정합니다:

# 특정 Node.js 버전을 사용하는 래퍼 스크립트 생성
# C:\cursor-worker\start-worker.bat
@echo off
set PATH=C:\Program Files\nodejs-v22\;%PATH%
node "C:\Program Files\nodejs-v22\node_modules\@cursor\remote-worker\bin\worker.js" start

그런 다음 Windows 서비스가 기본 진입점 대신 이 배치 파일을 사용하도록 구성합니다.

경고

개발을 위해 nvm-windows를 사용하여 Node.js 버전을 전환하는 경우, 시스템 전체의 활성 Node.js 버전을 변경하면 워커가 손상될 수 있습니다. 래퍼 스크립트 접근 방식(해결 4)은 워커의 Node.js 버전을 개발 환경에서 분리하기 때문에 가장 신뢰할 수 있는 장기적 해결책입니다.

워커 문제 해결​

워커가 시작되지 않음​

증상: cursor-remote-worker start가 출력 없이 즉시 종료됩니다.

진단:

# 워커 로그 확인
Get-Content "$env:USERPROFILE\.cursor-remote\logs\worker.log" -Tail 50

# 포트가 이미 사용 중인지 확인
netstat -ano | findstr :8473

# 다른 워커 프로세스가 실행 중인지 확인
Get-Process -Name "node" | Where-Object { $_.CommandLine -like "*remote-worker*" }

해결:

  • 포트 8473을 사용하는 프로세스 종료: Stop-Process -Id <PID> -Force

잠금 파일 삭제: Remove-Item "$env:USERPROFILE\.cursor-remote\.lock"

상세 로깅으로 시작: cursor-remote-worker start --log-level debug

워커는 시작하지만 데이터베이스가 손상됨​

증상: 워커는 시작하지만 모든 작업이 SQLite 오류로 실패합니다.

해결:

# 워커 중지
cursor-remote-worker stop-service

# 손상된 데이터베이스 백업
Copy-Item "$env:USERPROFILE\.cursor-remote\state.db" "$env:USERPROFILE\.cursor-remote\state.db.bak"

# 손상된 데이터베이스 삭제 (워커가 재생성합니다)
Remove-Item "$env:USERPROFILE\.cursor-remote\state.db"

# 워커 재시작
cursor-remote-worker start-service
팁

상태 데이터베이스는 작업 기록, 워커 상태 및 세션 메타데이터만 저장합니다. 삭제해도 프로젝트 파일에는 영향을 미치지 않습니다. 과거 원격 작업의 기록은 잃게 되지만, 워커는 데이터베이스 재생성 후 정상적으로 작동합니다.

워커가 간헐적으로 연결을 잃음​

증상: CLI가 때로는 연결할 수 있지만 무작위로 실패합니다.

원인 및 해결:

  1. 방화벽 규칙이 너무 제한적임 - 단일 IP가 아닌 컨트롤러의 IP 범위를 허용하도록 규칙 확인
  2. NAT/라우터 시간 초과 - 인터넷을 통해 연결하는 경우, NAT 테이블 항목이 만료될 수 있습니다. SSH 터널을 대신 사용하세요
  3. 전원 관리 - Windows가 네트워크 어댑터를 절전 모드로 전환할 수 있습니다. 이를 비활성화합니다:
# 네트워크 어댑터에서 전원 관리 비활성화
powercfg /devicequery wake_from_any
# 네트워크 어댑터를 찾은 다음:
powercfg /devicedisablewake "Your Network Adapter Name"
  1. 안티바이러스 간섭 - 일부 안티바이러스 소프트웨어는 TCP 연결을 가로챕니다. 워커 실행 파일과 포트 8473을 제외 항목에 추가하세요.

버전 호환성 매트릭스​

모든 컴포넌트 간의 버전 호환성을 보장하는 것은 안정적인 Remote Control 작동에 중요합니다.

컴포넌트최소 버전비고
Cursor (호스트)0.45+Remote Control 지원이 여기서 시작됨
@cursor/remote-worker1.0.0+워커 패키지
@cursor/remote-cli1.0.0+CLI 패키지
Node.js (호스트)18.x, 20.x, 22.xbetter-sqlite3이 137 빌드를 출시할 때까지 24.x 피하기
Node.js (컨트롤러)18.x+더 유연함, 네이티브 모듈 없음
better-sqlite311.0.0+Node 버전에 대한 사전 빌드 가용성 확인
Windows10 1903+ / 11PowerShell 5.1 최소
경고

워커와 CLI 버전은 호환되어야 합니다. v1.0.0을 실행하는 워커는 프로토콜 변경 사항이 있는 경우 v1.5.0을 실행하는 CLI에서 작동하지 않을 수 있습니다. 어느 한 컴포넌트를 업그레이드할 때 항상 변경 로그를 확인하세요. 하나를 업그레이드하면 둘 다 업그레이드하세요.

버전 호환성 확인​

# 호스트에서 워커 및 데이터베이스 버전 확인
cursor-remote-worker --version
cursor-remote-worker --check-deps

# 컨트롤러에서 CLI 버전 확인
cursor-remote --version

# Node.js ABI 버전 확인
node -e "console.log(process.versions.modules)"

--check-deps 플래그는 다음을 확인하는 진단을 실행합니다:

  • Node.js 버전 호환성
  • better-sqlite3 바이너리 호환성
  • 필수 시스템 종속성
  • 포트 가용성
  • 구성 디렉터리에 대한 쓰기 권한

고급 구성​

SSH 터널 설정​

인터넷을 통한 보안 연결을 위해 SSH 터널을 사용합니다:

# 컨트롤러에서 호스트로의 SSH 터널 생성
ssh -L 8473:localhost:8473 [email protected] -N

# 그런 다음 CLI를 localhost에 연결
cursor-remote add-host `
  --name "win-tunneled" `
  --host "127.0.0.1" `
  --port 8473 `
  --token "auto-generated-token-here" `
  --project "H:\Projects\my-app"

이것은 모든 트래픽을 SSH 암호화를 통해 터널링하며, 포트를 직접 노출하는 것보다 훨씬 안전합니다.

멀티 호스트 구성​

하나의 컨트롤러에서 여러 호스트 머신을 제어할 수 있습니다:

{
  "hosts": [
    {
      "name": "win-cloud-dev",
      "host": "192.168.1.100",
      "port": 8473,
      "token": "token-1",
      "project": "H:\\Projects\\my-app"
    },
    {
      "name": "win-build-server",
      "host": "192.168.1.101",
      "port": 8473,
      "token": "token-2",
      "project": "C:\\Builds\\ci-pipeline"
    }
  ]
}

호스트 간 전환:

# 특정 호스트에서 작업 실행
cursor-remote agent --host win-build-server --prompt "Fix the failing CI pipeline test"

# 모든 호스트 및 상태 나열
cursor-remote hosts --status

환경 변수 주입​

agent 작업을 위해 워커에 환경 변수를 전달합니다:

cursor-remote agent `
  --host win-cloud-dev `
  --env "DATABASE_URL=Server=prod;Database=myapp;User=admin;Password=secret" `
  --env "NODE_ENV=production" `
  --prompt "Run the database migration and report results"
경고

CLI를 통해 전달된 환경 변수는 컨트롤러와 호스트 머신 모두의 프로세스 목록에서 볼 수 있습니다. 이 방법으로 실제 프로덕션 시크릿을 전달하지 마세요. 대신 시크릿 관리자 또는 제한된 권한을 가진 환경 변수 파일을 사용하세요.

보안 모범 사례​

  1. 인증 토큰을 정기적으로 교체: cursor-remote-worker regenerate-token
  2. 신뢰할 수 없는 네트워크를 통과하는 모든 연결에 SSH 터널 사용
  3. 방화벽 규칙을 특정 IP 주소로 제한, "any"가 아닌
  4. 가능한 경우 비관리자 사용자로 워커 실행
  5. 워커 로깅 활성화 및 예상치 못한 액세스 패턴에 대해 매주 로그 검토
  6. 공유 또는 클라우드 머신에서 사용하지 않을 때 워커 비활성화
  7. 워커와 CLI를 최신으로 유지하여 보안 패치 획득

요약​

Windows에서의 Cursor Remote Control은 AI 지원 개발을 원격 및 헤드리스 머신으로 확장하는 강력한 기능입니다. 설정에는 호스트의 워커 프로세스와 컨트롤러의 CLI가 포함되며, TCP를 통해 통신합니다. 가장 일반적인 충돌인 better-sqlite3 NODE_MODULE_VERSION 127 vs 137은 Node.js 버전 불일치로 인해 발생하며, 현재 Node.js 버전용 네이티브 애드온을 재빌드하거나 워커를 특정 Node.js 설치에 고정하여 해결할 수 있습니다. 이 가이드의 버전 호환성 지침과 보안 모범 사례를 따르면, Windows에서 안정적이고 안전한 Remote Control 설정을 유지할 수 있습니다.