Cursor Remote Control sur Windows
Cursor Remote Control vous permet de contrôler une instance Cursor depuis une machine distante, enabling le développement assisté par IA sur des serveurs sans écran, des stations de travail cloud ou des machines secondaires. Sous Windows, la configuration implique un processus worker, une configuration CLI et un stockage d'état basé sur SQLite. Les utilisateurs du forum rencontrent fréquemment des plantages liés à better-sqlite3 et des incompatibilités de NODE_MODULE_VERSION. Ce guide couvre la configuration complète et fournit des solutions testées pour les problèmes les plus courants spécifiques à Windows.
Qu'est-ce que Cursor Remote Control ?
Remote Control se compose de deux composants :
- L'Hôte - L'instance Cursor que vous souhaitez contrôler (généralement sur une machine Windows distante ou cloud)
- Le Contrôleur - Votre machine locale exécutant le CLI de Cursor pour envoyer des commandes
L'Hôte exécute un processus worker qui :
- Écoute les commandes entrantes du CLI
- Maintient l'état dans une base de données SQLite locale (
better-sqlite3) - Exécute les opérations de fichiers, les commandes de terminal et les tâches d'agent
- Diffuse les résultats vers le Contrôleur
Cas d'utilisation
| Scénario | Bénéfice |
|---|---|
| Station de travail de développement cloud | Utiliser l'IA sur une machine cloud puissante depuis un ordinateur portable léger |
| Gestion de serveur sans écran | Exécuter des agents Cursor sur un serveur sans affichage |
| Flux de travail multi-machines | Contrôler plusieurs instances Cursor depuis une seule machine |
| Intégration CI/CD | Déclencher des tâches d'agent depuis des pipelines automatisés |
Prérequis
Avant de configurer Remote Control sous Windows :
- Cursor installé sur la machine Hôte (celle étant contrôlée)
- Node.js 18+ installé sur l'Hôte et le Contrôleur
- Windows 10 ou 11 avec PowerShell 5.1+ ou PowerShell 7
- Accès réseau entre l'Hôte et le Contrôleur (TCP direct ou tunnel SSH)
- Accès administrateur pour la configuration initiale sur l'Hôte
Configuration du Worker Remote Control
Le worker est le cœur de la machine Hôte. Il s'exécute comme un processus d'arrière-plan et gère toutes les commandes entrantes.
Étape 1 : Installer le Worker
Sur la machine Hôte Windows :
# Installer le worker Cursor Remote Control globalement
npm install -g @cursor/remote-worker
# Vérifier l'installation
cursor-remote-worker --version
Étape 2 : Initialiser le Worker
# Initialiser le worker avec un chemin de projet
cursor-remote-worker init --project "H:\Projects\my-app"
# Cela crée un fichier de configuration à :
# %USERPROFILE%\.cursor-remote\config.json
La configuration générée ressemble à :
{
"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
}
Notez la valeur authToken. Vous en aurez besoin pour configurer le CLI du Contrôleur. Traitez-le comme un mot de passe. Si vous devez le régénérer, exécutez cursor-remote-worker regenerate-token.
Étape 3 : Démarrer le Worker
# Démarrer le worker au premier plan (pour les tests)
cursor-remote-worker start
# Installer le worker comme service Windows (pour la production)
cursor-remote-worker install-service
cursor-remote-worker start-service
Pour une utilisation en production, installez-le comme un service Windows pour qu'il survive aux redémarrages :
# Vérifier que le service fonctionne
Get-Service -Name "CursorRemoteWorker"
# Sortie attendue :
# Status Name DisplayName
# ------ ---- -----------
# Running CursorRemoteWorker Cursor Remote Worker
Étape 4 : Configurer le Pare-feu
Le worker écoute sur le port 8473 par défaut. Ouvrez le pare-feu :
# Ouvrir le port dans le Pare-feu Windows
New-NetFirewallRule -DisplayName "Cursor Remote Worker" -Direction Inbound -Protocol TCP -LocalPort 8473 -Action Allow
# Vérifier que la règle a été créée
Get-NetFirewallRule -DisplayName "Cursor Remote Worker"
N'exposez pas le port 8473 à l'Internet public. L'authentification du worker est basée sur des jetons mais n'est pas conçue pour les réseaux non fiables. Utilisez un VPN, un tunnel SSH, ou restreignez les règles de pare-feu à des adresses IP spécifiques. Exposer le port publiquement est un risque de sécurité.
Configuration du CLI sur le Contrôleur
Sur votre machine locale (le Contrôleur), installez et configurez le CLI pour communiquer avec l'Hôte.
Étape 1 : Installer le CLI
npm install -g @cursor/remote-cli
# Vérifier
cursor-remote --version
Étape 2 : Ajouter un Hôte Distant
# Ajouter la configuration de l'hôte distant
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"
Cela stocke la configuration dans %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"
}
]
}
Étape 3 : Tester la Connexion
# Pinger l'hôte distant
cursor-remote ping --host win-cloud-dev
# Sortie attendue :
# Connected to win-cloud-dev (192.168.1.100:8473)
# Worker version: 1.2.3
# Project: H:\Projects\my-app
# Status: ready
Étape 4 : Démarrer une Session Distante
# Ouvrir une session interactive
cursor-remote session --host win-cloud-dev
# Vous êtes maintenant dans une invite interactif connecté à l'instance Cursor distante
# Les commandes que vous tapez sont exécutées sur la machine Hôte
Exécution de Tâches d'Agent à Distance
Une fois connecté, vous pouvez exécuter des tâches d'agent sur l'Hôte distant :
# Exécuter une seule tâche d'agent
cursor-remote agent --host win-cloud-dev --prompt "Refactor the authentication module to use JWT"
# Exécuter avec un modèle spécifique
cursor-remote agent --host win-cloud-dev --model claude-sonnet-4-0 --prompt "Add input validation to all API endpoints"
# Exécuter avec un contexte de fichier
cursor-remote agent --host win-cloud-dev --files "src/auth/auth.ts,src/api/routes.ts" --prompt "Add rate limiting to these routes"
Diffusion en Continu de la Sortie
Par défaut, la sortie de l'agent est diffusée en continu vers votre terminal en temps réel :
cursor-remote agent --host win-cloud-dev --prompt "Create a test file" --stream
Cela affiche chaque étape au fur et à mesure, y compris les diffs de fichiers et les exécutions d'outils.
Pour les tâches longues, utilisez le drapeau --detach pour exécuter la tâche en arrière-plan sur l'Hôte. Vous pouvez la vérifier plus tard :
# Démarrer une tâche détachée
cursor-remote agent --host win-cloud-dev --prompt "Write comprehensive test suite" --detach
# Vérifier le statut de la tâche
cursor-remote tasks --host win-cloud-dev --status running
# Obtenir la sortie de la tâche
cursor-remote tasks --host win-cloud-dev --id task_abc123 --output
Le Plantage better-sqlite3 NODE_MODULE_VERSION
C'est le problème le plus critique auquel les utilisateurs Windows sont confrontés. Le worker utilise better-sqlite3 pour sa base de données d'état, et lorsque la version de Node.js sur l'Hôte ne correspond pas à la version avec laquelle better-sqlite3 a été compilé, le worker plante avec une erreur comme :
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.
Comprendre l'Erreur
better-sqlite3 est un module natif. Il compile du code C++ en un binaire .node qui est spécifique à une version d'ABI Node.js. Le NODE_MODULE_VERSION est un nombre qui correspond à une version majeure spécifique de Node.js :
| NODE_MODULE_VERSION | Version de Node.js |
|---|---|
| 115 | Node.js 18.x |
| 120 | Node.js 20.x |
| 127 | Node.js 22.x |
| 137 | Node.js 24.x |
Lorsque le worker a été installé avec Node.js 22 (MODULE_VERSION 127) mais que vous avez ensuite mis à niveau vers Node.js 24 (MODULE_VERSION 137), le binaire précompilé ne correspond plus.
Solution 1 : Recompiler better-sqlite3 (Recommandé)
# Naviguer vers le répertoire d'installation du worker
cd "$env:APPDATA\npm\node_modules\@cursor\remote-worker"
# Recompiler les modules natifs pour la version actuelle de Node.js
npm rebuild better-sqlite3
# Ou forcer une recompilation depuis la source
npm rebuild better-sqlite3 --build-from-source
Vous avez besoin de Visual Studio Build Tools (ou Visual Studio complet avec la charge de travail C++) pour recompiler les modules natifs. Si vous ne les avez pas installés :
# Installer les outils de construction via npm
npm install --global windows-build-tools
# Ou installer Visual Studio Build Tools manuellement :
# https://visualstudio.microsoft.com/visual-cpp-build-tools/
Après l'installation, redémarrez votre terminal et réessayez la recompilation.
Solution 2 : Rétrograder Node.js
Si la recompilation n'est pas une option, adaptez votre version de Node.js à ce que le worker attend :
# Vérifier avec quelle version de Node.js le worker a été construit
# (Regardez le message d'erreur pour NODE_MODULE_VERSION)
# Installer nvm-windows pour la gestion des versions
# https://github.com/coreybutler/nvm-windows
nvm install 22.0.0
nvm use 22.0.0
# Vérifier
node --version
# v22.0.0
# Redémarrer le worker
cursor-remote-worker stop-service
cursor-remote-worker start-service
Solution 3 : Utiliser un Binaire Préconstruit
Certaines versions de better-sqlite3 livrent des binaires préconstruits pour les plateformes courantes. Si votre combinaison est disponible :
# Installer une version de better-sqlite3 avec des préconstructions
npm install [email protected] --build-from-source=false
# Ou utiliser prebuild-install pour récupérer le bon binaire
npx prebuild-install --runtime node --target $(node -v)
Solution 4 : Épingler la Version de Node.js pour le Worker
Pour éviter que cela ne se reproduise, épinglez la version de Node.js que le worker utilise, indépendamment de votre Node.js de développement :
# Créer un script wrapper qui utilise une version spécifique de 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
Configurez ensuite le service Windows pour utiliser ce fichier batch au lieu du point d'entrée par défaut.
Si vous utilisez nvm-windows pour basculer entre les versions de Node.js pour le développement, chaque bascule peut casser le worker si elle modifie la version de Node.js active à l'échelle du système. L'approche du script wrapper (Solution 4) est la solution à long terme la plus fiable car elle découuple la version de Node.js du worker de votre environnement de développement.
Dépannage du Worker
Le Worker Ne Démarre Pas
Symptôme : cursor-remote-worker start se ferme immédiatement sans sortie.
Diagnostic :
# Vérifier les logs du worker
Get-Content "$env:USERPROFILE\.cursor-remote\logs\worker.log" -Tail 50
# Vérifier si le port est déjà utilisé
netstat -ano | findstr :8473
# Vérifier si un autre processus worker est en cours d'exécution
Get-Process -Name "node" | Where-Object { $_.CommandLine -like "*remote-worker*" }
Solutions :
- Tuer tout processus utilisant le port 8473 :
Stop-Process -Id <PID> -Force - Supprimer le fichier de verrouillage :
Remove-Item "$env:USERPROFILE\.cursor-remote\.lock" - Démarrer avec journalisation détaillée :
cursor-remote-worker start --log-level debug
Le Worker Démarre mais la Base de Données Est Corrompue
Symptôme : Le worker démarre, mais toutes les opérations échouent avec des erreurs SQLite.
Solution :
# Arrêter le worker
cursor-remote-worker stop-service
# Sauvegarder la base de données corrompue
Copy-Item "$env:USERPROFILE\.cursor-remote\state.db" "$env:USERPROFILE\.cursor-remote\state.db.bak"
# Supprimer la base de données corrompue (le worker la recréera)
Remove-Item "$env:USERPROFILE\.cursor-remote\state.db"
# Redémarrer le worker
cursor-remote-worker start-service
La base de données d'état ne stocke que l'historique des tâches, l'état du worker et les métadonnées de session. La supprimer n'affecte pas vos fichiers de projet. Vous perdrez l'historique des tâches à distance passées, mais le worker fonctionnera normalement après avoir recréé la base de données.
Le Worker Perd la Connexion Intermittemment
Symptôme : Le CLI peut se connecter parfois mais échoue aléatoirement.
Causes et Solutions :
- Règles de pare-feu trop restrictives - Assurez-vous que la règle autorise la plage IP du Contrôleur, pas seulement une seule IP
- Expiration NAT/Routeur - Si vous vous connectez via Internet, l'entrée de table NAT peut expirer. Utilisez plutôt un tunnel SSH
- Gestion de l'alimentation - Windows peut mettre la carte réseau en veille. Désactivez ceci :
# Désactiver la gestion de l'alimentation sur la carte réseau
powercfg /devicequery wake_from_any
# Trouvez votre carte réseau, puis :
powercfg /devicedisablewake "Your Network Adapter Name"
- Interférence de l'antivirus - Certains logiciels antivirus interceptent les connexions TCP. Ajoutez l'exécutable du worker et le port 8473 aux exclusions.
Matrice de Compatibilité des Versions
Assurer la compatibilité des versions entre tous les composants est critique pour un fonctionnement stable de Remote Control.
| Composant | Version Minimale | Notes |
|---|---|---|
| Cursor (Hôte) | 0.45+ | Le support de Remote Control a commencé ici |
| @cursor/remote-worker | 1.0.0+ | Package du worker |
| @cursor/remote-cli | 1.0.0+ | Package du CLI |
| Node.js (Hôte) | 18.x, 20.x, 22.x | Éviter 24.x jusqu'à ce que better-sqlite3 livre les builds 137 |
| Node.js (Contrôleur) | 18.x+ | Plus flexible, pas de modules natifs |
| better-sqlite3 | 11.0.0+ | Vérifiez la disponibilité des préconstructions pour votre version de Node |
| Windows | 10 1903+ / 11 | PowerShell 5.1 minimum |
Les versions du worker et du CLI doivent être compatibles. Un worker exécutant v1.0.0 peut ne pas fonctionner avec un CLI exécutant v1.5.0 s'il y a des changements de protocole cassants. Vérifiez toujours le journal des modifications lors de la mise à niveau de l'un ou l'autre composant. Si vous mettez à niveau l'un, mettez à niveau les deux.
Vérification de la Compatibilité des Versions
# Sur l'Hôte, vérifier les versions du worker et de la base de données
cursor-remote-worker --version
cursor-remote-worker --check-deps
# Sur le Contrôleur, vérifier la version du CLI
cursor-remote --version
# Vérifier la version d'ABI de Node.js
node -e "console.log(process.versions.modules)"
Le drapeau --check-deps exécute un diagnostic qui vérifie :
- La compatibilité de la version de Node.js
- La compatibilité binaire de better-sqlite3
- Les dépendances système requises
- La disponibilité du port
- Les permissions d'écriture sur le répertoire de configuration
Configuration Avancée
Configuration d'un Tunnel SSH
Pour des connexions sécurisées via Internet, utilisez un tunnel SSH :
# Sur le Contrôleur, créer un tunnel SSH vers l'Hôte
ssh -L 8473:localhost:8473 [email protected] -N
# Puis connecter le 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"
Cela tunnel tout le trafic à travers le chiffrement SSH, ce qui est bien plus sûr que d'exposer le port directement.
Configuration Multi-Hôtes
Vous pouvez contrôler plusieurs machines Hôte depuis un seul Contrôleur :
{
"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"
}
]
}
Basculer entre les hôtes :
# Exécuter une tâche sur un hôte spécifique
cursor-remote agent --host win-build-server --prompt "Fix the failing CI pipeline test"
# Lister tous les hôtes et leur statut
cursor-remote hosts --status
Injection de Variables d'Environnement
Passez des variables d'environnement au worker pour les tâches d'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"
Les variables d'environnement passées via le CLI sont visibles dans la liste des processus sur les machines Contrôleur et Hôte. Ne passez jamais de vrais secrets de production de cette façon. Utilisez un gestionnaire de secrets ou des fichiers de variables d'environnement avec des permissions restreintes à la place.
Meilleures Pratiques de Sécurité
- Renouvelez régulièrement le jeton d'authentification :
cursor-remote-worker regenerate-token - Utilisez des tunnels SSH pour toute connexion traversant des réseaux non fiables
- Restreignez les règles de pare-feu à des adresses IP spécifiques, pas « any »
- Exécutez le worker en tant qu'utilisateur non-admin lorsque c'est possible
- Activez la journalisation du worker et examinez les logs chaque semaine pour des modèles d'accès inattendus
- Désactivez le worker lorsqu'il n'est pas utilisé sur des machines partagées ou cloud
- Maintenez le worker et le CLI à jour pour obtenir les correctifs de sécurité
Résumé
Cursor Remote Control sous Windows est une fonctionnalité puissante qui étend le développement assisté par IA aux machines distantes et sans écran. La configuration implique un processus worker sur l'Hôte et un CLI sur le Contrôleur, avec communication via TCP. Le plantage le plus courant, better-sqlite3 NODE_MODULE_VERSION 127 vs 137, est causé par des incompatibilités de version de Node.js et est résolu en recompilant le module natif pour votre version actuelle de Node.js ou en épinglant le worker à une installation Node.js spécifique. En suivant les conseils de compatibilité des versions et les meilleures pratiques de sécurité de ce guide, vous pouvez maintenir une configuration Remote Control stable et sécurisée sous Windows.