Desenvolvimento e Gerenciamento Remoto

Este guia aborda dois tópicos: abrir seu VelaTerm local para outros dispositivos e se conectar a máquinas remotas para desenvolver e gerenciar sessões lá.

1. Dois pontos de entrada, duas direções

Ambas as funcionalidades remotas ficam no lado direito da barra de título (ao lado do alternador de temas):

O ícone de globo é Acesso Remoto (Navegador) — abre essa máquina para que um telefone, tablet ou outro computador possa usar seu VelaTerm por meio de um navegador. O ícone de seta é Conectar-se ao Servidor Remoto — essa máquina atua como cliente e se conecta para desenvolver em outra máquina. Quando o servidor está em execução, o globo acende em verde.

2. Abrir essa máquina (Acesso Remoto)

2.1 Iniciar o servidor

Clique no globo, defina uma porta (padrão 8799 — altere se estiver ocupada) e uma senha de acesso, e então clique em Iniciar Servidor:

É necessária a senha de acesso para qualquer dispositivo se conectar. Ela só é válida enquanto o servidor estiver rodando; após interrompê-lo, defina uma nova na próxima vez.

2.2 Conectar um dispositivo

Uma vez em execução, o painel exibe o status, a impressão digital do certificado e um link de emparelhamento gerado automaticamente:

Para se conectar: envie o link de emparelhamento para o seu próprio dispositivo (AirDrop, mensagem para si mesmo — o que funcionar), abra-o em um navegador e insira a senha de acesso. O link contém as credenciais de emparelhamento criptografadas; o tráfego do navegador para a máquina é criptografado do início ao fim. Duas coisas importantes:

• O link é uma chave. Compartilhe-o apenas com seus próprios dispositivos. Se suspeitar que ele vazou, clique em Gerar link novamente — o link antigo é invalidado imediatamente e todos os dispositivos conectados são desconectados até que usem o novo.
• Na primeira conexão, o navegador avisará sobre um certificado não confiável — algo normal em um certificado autoassinado. Compare a impressão digital exibida pelo navegador com a impressão digital do certificado no painel; se corresponderem, você está se comunicando com sua própria máquina.

Com várias interfaces de rede (cablada, Wi-Fi, VPN), o painel exibe o endereço preferido e oculta os demais em “1 URL a mais” — escolha aquele que está na mesma rede que o dispositivo conectado.

Abrir o mesmo link em um telefone altera automaticamente para a interface móvel (navegação em dois níveis mais uma barra de teclas de terminal) — sem necessidade de configuração.

2.3 Como é a experiência no lado do navegador

Página de login e interface principal que um dispositivo conectado vê:

O cliente do navegador compartilha as mesmas sessões ativas que a versão desktop: mesma estrutura, mesmo resultado do terminal, ambos os lados podem digitar e cada um vê as ações do outro em tempo real. A disposição das janelas (abas abertas, divisão) é específica de cada cliente e independente.

O tamanho do terminal tem um conceito de “dono”: quando uma sessão está aberta em vários clientes, o tamanho segue o dono e os outros clientes veem um espelho escalado com uma barra “Espelho … clique para ajustar esta janela” (no canto superior direito do terminal na captura acima) — clique nela para assumir o controle do tamanho da janela atual.

2.4 Gerenciamento de dispositivos

A lista de Dispositivos emparelhados no painel mostra todos os dispositivos que se conectaram:

Para bloquear um dispositivo, clique em Bloquear ao lado dele e confirme — ele é desconectado imediatamente e não pode se reconectar (precisaria de um novo link de emparelhamento); os outros dispositivos não são afetados. Os nomes dos dispositivos são informados pelos próprios clientes — trate-os como rótulos, não como identidades. Para bloquear todos de uma vez, use Gerar link.

2.5 Parar o servidor

Clique em Parar Servidor na parte inferior do painel. Os clientes do navegador se desconectam; as sessões em execução não são afetadas — elas pertencem ao aplicativo desktop em si.

