Desenvolvimento e Gerenciamento Remoto

Este guia trata de quatro assuntos: abrir o seu VelaTerm para outros dispositivos da sua rede, conectar-se a outras máquinas por SSH ou por um link de emparelhamento, compartilhar conversas com os seus próprios dispositivos por meio de uma conta VelaTerm e transferir arquivos de e para máquinas remotas.

1. Pontos de entrada

Os recursos remotos ficam no lado direito da barra de título:

• O ícone de globo é o "Acesso remoto (navegador)". Ele permite que um celular, um tablet ou outro computador da sua rede use este VelaTerm em um navegador. Enquanto o servidor está em execução, o ícone fica destacado na cor de destaque e a dica de ferramenta passa a incluir "Em execução · porta N".
• O ícone de seta é o "Conectar a servidor remoto". Ele transforma esta máquina em cliente de outra máquina, por SSH, por um link de emparelhamento ou pela sua conta VelaTerm.
• O ícone de pessoa é a entrada "Conta", marcada como "Experimental". Com ela, você entra em uma conta VelaTerm neste computador e compartilha conversas pela internet com os seus outros dispositivos conectados à conta.

O botão "Compartilhar", ao lado deles, abre "Compartilhar o VelaTerm", que serve para recomendar o VelaTerm a outras pessoas; ele não compartilha nenhuma sessão.

2. Como abrir esta máquina para outros dispositivos (Acesso remoto)

2.1 Inicie o servidor

Clique no botão de globo. Escolha uma "Porta" (8799 por padrão; a última porta usada é lembrada), um endereço "IP" para o link de emparelhamento ("Automático (primeiro endereço LAN)" ou uma interface específica; as interfaces de VPN são marcadas como "VPN") e uma senha de acesso ("Definir senha de acesso") e depois clique em "Iniciar servidor".

A senha de acesso é exigida de todos os dispositivos que se conectam. Enquanto o servidor está em execução, o painel informa: "O acesso remoto reinicia automaticamente ao reabrir o aplicativo. 'Parar servidor' desativa isso." Se a inicialização automática falhar em uma abertura posterior, o painel mostra "Falha no início automático:" seguido do motivo.

A caixa de seleção "Espelhar o layout em todos os dispositivos" vem marcada por padrão. Com ela marcada, as abas, as divisões e a sessão ativa ficam iguais em todos os dispositivos conectados, enquanto o foco do teclado continua independente em cada um. Desmarque-a se cada dispositivo precisar organizar as próprias abas.

2.2 Conecte um dispositivo

Com o servidor em execução, o painel mostra o status, a "Impressão digital do certificado (SHA-256)", um link de emparelhamento e um QR code:

Para conectar um dispositivo, leia o QR code com a câmera dele ou envie o link de emparelhamento para ele (por exemplo, por AirDrop ou em uma mensagem para você mesmo), abra o link em um navegador e digite a senha de acesso. O link de emparelhamento e a senha são obrigatórios; abrir o endereço sem o link de emparelhamento mostra "Este servidor requer um link de emparelhamento." O tráfego entre o navegador e esta máquina tem criptografia de ponta a ponta.

Dois pontos são importantes para a segurança:

• O link de emparelhamento contém credenciais de acesso. Compartilhe-o apenas com os seus próprios dispositivos. Se você achar que ele vazou, clique em "Regenerar link (desconecta todos)": o link antigo deixa de funcionar imediatamente e todos os dispositivos conectados são desconectados até abrirem o novo link.
• Na primeira visita, o navegador avisa que o certificado não é confiável, o que é esperado para um certificado autoassinado. Compare a impressão digital mostrada pelo navegador com a do painel. Se forem iguais, você está conectado à sua própria máquina.

Se a máquina tiver várias interfaces de rede (cabo, Wi-Fi, VPN), o painel mostra o endereço preferencial e lista os demais em "mais N links". Escolha o endereço que está na mesma rede do dispositivo que você vai conectar.

Os links de emparelhamento continuam válidos quando o VelaTerm é reiniciado. Somente "Regenerar link (desconecta todos)" os substitui.

2.3 O que o cliente de navegador pode fazer

A página de login e a interface principal em um dispositivo conectado:

