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 は2つのコンポーネントで構成されています：

ホスト - 制御したい Cursor インスタンス（通常はリモートまたはクラウドの Windows マシン上）
コントローラー - コマンドを送信するために Cursor CLI を実行するローカルマシン

ホストは ワーカープロセス を実行し、以下を行います：

CLI からの受信コマンドをリッスン
ローカル SQLite データベース（better-sqlite3）で状態を維持
ファイル操作、ターミナルコマンド、agent タスクを実行
結果をコントローラーにストリーミング

ユースケース

シナリオ	利点
クラウド開発ワークステーション	軽量ラップトップから強力なクラウドマシンで AI を使用
ヘッドレスサーバー管理	ディスプレイなしでサーバー上で Cursor agent を実行
マルチマシンワークフロー	1台のマシンから複数の Cursor インスタンスを制御
CI/CD 統合	自動化パイプラインから agent タスクをトリガー

前提条件

Windows で Remote Control をセットアップする前に：

Cursor がホストマシン（制御される側）にインストール済み
Node.js 18+ がホストとコントローラーの両方にインストール済み
Windows 10 または 11 で PowerShell 5.1+ または PowerShell 7
ホストとコントローラー間のネットワークアクセス（直接 TCP または SSH トンネル）
ホストでの初期セットアップのための管理者アクセス権

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

ファイル差分やツール実行を含む各ステップを表示します。

ヒント

長時間実行されるタスクには、--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_VERSION	Node.js バージョン
115	Node.js 18.x
120	Node.js 20.x
127	Node.js 22.x
137	Node.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 は時々接続できるがランダムに失敗する。

原因と修正：

ファイアウォールルールが厳しすぎる - 単一の IP ではなく、コントローラーの IP 範囲を許可するようにルールを確認
NAT/ルーターのタイムアウト - インターネット経由で接続する場合、NAT テーブルエントリが期限切れになる可能性があります。SSH トンネルを使用してください
電源管理 - Windows がネットワークアダプターをスリープ状態にする可能性があります。これを無効にします：

# ネットワークアダプターの電源管理を無効にする
powercfg /devicequery wake_from_any
# ネットワークアダプターを見つけて、次に：
powercfg /devicedisablewake "Your Network Adapter Name"

アンチウイルスの干渉 - 一部のアンチウイルスソフトウェアは TCP 接続を傍受します。ワーカーの実行可能ファイルとポート8473を除外リストに追加してください。

バージョン互換性マトリックス

すべてのコンポーネント間のバージョン互換性を確保することは、安定した Remote Control 操作に不可欠です。

コンポーネント	最小バージョン	備考
Cursor（ホスト）	0.45+	Remote Control サポートはここから開始
@cursor/remote-worker	1.0.0+	ワーカーパッケージ
@cursor/remote-cli	1.0.0+	CLI パッケージ
Node.js（ホスト）	18.x, 20.x, 22.x	better-sqlite3 が137ビルドを出荷するまで24.xを避ける
Node.js（コントローラー）	18.x+	より柔軟、ネイティブモジュールなし
better-sqlite3	11.0.0+	あなたの Node バージョンのプリビルドの可用性を確認
Windows	10 1903+ / 11	PowerShell 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 暗号化を経由してトンネリングされ、ポートを直接公開するよりもはるかに安全です。

マルチホスト設定

1つのコントローラーから複数のホストマシンを制御できます：

{
  "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 経由で渡された環境変数は、コントローラーとホストマシンの両方のプロセスリストで表示されます。本番のシークレットをこの方法で渡さないでください。シークレットマネージャーまたは制限された権限を持つ環境変数ファイルを使用してください。

セキュリティのベストプラクティス

認証トークンを定期的にローテーション：cursor-remote-worker regenerate-token
信頼できないネットワークを通過する接続には SSH トンネルを使用
ファイアウォールルールを特定の IP アドレスに制限、「any」ではなく
可能な場合は非管理者ユーザーとしてワーカーを実行
ワーカーログを有効にし、予期しないアクセスパターンがないか毎週ログを確認
共有またはクラウドマシンでは使用しない時にワーカーを無効化
ワーカーと 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 セットアップを維持できます。

Cursor Remote Control とは？​

ユースケース​

前提条件​

Remote Control ワーカーのセットアップ​

ステップ 1：ワーカーのインストール​

ステップ 2：ワーカーの初期化​

ステップ 3：ワーカーの起動​

ステップ 4：ファイアウォールの構成​

コントローラーでの CLI 構成​

ステップ 1：CLI のインストール​

ステップ 2：リモートホストの追加​

ステップ 3：接続のテスト​

ステップ 4：リモートセッションの開始​

リモートでの Agent タスクの実行​

ストリーミング出力​

better-sqlite3 NODE_MODULE_VERSION クラッシュ​

エラーの理解​

修正 1：better-sqlite3 のリビルド（推奨）​

修正 2：Node.js のダウングレード​

修正 3：プリビルドバイナリの使用​

修正 4：ワーカーの Node.js バージョンを固定​

ワーカーのトラブルシューティング​

ワーカーが起動しない​

ワーカーは起動するがデータベースが破損​

ワーカーが間欠的に接続を失う​

バージョン互換性マトリックス​

バージョン互換性の確認​

高度な設定​

SSH トンネルのセットアップ​

マルチホスト設定​

環境変数の注入​

セキュリティのベストプラクティス​

まとめ​