3. Conectar-se para fora (Conectar-se ao Servidor Remoto)

Clique no botão de conexão na barra de título; o painel oferece os modos SSH e URL.

3.1 Modo SSH: tudo o que o remoto precisa é de SSH

Para uma caixa de desenvolvimento remota (geralmente Linux ou macOS) sem componentes VelaTerm instalados. A conexão executa automaticamente todo o processo: verifica o SO e a arquitetura remota → transfere o vela-server correspondente → inicia-o como processo persistente → configura o redirecionamento de porta local → abre uma janela remota e faz o login automaticamente.

Insira user@host[:port] e clique em Conectar. Detalhes importantes:

**Verificação da chave do host na primeira conexão.**Um novo host exibe sua impressão digital da chave do host SSH para que você possa verificar; confirme com “A impressão digital corresponde, conectar” e ela será salva em known_hosts — não haverá mais solicitações para esse host. Se a impressão digital de um host conhecido mudar, o painel ficará vermelho — descubra o motivo (SO reinstalado, máquina diferente ou alguém adulterando o link) antes de confirmar.

**Autenticação.**Sua configuração SSH existente (ssh-agent, ~/.ssh/config, chaves) é reutilizada de forma transparente; uma solicitação de senha aparece apenas quando a autenticação por chave pública falha. “Lembrar senha” armazena-a no chaveiro do sistema (nunca no banco de dados) e a reutiliza na próxima vez.

Modo de dados: "Usar o banco de dados do aplicativo de área de trabalho remota". Desmarcado (padrão): o servidor remoto usa um diretório de dados isolado (~/.velaterm/data), completamente separado de qualquer VelaTerm aplicativo de área de trabalho instalado nessa máquina. Marcado: ele utiliza o banco de dados da versão de lançamento da área de trabalho remota — ambas as partes veem a mesma árvore de sessões, o que é adequado para casos em que "essa máquina roda o VelaTerm no dia a dia e eu assumo os mesmos projetos remotamente". O que é compartilhado é o arquivo do banco de dados no disco, não os processos em execução (ver §4.1); recomenda‑se manter ambas as extremidades na mesma versão.

Hosts recentes. São listados os hosts aos quais você se conectou; clicar em um apenas preenche o campo de entrada (sem conexão automática) — revise e, em seguida, clique em Conectar. Um ícone de chave indica uma senha salva; × significa que o host (e sua senha salva) foram esquecidos.

Progresso da conexão. Na primeira conexão, o binário do servidor é transferido (dezenas de MB) — o botão exibe “Preparando”/“Transferindo” com uma porcentagem. As reconexões reutilizam o servidor já presente no lado remoto e são muito mais rápidas.

Modo URL 3.2: o outro lado já possui acesso remoto

Para quando o VelaTerm de outra máquina tem o acesso remoto em execução (§2) e você tem o link de emparelhamento. Em comparação com abrir o link em um navegador comum, você obtém uma janela dedicada, login automático com suporte ao keychain e verificação por impressão digital gerenciada pelo aplicativo.

Cole o link de emparelhamento, insira a senha de acesso definida no outro lado e clique em Conectar. Na primeira conexão, é verificada a impressão digital do certificado TLS (compare com a impressão digital de certificado exibida no painel do outro lado); depois disso, impressões digitais inalteradas permitem conexão direta. Lembrar senha funciona da mesma forma, por meio do keychain do sistema.

4. Desconectar, fechar e o que permanece

4.1 Três camadas de estado

Se “as coisas ainda estão lá após uma desconexão” depende de qual camada você está considerando:

As duas primeiras camadas são seguras por design. A única camada a ser considerada é a terceira: enquanto o processo do servidor remoto estiver ativo, suas sessões em execução também permanecem.

4.2 O que significa fechar a janela