Um cliente de navegador trabalha com as mesmas sessões ativas do aplicativo desktop: a mesma árvore de projetos e a mesma saída de terminal e de conversa, e qualquer um dos lados pode digitar. Com "Espelhar o layout em todos os dispositivos" ativado, a barra de título do host mostra "Espelhado por N"; clique nesse item para ver os "Clientes conectados", com o nome, o endereço e o horário de conexão de cada um. Os nomes dos clientes são informados pelos próprios clientes, então trate-os como rótulos, e não como prova de identidade.

Quando o mesmo terminal está aberto em vários dispositivos, o tamanho dele acompanha um desses dispositivos. Os outros mostram uma cópia em escala com o selo "⤢ Espelho … · clique para ajustar a esta janela" no canto superior direito do terminal; clique nele para dimensionar o terminal para a janela atual.

Os clientes de navegador não têm abas de navegador nem a opção de colagem nativa de imagens. Eles podem enviar e baixar arquivos na aba Arquivos (§5).

2.4 Dispositivos emparelhados

Clique em "Dispositivos emparelhados" no painel em execução para ver todos os dispositivos que já se conectaram, com o horário da "Última conexão":

Para bloquear um dispositivo, clique em "Bloquear" e depois em "Confirmar bloqueio". O dispositivo é desconectado na hora e não consegue se reconectar até abrir um novo link de emparelhamento; os outros dispositivos não são afetados. Para desconectar todos os dispositivos de uma vez, use "Regenerar link (desconecta todos)".

2.5 Pare o servidor

Clique em "Parar servidor" na parte inferior do painel. Os clientes de navegador são desconectados, e as sessões em execução continuam, porque pertencem ao aplicativo desktop. Parar o servidor também desativa a inicialização automática; na próxima vez que você iniciar o servidor, digite a senha de acesso novamente.

3. Conexão com outras máquinas

Clique no botão de conexão na barra de título. O painel tem três abas: "SSH", "URL" e "Remote".

3.1 SSH: a máquina remota só precisa de SSH

Use esta opção para uma máquina remota sem nenhum componente do VelaTerm. A máquina remota pode executar Linux (x86_64 ou ARM64), macOS (Apple silicon ou Intel) ou Windows (x86_64); as máquinas Windows podem usar o servidor OpenSSH da Microsoft ou um servidor SSH do Cygwin ou do MSYS2. A conexão executa toda a configuração automaticamente: o VelaTerm detecta o sistema remoto, copia para ele o servidor VelaTerm correspondente, inicia o servidor para que ele continue funcionando por conta própria, encaminha uma porta local para ele e abre uma janela remota que faz login automaticamente.

Digite user@host[:port] e clique em "Conectar". Detalhes que vale a pena conhecer:

Verificação da chave do host. A primeira conexão com um host mostra a "Impressão digital da chave do host SSH" dele com o aviso "Primeira conexão com este host — verifique a impressão digital antes de continuar." Confira a impressão digital e clique em "Impressão correta, conectar"; a chave é salva em known_hosts e a pergunta não se repete. Se a chave de um host conhecido mudar, aparece um aviso em vermelho: "⚠ A chave deste host mudou — pode ser uma reinstalação do servidor ou um ataque man-in-the-middle. Continue apenas se tiver certeza." Descubra o motivo antes de confirmar.

Autenticação. Sua configuração de SSH existente (ssh-agent, ~/.ssh/config e chaves) é usada como está. Um pedido de "Senha SSH" só aparece quando a autenticação por chave falha. "Lembrar senha" guarda a senha no chaveiro do sistema, nunca no banco de dados, e a usa na próxima vez.

Espelhar o app de desktop remoto. Esta opção vem desativada por padrão e é lembrada para cada host. Ative-a quando a máquina remota também executar o aplicativo desktop do VelaTerm e você quiser ver exatamente o que ele mostra: as mesmas abas, divisões e sessão ativa, com as alterações feitas em qualquer lado aparecendo nos dois. Se o aplicativo desktop não estiver em execução na máquina remota, o VelaTerm abre diretamente o banco de dados dele ou, se não houver um, um banco de dados separado. Sem essa opção, o servidor remoto usa o próprio diretório de dados (~/.velaterm/data, ou %USERPROFILE%\.velaterm\data no Windows), separado de qualquer aplicativo desktop instalado lá.

Se você mantiver Option (Alt no Windows e no Linux) pressionada ao clicar no botão de conexão, aparecerá mais uma opção quando o espelhamento estiver desativado: "Usar o banco de dados do app de desktop remoto". Ela permite que o servidor remoto abra o banco de dados do aplicativo desktop remoto sem se vincular ao aplicativo em execução. É recomendável manter os dois na mesma versão do VelaTerm.

