Remote Harness GitHub ↗

Primeiros passos

Vale para 0.7+

Requisitos

  • Um computador com macOS, Linux (systemd recomendado) ou Windows 10 2004+ / 11 via WSL2, com tmux, git, rg (ripgrep), zsh e claude (ou codex, gemini, kimi, qwen) no PATH. O instalador adiciona as ferramentas que faltam.
  • Node 24+. O instalador baixa um Node privado para ~/.remote-harness/node quando ele falta, sem mexer no Node do sistema.
  • Nada para instalar no celular além do app, nenhuma VPN: em casa o app alcança o computador direto, fora dela por um relay de conexão com criptografia de ponta a ponta.
  • Um iPhone ou iPad (iOS 17+) ou um celular Android (Android 10+).

Instalar no computador

Um endereço para todos os sistemas: https://remoteharness.app/install entrega ao curl o script de macOS / Linux e ao PowerShell o do Windows. Aberto no navegador do computador, mostra o comando certo com um botão de copiar. Acrescente ?ref=<branch|tag> para outra versão, por exemplo curl -fsSL "https://remoteharness.app/install?ref=development" | bash.

macOS e Linux

curl -fsSL https://remoteharness.app/install | bash

O instalador confere o sistema e o Node, instala as ferramentas que faltam (Homebrew no macOS; apt, dnf, pacman ou zypper no Linux, com sudo depois de explicar o motivo), coloca o código em ~/.remote-harness/src, compila o daemon e abre a instalação guiada (remote-harness setup), que:

  • encontra as suas contas do Claude Code (~/.claude, ~/.claude-*) e deixa escolher quais controlar, ou cria uma nova e abre o Claude Code nela para você fazer login;
  • pergunta o alias de cada uma: o comando que abre aquela conta dentro do tmux (por exemplo pessoal, trabalho);
  • pode adicionar um perfil OpenRouter: o Claude Code pago com a sua chave do OpenRouter, que ele confere e guarda no cofre de segredos do sistema;
  • instala os atalhos, a entrada no PATH e os hooks (com backups), e o serviço em segundo plano;
  • termina no pareamento: mostra o QR code de pareamento.

Opções: bash -s -- --yes pula as perguntas, bash -s -- --ref <branch|tag> instala outra versão, bash -s -- --update atualiza sem a instalação guiada.

Windows (WSL2)

O Remote Harness controla o Claude Code pelo tmux, então no Windows ele roda dentro do WSL2, onde o Claude Code também funciona melhor. No PowerShell:

irm https://remoteharness.app/install | iex

O script confere o Windows 10 2004+ ou Windows 11, instala o WSL2 com Ubuntu quando falta (o Windows pede permissão de administrador; reinicie se pedir e rode o mesmo comando de novo), ajuda a criar o usuário Linux e executa o instalador Linux dentro da distribuição. Node e Claude Code precisam estar instalados dentro do WSL, não só no Windows. Opções: & ([scriptblock]::Create((irm https://remoteharness.app/install))) -Distro Ubuntu-24.04 -Ref main -Yes -NoService.

systemd, início no logon e a rede do WSL estão em Solução de problemas.

A partir de um clone

git clone https://github.com/maarkN/remote-harness.git
cd remote-harness
pnpm install
pnpm --filter @remote-harness/daemon build
node apps/daemon/dist/cli.js setup

Instalar o app

  • iPhone e iPad: pelo TestFlight (iOS 17+): abra o link no iPhone ou iPad, instale o app TestFlight se ele pedir, aceite o convite e instale. Aparelhos cadastrados no time de desenvolvedor também podem instalar o build ad-hoc por um link de instalação: veja Cadastrar um iPhone ou iPad. Ou compile a partir do código: com o Xcode num Mac, cd apps/mobile && pnpm ios roda no simulador ou num aparelho conectado; make install-ios faz um release build num iPhone ou iPad conectado. O CONTRIBUTING.md tem os detalhes de assinatura.
  • Android: pelo Google Play (teste): entre no teste e instale pela Play Store; ou o APK dos Releases no GitHub (permita instalar pelo navegador quando pedir), ou pnpm android e pnpm build:android a partir do repositório.

Nada mais vai no celular: não precisa de VPN. Em casa o app alcança o computador direto pela rede de casa; fora dela, passa pelo relay de conexão, que só repassa tráfego criptografado de ponta a ponta que não consegue ler.

Cadastrar um iPhone ou iPad

Fora do TestFlight, a Apple só deixa o build pelo ar (ad-hoc) instalar em aparelhos cujo identificador (UDID) está no perfil de provisionamento do time de desenvolvedor. Em qualquer outro aparelho a instalação falha. Para incluir o seu:

  1. Ache o UDID: conecte o iPhone ou iPad num Mac, selecione-o no Finder e clique na linha abaixo do nome até o UDID aparecer (Control-clique para copiar). O Xcode também mostra, em Window → Devices and Simulators.
  2. Mande-o em particular para o mantenedor, pelo contato em maarkn.dev, não numa issue pública.
  3. Depois de incluído, o próximo build publicado no link de instalação instala nesse aparelho.

Compilar a partir do código com a sua própria conta de desenvolvedor da Apple não tem essa lista: o Xcode cadastra os seus próprios aparelhos.

Parear o celular

A instalação termina com um QR code; remote-harness pair pede um novo ao daemon em execução quando quiser, assim como a bandeja e Adicionar aparelho em Ajustes → Aparelhos de um celular já pareado. Cada código pareia um aparelho e expira depois de 5 minutos; um computador aceita até 10 aparelhos, e o app pode parear vários computadores e alternar entre eles. Abra o app, escaneie e pronto: o celular cria o próprio par de chaves, guarda no armazenamento seguro e conecta direto em casa ou pelo relay de conexão fora dela, com tudo criptografado de ponta a ponta (Noise, X25519 e ChaCha20-Poly1305).

Instalou o app primeiro? A tela de pareamento tem um passo a passo para o lado do computador, com o comando de instalação para compartilhar.

Testando num simulador: remote-harness start --dev prende o daemon a 127.0.0.1 (e nunca usa relay) e remote-harness pair imprime um código com esse endereço: cole o link na aba Colar link do app. No emulador Android rode também adb reverse tcp:7337 tcp:7337.

Primeira sessão

Rode o seu alias em vez de claude, com os mesmos argumentos:

pessoal             # abre o Claude Code no tmux com aquela conta
trabalho --resume   # outra conta

As duas aparecem no app, totalmente controláveis. Sessões abertas com claude puro fora do tmux também aparecem, somente leitura, e podem ser retomadas pelo celular.

Atualizar

remote-harness update baixa a nova versão, recompila, atualiza os hooks e reinicia o serviço sem as perguntas da instalação. O serviço em segundo plano também procura atualizações a cada 6 horas e mostra uma notificação na área de trabalho; veja atualizações e canais.