Cursor Remote Control unter Windows
Cursor Remote Control ermöglicht es Ihnen, eine Cursor-Instanz von einer Remotemaschine aus zu steuern und ermöglicht KI-gestützte Entwicklung auf Headless-Servern, Cloud-Workstations oder Zweitmaschinen. Unter Windows umfasst die Einrichtung einen Worker-Prozess, eine CLI-Konfiguration und einen SQLite-basierten Zustandsspeicher. Forumsbenutzer treffen häufig auf Abstürze im Zusammenhang mit better-sqlite3 und NODE_MODULE_VERSION-Konflikten. Dieser Leitfaden behandelt die vollständige Einrichtung und bietet getestete Lösungen für die häufigsten Windows-spezifischen Probleme.
Was ist Cursor Remote Control?
Remote Control besteht aus zwei Komponenten:
- Der Host - Die Cursor-Instanz, die Sie steuern möchten (typischerweise auf einer Remote- oder Cloud-Windows-Maschine)
- Der Controller - Ihre lokale Maschine, die das Cursor CLI ausführt, um Befehle zu senden
Der Host führt einen Worker-Prozess aus, der:
- Auf eingehende Befehle vom CLI lauscht
- Den Zustand in einer lokalen SQLite-Datenbank (
better-sqlite3) verwaltet - Dateioperationen, Terminal-Befehle und Agent-Aufgaben ausführt
- Ergebnisse an den Controller zurückstreamt
Anwendungsfälle
| Szenario | Vorteil |
|---|---|
| Cloud-Entwicklungsworkstation | KI auf einer leistungsstarken Cloud-Maschine von einem leichten Laptop aus nutzen |
| Headless-Server-Verwaltung | Cursor-Agenten auf einem Server ohne Display ausführen |
| Multi-Maschinen-Workflows | Mehrere Cursor-Instanzen von einer Maschine aus steuern |
| CI/CD-Integration | Agent-Aufgaben aus automatisierten Pipelines auslösen |
Voraussetzungen
Vor der Einrichtung von Remote Control unter Windows:
- Cursor auf der Host-Maschine installiert (derjenigen, die gesteuert wird)
- Node.js 18+ auf Host und Controller installiert
- Windows 10 oder 11 mit PowerShell 5.1+ oder PowerShell 7
- Netzwerkzugang zwischen Host und Controller (direktes TCP oder SSH-Tunnel)
- Administratorzugang für die Ersteinrichtung auf dem Host
Einrichtung des Remote Control Workers
Der Worker ist das Herz der Host-Maschine. Er läuft als Hintergrundprozess und verarbeitet alle eingehenden Befehle.
Schritt 1: Den Worker installieren
Auf der Host-Windows-Maschine:
# Den Cursor Remote Control Worker global installieren
npm install -g @cursor/remote-worker
# Installation überprüfen
cursor-remote-worker --version
Schritt 2: Den Worker initialisieren
# Den Worker mit einem Projektpfad initialisieren
cursor-remote-worker init --project "H:\Projects\my-app"
# Dies erstellt eine Konfigurationsdatei unter:
# %USERPROFILE%\.cursor-remote\config.json
Die generierte Konfiguration sieht so aus:
{
"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
}
Notieren Sie sich den authToken-Wert. Sie benötigen ihn, um das Controller-CLI zu konfigurieren. Behandeln Sie ihn wie ein Passwort. Wenn Sie ihn neu generieren müssen, führen Sie cursor-remote-worker regenerate-token aus.
Schritt 3: Den Worker starten
# Den Worker im Vordergrund starten (zum Testen)
cursor-remote-worker start
# Den Worker als Windows-Dienst installieren (für Produktion)
cursor-remote-worker install-service
cursor-remote-worker start-service
Für den Produktionseinsatz installieren Sie ihn als Windows-Dienst, damit er Neustarts übersteht:
# Überprüfen, ob der Dienst läuft
Get-Service -Name "CursorRemoteWorker"
# Erwartete Ausgabe:
# Status Name DisplayName
# ------ ---- -----------
# Running CursorRemoteWorker Cursor Remote Worker
Schritt 4: Firewall konfigurieren
Der Worker lauscht standardmäßig auf Port 8473. Öffnen Sie die Firewall:
# Den Port in der Windows-Firewall öffnen
New-NetFirewallRule -DisplayName "Cursor Remote Worker" -Direction Inbound -Protocol TCP -LocalPort 8473 -Action Allow
# Überprüfen, ob die Regel erstellt wurde
Get-NetFirewallRule -DisplayName "Cursor Remote Worker"
Setzen Sie Port 8473 nicht dem öffentlichen Internet aus. Die Authentifizierung des Workers ist tokenbasiert, aber nicht für nicht vertrauenswürdige Netzwerke konzipiert. Verwenden Sie ein VPN, einen SSH-Tunnel, oder beschränken Sie Firewall-Regeln auf spezifische IP-Adressen. Den Port öffentlich freizugeben ist ein Sicherheitsrisiko.
CLI-Konfiguration auf dem Controller
Auf Ihrer lokalen Maschine (dem Controller) installieren und konfigurieren Sie das CLI, um mit dem Host zu kommunizieren.
Schritt 1: Das CLI installieren
npm install -g @cursor/remote-cli
# Überprüfen
cursor-remote --version
Schritt 2: Einen Remote-Host hinzufügen
# Die Remote-Host-Konfiguration hinzufügen
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"
Dies speichert die Konfiguration unter %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"
}
]
}
Schritt 3: Die Verbindung testen
# Den Remote-Host pingen
cursor-remote ping --host win-cloud-dev
# Erwartete Ausgabe:
# Connected to win-cloud-dev (192.168.1.100:8473)
# Worker version: 1.2.3
# Project: H:\Projects\my-app
# Status: ready
Schritt 4: Eine Remote-Sitzung starten
# Eine interaktive Sitzung öffnen
cursor-remote session --host win-cloud-dev
# Sie befinden sich nun in einer interaktiven Eingabe, die mit der Remote-Cursor-Instanz verbunden ist
# Befehle, die Sie eingeben, werden auf der Host-Maschine ausgeführt
Agent-Aufgaben remote ausführen
Sobald verbunden, können Sie Agent-Aufgaben auf dem Remote-Host ausführen:
# Eine einzelne Agent-Aufgabe ausführen
cursor-remote agent --host win-cloud-dev --prompt "Refactor the authentication module to use JWT"
# Mit einem bestimmten Modell ausführen
cursor-remote agent --host win-cloud-dev --model claude-sonnet-4-0 --prompt "Add input validation to all API endpoints"
# Mit Dateikontext ausführen
cursor-remote agent --host win-cloud-dev --files "src/auth/auth.ts,src/api/routes.ts" --prompt "Add rate limiting to these routes"
Streaming-Ausgabe
Standardmäßig wird die Agent-Ausgabe in Echtzeit an Ihr Terminal gestreamt:
cursor-remote agent --host win-cloud-dev --prompt "Create a test file" --stream
Dies zeigt jeden Schritt, während er passiert, einschließlich Datei-Diffs und Tool-Ausführungen.
Für lang laufende Aufgaben verwenden Sie das Flag --detach, um die Aufgabe im Hintergrund auf dem Host auszuführen. Sie können sie später überprüfen:
# Eine abgetrennte Aufgabe starten
cursor-remote agent --host win-cloud-dev --prompt "Write comprehensive test suite" --detach
# Aufgabenstatus überprüfen
cursor-remote tasks --host win-cloud-dev --status running
# Aufgabenausgabe abrufen
cursor-remote tasks --host win-cloud-dev --id task_abc123 --output
Der better-sqlite3 NODE_MODULE_VERSION-Absturz
Dies ist das kritischste Problem, mit dem Windows-Benutzer konfrontiert werden. Der Worker verwendet better-sqlite3 für seine Zustandsdatenbank, und wenn die Node.js-Version auf dem Host nicht mit der Version übereinstimmt, gegen die better-sqlite3 kompiliert wurde, stürzt der Worker mit einem Fehler ab wie:
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.
Den Fehler verstehen
better-sqlite3 ist ein natives Addon. Es kompiliert C++-Code in eine .node-Binärdatei, die spezifisch für eine Node.js-ABI-Version ist. Die NODE_MODULE_VERSION ist eine Zahl, die einer bestimmten Node.js-Hauptversion entspricht:
| NODE_MODULE_VERSION | Node.js-Version |
|---|---|
| 115 | Node.js 18.x |
| 120 | Node.js 20.x |
| 127 | Node.js 22.x |
| 137 | Node.js 24.x |
Wenn der Worker mit Node.js 22 (MODULE_VERSION 127) installiert wurde, Sie aber später auf Node.js 24 (MODULE_VERSION 137) aktualisiert haben, passt die vorkompilierte Binärdatei nicht mehr.
Lösung 1: better-sqlite3 neu kompilieren (Empfohlen)
# Zum Worker-Installationsverzeichnis navigieren
cd "$env:APPDATA\npm\node_modules\@cursor\remote-worker"
# Native Module für die aktuelle Node.js-Version neu kompilieren
npm rebuild better-sqlite3
# Oder Neukompilierung aus der Quelle erzwingen
npm rebuild better-sqlite3 --build-from-source
Sie benötigen die Visual Studio Build Tools (oder das vollständige Visual Studio mit C++-Workload), um native Addons neu zu kompilieren. Wenn Sie diese nicht installiert haben:
# Build-Tools über npm installieren
npm install --global windows-build-tools
# Oder Visual Studio Build Tools manuell installieren:
# https://visualstudio.microsoft.com/visual-cpp-build-tools/
Starten Sie nach der Installation Ihr Terminal neu und versuchen Sie die Neukompilierung erneut.
Lösung 2: Node.js zurückstufen
Wenn Neukompilierung keine Option ist, passen Sie Ihre Node.js-Version an die vom Worker erwartete Version an:
# Prüfen, mit welcher Node.js-Version der Worker gebaut wurde
# (NODE_MODULE_VERSION in der Fehlermeldung prüfen)
# nvm-windows zur Versionsverwaltung installieren
# https://github.com/coreybutler/nvm-windows
nvm install 22.0.0
nvm use 22.0.0
# Überprüfen
node --version
# v22.0.0
# Worker neu starten
cursor-remote-worker stop-service
cursor-remote-worker start-service
Lösung 3: Eine vorkompilierte Binärdatei verwenden
Einige Versionen von better-sqlite3 liefern vorkompilierte Binärdateien für gängige Plattformen. Wenn Ihre Kombination verfügbar ist:
# Eine Version von better-sqlite3 mit Vorkompilaten installieren
npm install [email protected] --build-from-source=false
# Oder prebuild-install verwenden, um die richtige Binärdatei zu holen
npx prebuild-install --runtime node --target $(node -v)
Lösung 4: Node.js-Version für den Worker anheften
Um dies zu verhindern, heften Sie die vom Worker verwendete Node.js-Version fest, unabhängig von Ihrer Entwicklungs-Node.js:
# Ein Wrapper-Skript erstellen, das eine spezifische Node.js-Version verwendet
# 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
Konfigurieren Sie dann den Windows-Dienst, diese Batch-Datei anstelle des Standard-Einstiegspunkts zu verwenden.
Wenn Sie nvm-windows verwenden, um zwischen Node.js-Versionen für die Entwicklung zu wechseln, kann jeder Wechsel den Worker beschädigen, wenn er die systemweit aktive Node.js-Version ändert. Der Wrapper-Skript-Ansatz (Lösung 4) ist die zuverlässigste langfristige Lösung, da er die Node.js-Version des Workers von Ihrer Entwicklungsumgebung entkoppelt.
Worker-Fehlerbehebung
Der Worker startet nicht
Symptom: cursor-remote-worker start beendet sich sofort ohne Ausgabe.
Diagnose:
# Worker-Protokolle prüfen
Get-Content "$env:USERPROFILE\.cursor-remote\logs\worker.log" -Tail 50
# Prüfen, ob der Port bereits belegt ist
netstat -ano | findstr :8473
# Prüfen, ob ein anderer Worker-Prozess läuft
Get-Process -Name "node" | Where-Object { $_.CommandLine -like "*remote-worker*" }
Lösungen:
- Jeden Prozess beenden, der Port 8473 verwendet:
Stop-Process -Id <PID> -Force - Die Sperrdatei löschen:
Remove-Item "$env:USERPROFILE\.cursor-remote\.lock" - Mit ausführlicher Protokollierung starten:
cursor-remote-worker start --log-level debug
Der Worker startet, aber die Datenbank ist beschädigt
Symptom: Der Worker startet, aber alle Operationen schlagen mit SQLite-Fehlern fehl.
Lösung:
# Den Worker stoppen
cursor-remote-worker stop-service
# Die beschädigte Datenbank sichern
Copy-Item "$env:USERPROFILE\.cursor-remote\state.db" "$env:USERPROFILE\.cursor-remote\state.db.bak"
# Die beschädigte Datenbank löschen (der Worker erstellt sie neu)
Remove-Item "$env:USERPROFILE\.cursor-remote\state.db"
# Den Worker neu starten
cursor-remote-worker start-service
Die Zustandsdatenbank speichert nur Aufgabenverlauf, Worker-Zustand und Sitzungsmetadaten. Sie zu löschen wirkt sich nicht auf Ihre Projektdateien aus. Sie verlieren den Verlauf vergangener Remote-Aufgaben, aber der Worker wird nach der Neuerstellung der Datenbank normal funktionieren.
Der Worker verliert intermittierend die Verbindung
Symptom: Das CLI kann manchmal eine Verbindung herstellen, schlägt aber zufällig fehl.
Ursachen und Lösungen:
- Firewall-Regeln zu restriktiv - Stellen Sie sicher, dass die Regel den IP-Bereich des Controllers erlaubt, nicht nur eine einzelne IP
- NAT/Router-Timeout - Wenn Sie über das Internet verbinden, kann der NAT-Tabelleneintrag ablaufen. Verwenden Sie stattdessen einen SSH-Tunnel
- Energieverwaltung - Windows kann den Netzwerkadapter in den Ruhezustand versetzen. Deaktivieren Sie dies:
# Energieverwaltung auf dem Netzwerkadapter deaktivieren
powercfg /devicequery wake_from_any
# Finden Sie Ihren Netzwerkadapter, dann:
powercfg /devicedisablewake "Your Network Adapter Name"
- Antivirus-Interferenz - Manche Antivirensoftware fängt TCP-Verbindungen ab. Fügen Sie die ausführbare Worker-Datei und Port 8473 zu den Ausschlüssen hinzu.
Versionskompatibilitätsmatrix
Die Sicherstellung der Versionskompatibilität über alle Komponenten hinweg ist kritisch für einen stabilen Remote-Control-Betrieb.
| Komponente | Mindestversion | Hinweise |
|---|---|---|
| Cursor (Host) | 0.45+ | Remote-Control-Support begann hier |
| @cursor/remote-worker | 1.0.0+ | Worker-Paket |
| @cursor/remote-cli | 1.0.0+ | CLI-Paket |
| Node.js (Host) | 18.x, 20.x, 22.x | 24.x vermeiden, bis better-sqlite3 137-Builds liefert |
| Node.js (Controller) | 18.x+ | Flexibler, keine nativen Module |
| better-sqlite3 | 11.0.0+ | Vorkompilat-Verfügbarkeit für Ihre Node-Version prüfen |
| Windows | 10 1903+ / 11 | PowerShell 5.1 Minimum |
Die Worker- und CLI-Versionen müssen kompatibel sein. Ein Worker, der v1.0.0 ausführt, funktioniert möglicherweise nicht mit einem CLI, das v1.5.0 ausführt, wenn es protokolländernde Änderungen gibt. Überprüfen Sie immer das Änderungsprotokoll beim Upgrade einer der beiden Komponenten. Wenn Sie eine aktualisieren, aktualisieren Sie beide.
Versionskompatibilität überprüfen
# Auf dem Host Worker- und Datenbankversionen prüfen
cursor-remote-worker --version
cursor-remote-worker --check-deps
# Auf dem Controller die CLI-Version prüfen
cursor-remote --version
# Node.js-ABI-Version prüfen
node -e "console.log(process.versions.modules)"
Das Flag --check-deps führt eine Diagnose aus, die Folgendes überprüft:
- Node.js-Versionskompatibilität
- better-sqlite3-Binärkompatibilität
- Erforderliche Systemabhängigkeiten
- Port-Verfügbarkeit
- Schreibberechtigungen im Konfigurationsverzeichnis
Erweiterte Konfiguration
SSH-Tunnel-Einrichtung
Für sichere Verbindungen über das Internet verwenden Sie einen SSH-Tunnel:
# Auf dem Controller einen SSH-Tunnel zum Host erstellen
ssh -L 8473:localhost:8473 [email protected] -N
# Dann das CLI mit localhost verbinden
cursor-remote add-host `
--name "win-tunneled" `
--host "127.0.0.1" `
--port 8473 `
--token "auto-generated-token-here" `
--project "H:\Projects\my-app"
Dies tunnelt den gesamten Datenverkehr durch SSH-Verschlüsselung, was wesentlich sicherer ist als den Port direkt freizugeben.
Multi-Host-Konfiguration
Sie können mehrere Host-Maschinen von einem Controller aus steuern:
{
"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"
}
]
}
Zwischen Hosts wechseln:
# Eine Aufgabe auf einem bestimmten Host ausführen
cursor-remote agent --host win-build-server --prompt "Fix the failing CI pipeline test"
# Alle Hosts und ihren Status auflisten
cursor-remote hosts --status
Umgebungsvariablen-Injection
Übergeben Sie Umgebungsvariablen an den Worker für Agent-Aufgaben:
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"
Über das CLI übergebene Umgebungsvariablen sind in der Prozessliste auf beiden Maschinen, Controller und Host, sichtbar. Geben Sie niemals echte Produktionsgeheimnisse auf diese Weise weiter. Verwenden Sie stattdessen einen Secrets-Manager oder Umgebungsvariablendateien mit eingeschränkten Berechtigungen.
Sicherheits-Best Practices
- Auth-Token regelmäßig rotieren:
cursor-remote-worker regenerate-token - SSH-Tunnel verwenden für jede Verbindung, die nicht vertrauenswürdige Netzwerke durchquert
- Firewall-Regeln auf spezifische IP-Adressen beschränken, nicht auf "any"
- Den Worker als Nicht-Admin-Benutzer ausführen, wenn möglich
- Worker-Protokollierung aktivieren und Protokolle wöchentlich auf unerwartete Zugriffsmuster überprüfen
- Den Worker deaktivieren, wenn nicht verwendet, auf geteilten oder Cloud-Maschinen
- Worker und CLI aktuell halten, um Sicherheits-Patches zu erhalten
Zusammenfassung
Cursor Remote Control unter Windows ist eine leistungsstarke Funktion, die KI-gestützte Entwicklung auf Remote- und Headless-Maschinen erweitert. Die Einrichtung umfasst einen Worker-Prozess auf dem Host und ein CLI auf dem Controller, mit Kommunikation über TCP. Der häufigste Absturz, better-sqlite3 NODE_MODULE_VERSION 127 vs 137, wird durch Node.js-Versionskonflikte verursacht und wird gelöst, indem entweder das native Addon für Ihre aktuelle Node.js-Version neu kompiliert oder der Worker an eine spezifische Node.js-Installation angeheftet wird. Indem Sie den Versionskompatibilitäts-Hinweisen und Sicherheits-Best Practices in diesem Leitfaden folgen, können Sie eine stabile, sichere Remote-Control-Einrichtung unter Windows aufrechterhalten.