Hosts recentes. Os hosts aos quais você já se conectou aparecem em "Hosts recentes" ("Ver todos (N)" mostra a lista completa). Clicar em um item apenas preenche o formulário; revise-o e clique em "Conectar". Um ícone de chave indica uma senha salva, e × ("Esquecer este host") remove o host e a senha salva.

Progresso. A primeira conexão copia o servidor (dezenas de MB), e o botão mostra "Preparando servidor…", "Transferindo servidor…" e "Iniciando servidor…" com uma porcentagem. As conexões seguintes reutilizam o servidor que já está na máquina remota e são bem mais rápidas.

3.2 URL: a outra máquina está com o Acesso remoto em execução

Use esta opção quando o VelaTerm de outra máquina estiver com o Acesso remoto em execução (§2) e você tiver o link de emparelhamento dele. Em comparação com abrir o link em um navegador, você ganha uma janela dedicada, login automático com a senha salva no chaveiro do sistema e verificação de impressão digital feita pelo aplicativo.

Cole o link de emparelhamento, digite a "Senha de login" definida na outra máquina e clique em "Conectar". A primeira conexão mostra a impressão digital do certificado TLS da outra máquina; compare-a com a "Impressão digital do certificado (SHA-256)" exibida no painel daquela máquina. As conexões seguintes com a impressão digital inalterada são feitas diretamente, e uma impressão digital alterada gera um aviso em vermelho. Os links de emparelhamento recentes aparecem abaixo do formulário, como os hosts SSH.

3.3 Remote: seus dispositivos conectados à mesma conta

A aba "Remote" lista os dispositivos conectados à sua conta VelaTerm (§4). Cada dispositivo mostra "Online" ou "Offline" e o que compartilha, por exemplo "Todo o espaço de trabalho", um projeto ou uma conversa, ou "Este dispositivo não tem conteúdo compartilhado." Quando um dispositivo está online e compartilhando, "Ver conteúdo compartilhado →" abre o conteúdo compartilhado dele em uma nova janela. Se você não tiver entrado na conta, a aba mostra um link "Entrar no VelaTerm".

4. Compartilhamento pela sua conta VelaTerm (experimental)

O compartilhamento pela conta permite continuar, a partir dos seus outros dispositivos e pela internet, as conversas de IA em execução em um computador, sem abrir portas nem estar na mesma rede. O conteúdo compartilhado passa pelo velaterm.com com criptografia de ponta a ponta. Este recurso é experimental.

4.1 Entre na conta

Clique no botão de conta na barra de título. A caixa de diálogo "Conta" mostra "Entrar no VelaTerm"; clique nesse item para continuar no navegador. Enquanto aguarda, o VelaTerm mostra "Conclua a entrada no navegador e volte ao VelaTerm." Você pode expandir "Detalhes da solicitação de entrada" para comparar a solicitação com o que o site mostra.

Depois que você entra, a caixa de diálogo mostra seu nome e "ID da conta:", um botão "Conta" que abre a página da sua conta no velaterm.com e "Sair". Sair desconecta este computador e interrompe tudo o que ele compartilha.

4.2 Compartilhe conteúdo

Em "Compartilhar conteúdo", escolha um "Escopo do compartilhamento": "Todo o espaço de trabalho", "Projeto" ou "Conversa". Para um projeto ou uma conversa, escolha o item na lista e clique em "Compartilhar conteúdo". Cada item compartilhado aparece em "Compartilhamento ativo" com o status ("Compartilhamento ativo" ou "Conteúdo compartilhado indisponível") e um botão "Parar de compartilhar". Você pode compartilhar vários itens ao mesmo tempo. Os compartilhamentos permanecem após uma reinicialização e só ficam disponíveis enquanto este computador estiver executando o VelaTerm e conectado à internet.

Apenas as conversas de IA são compartilhadas. Terminais comuns e páginas de navegador nunca são compartilhados, e um dispositivo que visualiza o conteúdo compartilhado não pode abrir terminais, arquivos, configurações nem novas abas.

4.3 Abra o conteúdo compartilhado em outro dispositivo

Em outro dispositivo conectado à mesma conta, abra a aba "Remote" do botão de conexão (§3.3) e clique em "Ver conteúdo compartilhado →". Você pode ler as conversas compartilhadas. Também pode enviar mensagens, interromper o agente e responder às solicitações de permissão dele, mas apenas nas sessões que o computador que compartilha exibe na visão de conversa; para as outras sessões, a janela explica que o host precisa primeiro mudar a sessão para a visão de conversa.

