Cursor Remote Control no Windows
O Cursor Remote Control permite controlar uma instância do Cursor a partir de uma máquina remota, habilitando desenvolvimento assistido por IA em servidores sem interface, estações de trabalho na nuvem ou máquinas secundárias. No Windows, a configuração envolve um processo worker, configuração de CLI e um armazenamento de estado baseado em SQLite. Usuários do fórum frequentemente encontram falhas relacionadas a better-sqlite3 e incompatibilidades de NODE_MODULE_VERSION. Este guia aborda a configuração completa e fornece soluções testadas para os problemas mais comuns específicos do Windows.
O que é o Cursor Remote Control?
O Remote Control consiste em dois componentes:
- O Host - A instância do Cursor que você deseja controlar (tipicamente em uma máquina Windows remota ou na nuvem)
- O Controlador - Sua máquina local executando o CLI do Cursor para enviar comandos
O Host executa um processo worker que:
- Escuta comandos recebidos do CLI
- Mantém o estado em um banco de dados SQLite local (
better-sqlite3) - Executa operações de arquivos, comandos de terminal e tarefas de agent
- Transmite os resultados de volta ao Controlador
Casos de Uso
| Cenário | Benefício |
|---|---|
| Estação de trabalho de desenvolvimento na nuvem | Usar IA em uma máquina em nuvem poderosa a partir de um laptop leve |
| Gerenciamento de servidor sem interface | Executar agentes do Cursor em um servidor sem exibição |
| Fluxos de trabalho multi-máquina | Controlar múltiplas instâncias do Cursor a partir de uma máquina |
| Integração CI/CD | Disparar tarefas de agent a partir de pipelines automatizados |
Pré-requisitos
Antes de configurar o Remote Control no Windows:
- Cursor instalado na máquina Host (a que está sendo controlada)
- Node.js 18+ instalado em ambos, Host e Controlador
- Windows 10 ou 11 com PowerShell 5.1+ ou PowerShell 7
- Acesso de rede entre Host e Controlador (TCP direto ou túnel SSH)
- Acesso de administrador para a configuração inicial no Host
Configurando o Worker do Remote Control
O worker é o coração da máquina Host. Ele é executado como um processo em segundo plano e lida com todos os comandos recebidos.
Passo 1: Instalar o Worker
Na máquina Host Windows:
# Instalar o worker do Cursor Remote Control globalmente
npm install -g @cursor/remote-worker
# Verificar a instalação
cursor-remote-worker --version
Passo 2: Inicializar o Worker
# Inicializar o worker com um caminho de projeto
cursor-remote-worker init --project "H:\Projects\my-app"
# Isso cria um arquivo de configuração em:
# %USERPROFILE%\.cursor-remote\config.json
A configuração gerada se parece com:
{
"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
}
Anote o valor do authToken. Você precisará dele para configurar o CLI do Controlador. Trate-o como uma senha. Se precisar regenerá-lo, execute cursor-remote-worker regenerate-token.
Passo 3: Iniciar o Worker
# Iniciar o worker em primeiro plano (para testes)
cursor-remote-worker start
# Instalar o worker como um serviço do Windows (para produção)
cursor-remote-worker install-service
cursor-remote-worker start-service
Para uso em produção, instale-o como um serviço do Windows para que ele sobreviva a reinicializações:
# Verificar se o serviço está em execução
Get-Service -Name "CursorRemoteWorker"
# Saída esperada:
# Status Name DisplayName
# ------ ---- -----------
# Running CursorRemoteWorker Cursor Remote Worker
Passo 4: Configurar o Firewall
O worker escuta na porta 8473 por padrão. Abra o firewall:
# Abrir a porta no Firewall do Windows
New-NetFirewallRule -DisplayName "Cursor Remote Worker" -Direction Inbound -Protocol TCP -LocalPort 8473 -Action Allow
# Verificar se a regra foi criada
Get-NetFirewallRule -DisplayName "Cursor Remote Worker"
Não exponha a porta 8473 à internet pública. A autenticação do worker é baseada em token, mas não foi projetada para redes não confiáveis. Use uma VPN, túnel SSH, ou restrinja as regras de firewall a endereços IP específicos. Expor a porta publicamente é um risco de segurança.
Configuração do CLI no Controlador
Na sua máquina local (o Controlador), instale e configure o CLI para se comunicar com o Host.
Passo 1: Instalar o CLI
npm install -g @cursor/remote-cli
# Verificar
cursor-remote --version
Passo 2: Adicionar um Host Remoto
# Adicionar a configuração do host remoto
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"
Isso armazena a configuração em %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"
}
]
}
Passo 3: Testar a Conexão
# Pingar o host remoto
cursor-remote ping --host win-cloud-dev
# Saída esperada:
# Connected to win-cloud-dev (192.168.1.100:8473)
# Worker version: 1.2.3
# Project: H:\Projects\my-app
# Status: ready
Passo 4: Iniciar uma Sessão Remota
# Abrir uma sessão interativa
cursor-remote session --host win-cloud-dev
# Você agora está em um prompt interativo conectado à instância remota do Cursor
# Comandos que você digita são executados na máquina Host
Executando Tarefas de Agent Remotamente
Uma vez conectado, você pode executar tarefas de agent no Host remoto:
# Executar uma única tarefa de agent
cursor-remote agent --host win-cloud-dev --prompt "Refactor the authentication module to use JWT"
# Executar com um modelo específico
cursor-remote agent --host win-cloud-dev --model claude-sonnet-4-0 --prompt "Add input validation to all API endpoints"
# Executar com contexto de arquivo
cursor-remote agent --host win-cloud-dev --files "src/auth/auth.ts,src/api/routes.ts" --prompt "Add rate limiting to these routes"
Saída em Streaming
Por padrão, a saída do agent é transmitida em tempo real para o seu terminal:
cursor-remote agent --host win-cloud-dev --prompt "Create a test file" --stream
Isso mostra cada etapa conforme acontece, incluindo diffs de arquivo e execuções de ferramentas.
Para tarefas de longa duração, use o sinalizador --detach para executar a tarefa em segundo plano no Host. Você pode verificá-la mais tarde:
# Iniciar uma tarefa separada
cursor-remote agent --host win-cloud-dev --prompt "Write comprehensive test suite" --detach
# Verificar status da tarefa
cursor-remote tasks --host win-cloud-dev --status running
# Obter saída da tarefa
cursor-remote tasks --host win-cloud-dev --id task_abc123 --output
A Falha do better-sqlite3 NODE_MODULE_VERSION
Este é o problema mais crítico que os usuários do Windows enfrentam. O worker usa better-sqlite3 para seu banco de dados de estado, e quando a versão do Node.js no Host não corresponde à versão com a qual better-sqlite3 foi compilado, o worker falha com um erro como:
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.
Entendendo o Erro
better-sqlite3 é um complemento nativo. Ele compila código C++ em um binário .node que é específico a uma versão de ABI do Node.js. O NODE_MODULE_VERSION é um número que corresponde a uma versão principal específica do Node.js:
| NODE_MODULE_VERSION | Versão do Node.js |
|---|---|
| 115 | Node.js 18.x |
| 120 | Node.js 20.x |
| 127 | Node.js 22.x |
| 137 | Node.js 24.x |
Quando o worker foi instalado com o Node.js 22 (MODULE_VERSION 127), mas você posteriormente atualizou para o Node.js 24 (MODULE_VERSION 137), o binário pré-compilado não corresponde mais.
Solução 1: Recompilar o better-sqlite3 (Recomendado)
# Navegar até o diretório de instalação do worker
cd "$env:APPDATA\npm\node_modules\@cursor\remote-worker"
# Recompilar módulos nativos para a versão atual do Node.js
npm rebuild better-sqlite3
# Ou forçar recompilação a partir da fonte
npm rebuild better-sqlite3 --build-from-source
Você precisa do Visual Studio Build Tools (ou Visual Studio completo com carga de trabalho C++) para recompilar complementos nativos. Se não os tem instalados:
# Instalar ferramentas de build via npm
npm install --global windows-build-tools
# Ou instalar o Visual Studio Build Tools manualmente:
# https://visualstudio.microsoft.com/visual-cpp-build-tools/
Após a instalação, reinicie seu terminal e tente a recompilação novamente.
Solução 2: Fazer Downgrade do Node.js
Se a recompilação não for uma opção, ajuste sua versão do Node.js àquela que o worker espera:
# Verificar com qual versão do Node.js o worker foi construído
# (Verifique a mensagem de erro para NODE_MODULE_VERSION)
# Instalar nvm-windows para gerenciamento de versões
# https://github.com/coreybutler/nvm-windows
nvm install 22.0.0
nvm use 22.0.0
# Verificar
node --version
# v22.0.0
# Reiniciar o worker
cursor-remote-worker stop-service
cursor-remote-worker start-service
Solução 3: Usar um Binário Pré-construído
Algumas versões do better-sqlite3 fornecem binários pré-construídos para plataformas comuns. Se sua combinação estiver disponível:
# Instalar uma versão do better-sqlite3 com pré-construções
npm install [email protected] --build-from-source=false
# Ou usar prebuild-install para buscar o binário correto
npx prebuild-install --runtime node --target $(node -v)
Solução 4: Fixar a Versão do Node.js para o Worker
Para evitar que isso se repita, fixe a versão do Node.js que o worker usa, independentemente do seu Node.js de desenvolvimento:
# Criar um script wrapper que usa uma versão específica do 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
Em seguida, configure o serviço do Windows para usar este arquivo batch em vez do ponto de entrada padrão.
Se você usa nvm-windows para alternar entre versões do Node.js para desenvolvimento, cada alternância pode quebrar o worker se alterar a versão ativa do Node.js em todo o sistema. A abordagem do script wrapper (Solução 4) é a solução de longo prazo mais confiável porque desacopla a versão do Node.js do worker do seu ambiente de desenvolvimento.
Solução de Problemas do Worker
O Worker Não Inicia
Sintoma: cursor-remote-worker start sai imediatamente sem saída.
Diagnóstico:
# Verificar os logs do worker
Get-Content "$env:USERPROFILE\.cursor-remote\logs\worker.log" -Tail 50
# Verificar se a porta já está em uso
netstat -ano | findstr :8473
# Verificar se outro processo worker está em execução
Get-Process -Name "node" | Where-Object { $_.CommandLine -like "*remote-worker*" }
Soluções:
- Encerrar qualquer processo usando a porta 8473:
Stop-Process -Id <PID> -Force - Excluir o arquivo de bloqueio:
Remove-Item "$env:USERPROFILE\.cursor-remote\.lock" - Iniciar com registro detalhado:
cursor-remote-worker start --log-level debug
O Worker Inicia mas o Banco de Dados Está Corrompido
Sintoma: O worker inicia, mas todas as operações falham com erros do SQLite.
Solução:
# Parar o worker
cursor-remote-worker stop-service
# Fazer backup do banco de dados corrompido
Copy-Item "$env:USERPROFILE\.cursor-remote\state.db" "$env:USERPROFILE\.cursor-remote\state.db.bak"
# Excluir o banco de dados corrompido (o worker o recriará)
Remove-Item "$env:USERPROFILE\.cursor-remote\state.db"
# Reiniciar o worker
cursor-remote-worker start-service
O banco de dados de estado armazena apenas histórico de tarefas, estado do worker e metadados de sessão. Excluí-lo não afeta seus arquivos de projeto. Você perderá o histórico de tarefas remotas passadas, mas o worker funcionará normalmente após recriar o banco de dados.
O Worker Perde Conexão Intermitentemente
Sintoma: O CLI pode se conectar às vezes, mas falha aleatoriamente.
Causas e Soluções:
- Regras de firewall muito restritivas - Certifique-se de que a regra permite a faixa de IP do Controlador, não apenas um único IP
- Timeout de NAT/Roteador - Se conectando pela internet, a entrada da tabela NAT pode expirar. Use um túnel SSH em vez disso
- Gerenciamento de energia - O Windows pode colocar o adaptador de rede em modo de suspensão. Desative isso:
# Desativar gerenciamento de energia no adaptador de rede
powercfg /devicequery wake_from_any
# Encontre seu adaptador de rede, então:
powercfg /devicedisablewake "Your Network Adapter Name"
- Interferência de antivírus - Alguns softwares antivírus interceptam conexões TCP. Adicione o executável do worker e a porta 8473 às exclusões.
Matriz de Compatibilidade de Versões
Garantir a compatibilidade de versões entre todos os componentes é crítico para uma operação estável do Remote Control.
| Componente | Versão Mínima | Notas |
|---|---|---|
| Cursor (Host) | 0.45+ | Suporte a Remote Control começou aqui |
| @cursor/remote-worker | 1.0.0+ | Pacote do worker |
| @cursor/remote-cli | 1.0.0+ | Pacote do CLI |
| Node.js (Host) | 18.x, 20.x, 22.x | Evitar 24.x até better-sqlite3 fornecer builds 137 |
| Node.js (Controlador) | 18.x+ | Mais flexível, sem módulos nativos |
| better-sqlite3 | 11.0.0+ | Verifique a disponibilidade de pré-construções para sua versão do Node |
| Windows | 10 1903+ / 11 | PowerShell 5.1 mínimo |
As versões do worker e do CLI devem ser compatíveis. Um worker executando v1.0.0 pode não funcionar com um CLI executando v1.5.0 se houver mudanças de protocolo incompatíveis. Sempre verifique o changelog ao atualizar qualquer um dos componentes. Se você atualizar um, atualize ambos.
Verificação de Compatibilidade de Versões
# No Host, verifique as versões do worker e do banco de dados
cursor-remote-worker --version
cursor-remote-worker --check-deps
# No Controlador, verifique a versão do CLI
cursor-remote --version
# Verificar a versão de ABI do Node.js
node -e "console.log(process.versions.modules)"
O sinalizador --check-deps executa um diagnóstico que verifica:
- Compatibilidade de versão do Node.js
- Compatibilidade de binário do better-sqlite3
- Dependências de sistema necessárias
- Disponibilidade de porta
- Permissões de escrita no diretório de configuração
Configuração Avançada
Configuração de Túnel SSH
Para conexões seguras pela internet, use um túnel SSH:
# No Controlador, criar um túnel SSH para o Host
ssh -L 8473:localhost:8473 [email protected] -N
# Então conectar o CLI ao 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"
Isso canaliza todo o tráfego através de criptografia SSH, o que é muito mais seguro do que expor a porta diretamente.
Configuração Multi-Host
Você pode controlar múltiplas máquinas Host a partir de um Controlador:
{
"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"
}
]
}
Alternar entre hosts:
# Executar uma tarefa em um host específico
cursor-remote agent --host win-build-server --prompt "Fix the failing CI pipeline test"
# Listar todos os hosts e seus status
cursor-remote hosts --status
Injeção de Variáveis de Ambiente
Passe variáveis de ambiente para o worker para tarefas de 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"
Variáveis de ambiente passadas via CLI são visíveis na lista de processos tanto na máquina do Controlador quanto do Host. Nunca passe segredos de produção reais desta forma. Use um gerenciador de segredos ou arquivos de variáveis de ambiente com permissões restritas em vez disso.
Melhores Práticas de Segurança
- Rotacione o token de autenticação regularmente:
cursor-remote-worker regenerate-token - Use túneis SSH para qualquer conexão que atravesse redes não confiáveis
- Restrinja regras de firewall a endereços IP específicos, não "any"
- Execute o worker como usuário não-administrador quando possível
- Habilite o registro do worker e revise os logs semanalmente em busca de padrões de acesso inesperados
- Desative o worker quando não estiver em uso em máquinas compartilhadas ou na nuvem
- Mantenha o worker e o CLI atualizados para obter correções de segurança
Resumo
O Cursor Remote Control no Windows é um recurso poderoso que estende o desenvolvimento assistido por IA a máquinas remotas e sem interface. A configuração envolve um processo worker no Host e um CLI no Controlador, com comunicação via TCP. A falha mais comum, better-sqlite3 NODE_MODULE_VERSION 127 vs 137, é causada por incompatibilidades de versão do Node.js e é resolvida recompilando o complemento nativo para sua versão atual do Node.js ou fixando o worker a uma instalação específica do Node.js. Seguindo as orientações de compatibilidade de versões e as melhores práticas de segurança deste guia, você pode manter uma configuração de Remote Control estável e segura no Windows.