DeskVNCServer - Guia

Primeiros passos

1. Defina uma senha

Abra Ajustes (icone de engrenagem na barra inferior) e preencha a VNC password. Clientes VNC padrao usam o desafio DES do RFB, que so respeita os primeiros 8 bytes compativeis com ASCII; escolha uma senha de no maximo 8 caracteres.

2. Inicie o servidor

1. Na janela principal, clique em Start. O indicador de status muda para Running.
2. Quatro listeners sobem ao mesmo tempo: VNC 5900, controle QREX 5911, media QREX 4010 e a API de arquivos 8766.
3. Clique em Copy Info para copiar para a area de transferencia uma linha com o host, as portas e o PIN atual.

3. Conecte um cliente

Para um visualizador VNC padrao (macOS Screen Sharing, RealVNC, TightVNC, apps VNC moveis):

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

Para o app QuickRemote:

1. Abra o QuickRemote no telefone ou tablet e escolha Add Mac
2. Informe o PIN de pareamento de 6 digitos mostrado pelo DeskVNCServer (ou escaneie o QR code, se sua versao do QuickRemote suportar)
3. O QuickRemote armazena o token Bearer retornado e libera os recursos estendidos: IME, audio, sincronizacao de area de transferencia e transferencia de arquivos

Visao geral da interface

Linha de status

Botoes de acao

• Start: levanta os quatro listeners.
• Stop: fecha todos os listeners e desconecta as sessoes ativas.
• Copy Info: copia um resumo curto de conexao (host, porta VNC, porta de controle, PIN) para a area de transferencia, facilitando o compartilhamento com um cliente.

Painel de conexao

Exibe o host de bind, as portas, o Server ID atual e o PIN de pareamento ativo. O texto e atualizado automaticamente quando as configuracoes mudam.

Painel QuickRemote API

Referencia rapida dos protocolos que o servidor fala. Lista as versoes de RFB suportadas, o formato dos endpoints QREX e o conjunto de comandos IME, para que o QuickRemote (ou seu proprio cliente) saiba o que esta disponivel.

Protocolos e portas

Autenticacao

• Clientes VNC: senha RFB DES (primeiros 8 bytes compativeis com ASCII da senha configurada).
• Clientes QREX: a troca inicial do PIN de 6 digitos em POST /qr/v1/pair retorna um token Bearer. Todas as chamadas HTTP QREX e frames WebSocket subsequentes precisam incluir Authorization: Bearer <token>.
• Se a VNC password estiver vazia, o servidor anuncia o modo no-auth padrao do RFB. Util apenas em segmentos LAN confiaveis.

Referencia rapida de 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

Configuracoes

Exemplos de cliente

macOS Screen Sharing

1. Finder → Ir → Conectar ao servidor
2. Digite vnc://<your-mac-ip>:5900
3. Informe a VNC password

cURL: descobrir as capabilities

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

cURL: parear e chamar o IME bridge

# 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 dimensoes maximas de quadro em conexoes Wi-Fi lentas ou quando rotear via VPN.
• Pareie cada dispositivo apenas uma vez. Depois da troca inicial de PIN, o token Bearer sobrevive a reinicializacoes, e o QuickRemote reconecta silenciosamente.
• Use Copy Info como atalho para enviar os dados de conexao via chat ou email: inclui tudo o que um cliente precisa.
• Mantenha Enable file mutations desligado a menos que realmente precise de uploads. O modo somente leitura ja basta para examinar capturas, notas ou downloads.
• Desative a audio API quando nao estiver em uso. Codecs ociosos ainda consomem um pouco de CPU no caminho de codificacao.

Solucao de problemas

O servidor nao inicia

• Outro servidor VNC (por exemplo, macOS Screen Sharing) pode ja estar usando a porta 5900. Pare-o em System Settings → General → Sharing, ou altere a porta nas configuracoes do DeskVNCServer.
• As portas 5911 / 4010 / 8766 devem estar livres. Verifique com lsof -i :5911 e similares.

Clientes VNC falham na autenticacao

• Garanta que a senha tenha no maximo 8 bytes compativeis com ASCII. Caracteres multibyte ou strings mais longas sao truncados silenciosamente pela autenticacao RFB DES.
• Se quiser intencionalmente nao usar senha, deixe o campo vazio e conecte com um visualizador que suporte o modo no-auth do VNC.

QuickRemote nao pareia

• Confirme que o telefone ou tablet esta na mesma Wi-Fi do Mac.
• Abra o painel de conexao e releia o PIN. O PIN pode ser regerado pelas configuracoes.
• Verifique as configuracoes de firewall do macOS: as conexoes de entrada nas portas QREX precisam ser permitidas.

O controle remoto fica lento

• Reduza a taxa de quadros e as dimensoes maximas de quadro nas configuracoes.
• Desative recursos que voce nao esta usando (audio, area de transferencia, IME) para liberar CPU.

Os arquivos nao sao transferidos

• Confirme que Enable file transfer esta ligado. Listagens somente leitura funcionam sem Enable file mutations.
• Se os uploads falharem, ative tambem Enable file mutations. Caso contrario, a File API so responde a requisicoes de leitura.

Privacidade

• Todas as sessoes ocorrem diretamente entre o cliente e seu Mac. Nao ha retransmissao na nuvem, nem telemetria, nem analytics.
• A VNC password, o token Bearer QREX, o PIN de pareamento e o Stable Server ID sao armazenados somente nas configuracoes locais do app.
• Mutacoes de arquivos vem desligadas por padrao. Clientes remotos podem apenas ler ate que voce conceda acesso de escrita explicitamente.
• Voce pode desativar qualquer extensao (audio, area de transferencia, transferencia de arquivos, IME, entrada remota) a qualquer momento para revogar essa capacidade imediatamente.
• Se quiser manter o servidor restrito ao Mac, defina o bind host como 127.0.0.1.