DeskVNCServer - Guia

Primeiros passos

1. Defina uma senha

Abra as Configurações (ícone de engrenagem, barra de ferramentas inferior) e preencha Senha do VNC. Clientes VNC padrão usam o desafio DES do RFB, que só considera os primeiros 8 bytes compatíveis com ASCII — escolha uma senha com no máximo 8 caracteres.

2. Inicie o servidor

1. Na janela principal, clique em Iniciar. O indicador de status muda para Em execução.
2. Quatro listeners sobem de uma vez: VNC 5900, controle QREX 5911, mídia QREX 4010e a API de arquivos 8766.
3. Clique em Copiar informações para copiar para a área de transferência uma única linha com o host, as portas e o PIN atual.

3. Conecte um cliente

Para um visualizador VNC padrão (Compartilhamento de Tela do macOS, RealVNC, TightVNC, apps VNC para celular):

1. Abra o visualizador e informe vnc://<seu-ip-do-mac>:5900 como endereço
2. Digite a senha do VNC definida no passo 1
3. Controle o seu Mac imediatamente — teclado, mouse, copiar/colar via RFB

Para o app QuickRemote:

1. Abra o QuickRemote no celular ou tablet e escolha Adicionar Mac
2. Informe o PIN de pareamento de 6 dígitos exibido pelo DeskVNCServer (ou escaneie o QR code, se a sua versão do QuickRemote oferecer suporte)
3. O QuickRemote guarda o token Bearer retornado e libera os recursos estendidos — IME, áudio, sincronização da área de transferência e transferência de arquivos

Visão geral da interface

Linha de status

Botões de ação

• Iniciar — Ativa os quatro listeners.
• Parar — Fecha todos os listeners e desconecta as sessões ativas.
• Copiar informações — Copia um resumo curto da conexão (host, porta VNC, porta de controle, PIN) para a área de transferência, facilitando o compartilhamento com um cliente.

Painel de conexão

Mostra o host de vinculação, as portas, o ID do servidor atual e o PIN de pareamento ativo. O texto é atualizado automaticamente quando as configurações mudam.

Painel da API do QuickRemote

Referência rápida dos protocolos que o servidor fala. Lista as versões RFB suportadas, o formato dos endpoints QREX e o conjunto de comandos do IME, para que o QuickRemote (ou o seu próprio cliente) saiba o que está disponível.

Protocolos e portas

Autenticação

• Clientes VNC — Senha DES do RFB (os primeiros 8 bytes compatíveis com ASCII da senha configurada).
• Clientes QREX — A troca inicial do PIN de 6 dígitos em POST /qr/v1/pair retorna um token Bearer. Toda chamada HTTP QREX e todo frame WebSocket seguintes precisam incluir Authorization: Bearer <token>.
• Se a senha do VNC estiver vazia, o servidor anuncia o modo sem autenticação padrão do RFB. Útil apenas em segmentos de LAN confiáveis.

Referência rápida dos endpoints QREX

GET  /qr/v1/capabilities    # public, returns supported features
POST /qr/v1/pair            # public, exchange PIN for Bearer token
GET  /qr/v1/ws              # WebSocket, auth required
POST /qr/v1/ime/get         # auth required, query active IME
POST /qr/v1/ime/list        # auth required, list available IMEs
POST /qr/v1/ime/set         # auth required, switch IME
POST /qr/v1/ime/toggle      # auth required, toggle IME on/off
POST /qr/v1/ime/commit      # auth required, commit a text string

Configurações

Exemplos de cliente

Compartilhamento de Tela do macOS

1. Finder → Ir → Conectar ao Servidor
2. Digite vnc://<seu-ip-do-mac>:5900
3. Informe a senha do VNC

cURL — descobrir os recursos

curl http://<seu-ip-do-mac>:5911/qr/v1/capabilities

cURL — parear e chamar a ponte de IME

# 1. Exchange the PIN for a Bearer token
TOKEN=$(curl -s http://<your-mac-ip>:5911/qr/v1/pair \
  -H "Content-Type: application/json" \
  -d '{"pin":"123456"}' | jq -r .token)

# 2. Commit text via the IME bridge
curl http://<your-mac-ip>:5911/qr/v1/ime/commit \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"hello from remote"}'

Dicas

• Reduza a taxa de quadros e as dimensões máximas do quadro quando estiver em um Wi-Fi lento ou passando a conexão por uma VPN.
• Pareie cada dispositivo uma vez. Depois da troca inicial do PIN, o token Bearer sobrevive a reinicializações, então o QuickRemote reconecta silenciosamente.
• Use Copiar informações como uma forma rápida de enviar os detalhes da conexão por chat ou e-mail — inclui tudo o que um cliente precisa.
• Mantenha Ativar alterações de arquivos desativado, a menos que você realmente precise de envios. O modo somente leitura já basta para consultar capturas de tela, notas ou downloads.
• Desative a API de áudio quando não estiver usando. Codecs ociosos ainda consomem um pouco de CPU no caminho de codificação.

Solução de problemas

O servidor não inicia

• Outro servidor VNC (por exemplo, o Compartilhamento de Tela do macOS) pode já estar na porta 5900. Pare-o em Ajustes do Sistema → Geral → Compartilhamento, ou mude a porta nas configurações do DeskVNCServer.
• As portas 5911 / 4010 / 8766 precisam estar todas livres. Verifique com lsof -i :5911 e comandos semelhantes.

Clientes VNC não conseguem autenticar

• Confirme que a senha tem no máximo 8 bytes compatíveis com ASCII. Caracteres multibyte ou textos mais longos são truncados silenciosamente pela autenticação DES do RFB.
• Se você realmente quiser ficar sem senha, deixe o campo vazio e conecte com um visualizador compatível com o modo sem autenticação do VNC.

O QuickRemote não consegue parear

• Confirme que o celular ou tablet está na mesma rede Wi-Fi do Mac.
• Abra o painel de conexão e leia o PIN novamente. O PIN pode ser regenerado nas Configurações.
• Verifique as configurações do firewall do macOS — as conexões de entrada nas portas QREX precisam ser permitidas.

O controle remoto está lento

• Reduza a taxa de quadros e as dimensões máximas do quadro nas Configurações.
• Desative os recursos que não estiver usando (áudio, área de transferência, IME) para liberar CPU.

Os arquivos não são transferidos

• Confirme que Ativar transferência de arquivos está ativado. As listagens somente leitura funcionam sem Ativar alterações de arquivos.
• Se os envios falharem, ative também Ativar alterações de arquivos. Caso contrário, a API de arquivos só responde a requisições de leitura.

Privacidade

• Todas as sessões acontecem diretamente entre o cliente e o seu Mac. Não há retransmissão na nuvem, telemetria nem análises.
• A senha do VNC, o token Bearer QREX, o PIN de pareamento e o ID estável do servidor ficam armazenados somente nas configurações locais do app.
• As alterações de arquivos estão desativadas por padrão. Clientes remotos só conseguem ler até que você conceda acesso de escrita explicitamente.
• Desative qualquer extensão (áudio, área de transferência, transferência de arquivos, IME, entrada remota) a qualquer momento para revogar esse recurso imediatamente.
• Se quiser manter o servidor restrito ao seu Mac, defina o host de vinculação como 127.0.0.1.