Servidor na nuvem
Vale para 0.21+
O daemon roda numa VM na nuvem do mesmo jeito que num computador em casa: instale com o instalador de uma linha pelo SSH, rode remote-harness setup e pareie o celular escaneando o QR code que a instalação mostra no terminal. Esta página cobre o que muda num servidor: ninguém está logado, você chega nele por SSH e a rede fica atrás do firewall do provedor.
Portas e rede
Nenhuma porta de entrada é necessária. O daemon abre uma conexão de saída para o seu relay de conexão e o app o encontra lá, com criptografia de ponta a ponta. A VM só precisa de HTTPS de saída (TCP 443) para:
us.relay.remoteharness.appebr.relay.remoteharness.app, os relays de conexão (ou o seu próprio);push.remoteharness.app, para as notificações, a menos que você use a sua própria conta de serviço do Firebase;github.com, para oremote-harness update.
A maioria dos provedores libera todo o tráfego de saída por padrão. Numa rede que filtra a saída, libere esses hosts; o remote-harness doctor diz se os relays respondem.
O caminho direto (o WebSocket na porta 7337, wsPort na configuração) é opcional num servidor. O daemon anuncia os endereços das próprias interfaces de rede, e na AWS, no GCP e na Oracle Cloud o IP público não é um deles (o provedor faz a tradução), então o celular só alcança esses endereços por uma VPN como Tailscale ou WireGuard, cujo endereço de interface o daemon também anuncia. Bridges de contêiner e de VM (docker0, br-…, virbr0…) ficam de fora. Na DigitalOcean o IP público está na eth0, então abrir a 7337 faz o caminho direto funcionar de qualquer lugar; o canal continua cifrado com Noise e só celulares pareados entram, mas prefira a VPN ou limite a regra a endereços em que você confia. Nunca abra a porta dos hooks (7338): ela só escuta em 127.0.0.1.
Regras de firewall por provedor
Só para o caminho direto; pule esta seção quando o relay bastar.
| Provedor | Onde | Regra |
|---|---|---|
| AWS EC2 / Lightsail | O security group da instância (Lightsail: Networking → IPv4 firewall) | Entrada TCP 7337 a partir da sua faixa de origem |
| DigitalOcean | Networking → Firewalls (Cloud Firewall ligado ao droplet) | Entrada TCP 7337 a partir da sua faixa de origem |
| Google Cloud | VPC network → Firewall | gcloud compute firewall-rules create remote-harness --allow tcp:7337 --source-ranges <faixa> --target-tags remote-harness, e a tag na VM |
| Oracle Cloud | A security list da sub-rede ou o network security group da VNIC, e o iptables da própria VM |
Entrada TCP 7337, depois sudo iptables -I INPUT -p tcp --dport 7337 -j ACCEPT e sudo netfilter-persistent save (as imagens Ubuntu da Oracle rejeitam tudo menos SSH no iptables) |
Com ufw na VM, rode também sudo ufw allow 7337/tcp. Para desligar o caminho direto de vez, ponha "direct": "off" no arquivo de configuração.
Manter o daemon rodando sem login
- Serviço:
remote-harness service install(a instalação já faz) cria uma unidade de usuário do systemd. Uma unidade de usuário para quando a sua última sessão SSH termina, a menos que o linger esteja ligado; a instalação ofereceloginctl enable-linger, ou rodesudo loginctl enable-linger "$USER"você mesmo.loginctl show-user "$USER" -p Lingerdeve dizerLinger=yes, eremote-harness service statusque a unidade está ativa. - Chaves: o daemon guarda as chaves no Secret Service quando o
secret-toolestá instalado e um chaveiro responde. Um servidor sem sessão gráfica em geral não tem chaveiro, então o daemon usa um arquivo0600em~/.remote-harness/secrets/e lembra essa escolha. Oremote-harness doctormostra o armazenamento em uso;REMOTE_HARNESS_TOKEN_STORE=fileforça o arquivo. Trocar de armazenamento perde as chaves: pareie o celular de novo depois. - Sem systemd (algumas imagens de contêiner): rode
remote-harness startnuma janela do tmux e reconecte depois de um reboot. - Suspensão: uma VM na nuvem não suspende por inatividade, então a opção de manter acordado não muda nada lá. Parar a instância (ou uma instância spot ser recolhida) para o daemon e as sessões junto; o serviço volta com a VM, as sessões do tmux não.
O terminal por SSH
TERM: entrar por SSH a partir do Ghostty ou do kitty manda um tipo de terminal que o servidor pode não conhecer (xterm-ghostty,xterm-kitty). Os atalhos caem paraxterm-256color; para manter os recursos do seu terminal copie a descrição dele:infocmp -x "$TERM" | ssh <host> -- tic -x -. Veja o alias diz "missing or unsuitable terminal".- Locale: imagens mínimas muitas vezes não têm um locale UTF-8, e aí o tmux desenha caixas e acentos errado. Instale um e defina no perfil do shell:
sudo locale-gen pt_BR.UTF-8(Debian/Ubuntu), depoisexport LANG=pt_BR.UTF-8no~/.profile. O próprio daemon já roda o tmux em modo UTF-8. - Anexar: o seu alias abre a sessão na sessão
claude-remotedo servidor tmux próprio do Remote Harness e se anexa a ela; desanexe comCtrl-b dantes de fechar o SSH e volte comremote-harness tmuxno próximo login. A sessão continua rodando e controlável pelo celular.
Conexões instáveis
Os keepalives são mais curtos que qualquer tempo ocioso comum: o relay pinga o daemon e o celular a cada 25 s, o daemon derruba uma conexão com o relay que fica 90 s em silêncio e reconecta, e o app pinga uma conexão quieta a cada 30 s e troca uma que não responde em 10 s. Gateways de NAT (AWS 350 s, Google Cloud NAT 20 minutos) e balanceadores de carga (em geral de 60 a 350 s) portanto não devem cortar uma conexão em uso.
Se o app ainda vive reconectando:
- Atualize os dois lados:
remote-harness updateno servidor e o app em Ajustes → App. Versões anteriores deixavam o relay fechar uma conexão quieta depois de 10 minutos, e o app tentava todos os endereços anunciados antes do relay a cada reconexão. - Procure
relay connection closederelay connection failedem~/.remote-harness/logs/daemon.log: muitas delas apontam para a rede do servidor (um proxy de saída, um firewall que corta conexões longas). Oremote-harness doctorconfere se os relays respondem. - Não ponha a porta do daemon atrás de um balanceador de carga: o caminho pelo relay não precisa de nada de entrada. Se expuser a
7337por um, ligue o suporte a WebSocket e ponha o tempo ocioso em pelo menos 60 s. - Um firewall que descarta em silêncio (em vez de recusar) a porta
7337não atrapalha: o app desiste de um endereço direto depois de 3 s e, uma vez conectado pelo relay, reconecta por ele primeiro.
A investigação por trás desses valores está na issue #442. Ainda com problema? Abra uma issue com a saída do remote-harness doctor e as linhas do log do daemon em volta das quedas, como em pedindo ajuda.