Lembre-se de que um agente de IA age com as permissões do usuário no computador que compartilha: ele pode executar comandos e alterar arquivos lá. Qualquer pessoa que possa continuar uma conversa compartilhada pode dar instruções ao agente, então compartilhe apenas com dispositivos que você controla e use "Parar de compartilhar" quando não precisar mais do acesso.

5. Transferência de arquivos

Nos clientes de navegador e nas janelas remotas por URL e por SSH, a aba Arquivos do painel direito pode transferir arquivos entre o seu dispositivo e a máquina que executa as sessões. O aplicativo desktop local não precisa desse recurso e não mostra essas ações.

• Envio: clique com o botão direito em uma pasta, ou em um arquivo dentro dela, e escolha "Enviar arquivos…"; clique no botão de envio no cabeçalho de Arquivos ("Enviar arquivos para esta pasta"); ou arraste arquivos para a árvore de arquivos. Não é possível enviar pastas.
• Download: clique com o botão direito em um arquivo e escolha "Baixar". Em um navegador, o arquivo passa pelo gerenciador de downloads do próprio navegador. Em uma janela remota por URL ou SSH, uma caixa de diálogo de salvamento pergunta onde guardar o arquivo (por padrão, na pasta Downloads).

Os envios, e também os downloads nas janelas remotas, aparecem na lista "Transferências" com tamanho, velocidade e tempo restante. Clique no botão de cancelar para interromper um item e em "Limpar" para remover os itens concluídos. Se a conexão cair durante um envio, o item mostra "Reconectando…" e o VelaTerm continua tentando por cerca de um minuto. Um envio interrompido nunca deixa um arquivo parcial no destino, e enviar o mesmo arquivo de novo retoma o envio de onde ele parou.

6. Uso do VelaTerm no celular

Abra um link de emparelhamento (§2.2) no navegador do celular, por exemplo lendo o QR code do painel Acesso remoto. No celular, o VelaTerm muda para um layout projetado para telas sensíveis ao toque pequenas. O layout é escolhido quando a página carrega: ele é usado em dispositivos de toque cujo lado menor da tela tem menos de 768 pixels. Adicione ?view=mobile ou ?view=desktop ao endereço para escolher o layout você mesmo (um tablet pode usar ?view=mobile) ou escolha "Mudar para a versão desktop" no menu "Mais ações" (•••); a escolha é lembrada.

O layout para dispositivos móveis tem dois níveis:

• Lista de sessões: a árvore de projetos com uma caixa de busca ("Buscar sessões / grupos…") e filtros de status ("Em andamento", "Pendente", "Visto"). As sessões são criadas no aplicativo desktop ou em um navegador de computador e aparecem aqui automaticamente.
• Página da sessão: toque em uma sessão para abri-la e use "‹ Voltar" para retornar à lista. As sessões na visão de conversa mostram a conversa completa. As sessões de Claude Code, Codex, OpenCode, Pi e OMP executadas na visão de terminal mostram a conversa com uma caixa de mensagem que digita no terminal. As demais sessões mostram o terminal com uma barra de teclas: Esc, Tab, Ctrl (que abre uma linha de combinações com Ctrl, como ^C, ^D, ^R e ^W), as setas, ^C, um botão de teclado e um botão de câmera para enviar uma imagem. Deslize para rolar, toque para mostrar o teclado e mantenha o dedo pressionado para selecionar uma palavra e escolher "Copiar".

O layout para dispositivos móveis não mostra abas de navegador, abas de documento nem painéis divididos, não tem atalhos de teclado e mantém a própria visualização em vez de seguir "Espelhar o layout em todos os dispositivos". As sessões do Kiro oferecem o histórico em uma visualização somente leitura.

Um aplicativo VelaTerm para iOS e Android está em desenvolvimento e ainda não foi publicado.

7. Desconexão, fechamento e o que é preservado

7.1 Três camadas de estado

A resposta à pergunta "tudo continua lá depois de uma desconexão?" depende da camada:

Só a terceira camada exige atenção: enquanto o processo do servidor remoto estiver em execução, as suas sessões em execução continuam funcionando.

7.2 Fechamento de uma janela remota