Modo SSH: o servidor remoto foi iniciado por essa conexão e pertence a você, então ao fechar a janela é solicitado o que fazer — “Parar servidor” desliga o servidor no lado remoto (encerrando suas sessões em execução); “Manter em execução” apenas desconecta o seu lado, deixando o servidor ligado para que a próxima conexão àquela máquina o reutilize com todas as sessões intactas. Quer que os agentes continuem trabalhando enquanto você está ausente? Escolha “Manter em execução”.

Modo URL: você era um convidado de um programa que já estava rodando lá. Fechar sua janela significa apenas que você sai; o outro lado continua funcionando, e tudo permanece lá quando você voltar.

4.3 Quedas e reconexões

Em caso de problemas de rede, uma barra vermelha de reconexão aparece na parte superior da janela remota e as tentativas são feitas automaticamente; as sessões em execução não são afetadas — no modo SSH o servidor remoto é desconectado da sessão SSH (ele foi projetado para sobreviver a quedas de rede).

Um limite importante: a reconexão automática abrange apenas o trecho da janela para o porta de encaminhamento local. Se o processo do túnel SSH ou o próprio servidor remoto tiverem morrido, a barra vermelha ficará girando para sempre e a opção “Reconectar” não ajudará — volte à janela principal e conecte novamente. O fluxo de conexão verifica se o servidor remoto ainda está ativo: se estiver, ele é reutilizado (sessões intactas); somente se estiver morto é iniciado um novo.

Além disso: se a máquina remota entrar em modo de suspensão, fazer logout ou reiniciar, o servidor no modo SSH e suas sessões em execução são encerrados; a árvore de sessões, por estar no disco, não é afetada.

4.4 Referência rápida

5. Modelo de segurança em resumo

Senhas (SSH senhas de conta, senhas de login remoto) são armazenadas apenas no keychain do sistema, nunca no banco de dados, e somente quando você optar explicitamente por isso. O acesso via navegador LAN é feito por TLS com um certificado autoassinado; os links de emparelhamento transportam credenciais criptografadas de ponta a ponta, e o servidor rejeita conexões em texto plano não emparelhadas. Tanto as chaves de host SSH quanto os certificados TLS remotos seguem o princípio de confiança na primeira utilização: conexões conhecidas e inalteradas passam direto; novos destinos recebem um aviso de verificação; impressões digitais alteradas geram um aviso vermelho — investigue antes de confirmar. Dispositivos individuais podem ser bloqueados a qualquer momento (§2.4), e o link de emparelhamento pode ser gerado novamente conforme desejo.

Mais um ponto: se a barra de título da janela remota mostrar um adesivo vermelho “⚠ vX ≠ vY”, sua interface do cliente e o servidor remoto estão em versões diferentes — recursos podem não funcionar corretamente; atualize ambas as extremidades para a mesma versão.

6. Perguntas frequentes

Conectado, mas a barra lateral permanece vazia ou a barra vermelha fica girando para sempre? Provavelmente o túnel SSH ou o servidor remoto foi perdido — a reconexão dentro da janela não resolve isso (§4.3). Volte à janela principal e conecte novamente.

O porto 8799 não está iniciando? Algo else está usando esse porto; escolha outro porto no painel e tente novamente.

O navegador diz que o certificado não é confiável? Isso é normal para um certificado autoassinado — verifique a impressão digital e continue (§2.2). Para ignorar os avisos de cada navegador, acesse pelo link de emparelhamento, e o aplicativo cuidará da confiança por você.

Quer que um agente remoto continue funcionando enquanto você se afasta? No modo SSH, escolha “Manter em execução ao fechar a janela”; a sessão continuará no dispositivo remoto. Reconecte-se posteriormente e retome exatamente de onde parou.

O terminal parece muito pequeno no telefone? Isso é um espelho escalonado que segue o tamanho da área de trabalho — toque em “Clicar para ajustar esta janela” no canto superior direito do terminal para assumir o controle do tamanho no dispositivo atual.