SSH: o servidor remoto foi iniciado por esta conexão, então fechar a janela abre "Disconnect remote" com três opções. "Stop server" desliga o servidor na máquina remota e encerra as sessões em execução nele. "Keep running" apenas desconecta esta janela; a próxima conexão com essa máquina reutiliza o servidor com todas as sessões intactas. "Cancel" mantém a janela aberta. Escolha "Keep running" se os agentes precisarem continuar trabalhando enquanto você estiver ausente.

SSH vinculado ao aplicativo desktop remoto: quando "Espelhar o app de desktop remoto" vinculou a janela a um aplicativo desktop em execução, fechar a janela apenas desconecta; o aplicativo desktop continua em execução.

URL: você era um convidado de um VelaTerm que já estava em execução. Fechar a janela significa apenas que você sai; o outro lado continua em execução, e tudo estará lá quando você voltar.

7.3 Quedas de conexão

Quando a rede cai, uma barra vermelha aparece no topo da janela remota com "Conexão perdida, reconectando…", e o VelaTerm tenta novamente de forma automática. As sessões em execução não são afetadas; no modo SSH, o servidor remoto funciona independentemente da conexão SSH.

Nas janelas SSH, o VelaTerm também reconstrói o túnel SSH por conta própria ("Conexão SSH perdida, reconstruindo o túnel…"). Se ele desistir, a barra passa a exibir "A conexão SSH caiu — clique em 'Reconectar agora' para tentar novamente"; clique em "Reconectar agora". Se o próprio servidor remoto tiver parado, reconectar pela janela não resolve: volte à janela principal e conecte-se novamente. A conexão verifica se o servidor remoto ainda está em execução, reutiliza-o se estiver (com todas as sessões) e só inicia um novo se não estiver.

Quando a máquina remota entra em suspensão, faz logout ou é reiniciada, o servidor no modo SSH e as sessões em execução nele são encerrados. A árvore de projetos fica armazenada no disco e não é afetada.

7.4 Referência rápida

8. Segurança em resumo

• As senhas (senhas SSH e senhas de login remoto) são armazenadas apenas no chaveiro do sistema, nunca no banco de dados, e somente quando você escolhe "Lembrar senha". A senha do Acesso remoto é armazenada apenas como hash, para que o servidor possa reiniciar automaticamente.
• O acesso pelo navegador na rede local usa TLS com um certificado autoassinado. Os links de emparelhamento contêm as credenciais da criptografia de ponta a ponta, e o servidor recusa conexões sem link de emparelhamento.
• As chaves de host SSH e os certificados TLS remotos são considerados confiáveis no primeiro uso: destinos conhecidos e inalterados se conectam diretamente, destinos novos pedem uma confirmação e impressões digitais alteradas mostram um aviso em vermelho. Investigue antes de confirmar.
• Dispositivos individuais podem ser bloqueados a qualquer momento (§2.4), e o link de emparelhamento pode ser regenerado sempre que você quiser.
• O compartilhamento pela conta se limita às conversas de IA, mas os agentes dessas conversas agem com as suas permissões no computador que compartilha (§4.3).

Se a barra de título mostrar um selo "⚠ vX ≠ vY", a interface e o serviço VelaTerm ao qual ela está conectada informam versões diferentes, e alguns recursos podem não funcionar em conjunto. Atualize o VelaTerm para que os dois usem a mesma versão.

9. Perguntas frequentes

A janela está conectada, mas a barra lateral continua vazia ou a barra vermelha não desaparece. Provavelmente o servidor remoto parou. Volte à janela principal e conecte-se novamente (§7.3).

O servidor não inicia na porta 8799. Outro programa está usando a porta. Escolha outra porta no painel e inicie novamente.

O navegador diz que o certificado não é confiável. Isso é esperado para um certificado autoassinado. Confira a impressão digital e continue (§2.2).

Um agente em uma máquina remota precisa continuar trabalhando enquanto estou ausente. No modo SSH, escolha "Keep running" ao fechar a janela. A sessão continua na máquina remota, e você pode se reconectar depois e retomar de onde ela estava.

Um terminal aparece minúsculo no meu celular. Trata-se de uma cópia em escala que acompanha o tamanho de outro dispositivo. Toque em "clique para ajustar a esta janela" no selo do canto superior direito do terminal para dimensioná-lo para o celular.

"Ver conteúdo compartilhado" não aparece para o meu computador. O botão só aparece quando esse computador está online, conectado à mesma conta e compartilhando algo. Abra o VelaTerm nele e verifique "Compartilhamento ativo" na caixa de diálogo "Conta".