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),zsheclaude(oucodex,gemini,kimi,qwen) noPATH. O instalador adiciona as ferramentas que faltam. - Node 24+. O instalador baixa um Node privado para
~/.remote-harness/nodequando 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
PATHe 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 iosroda no simulador ou num aparelho conectado;make install-iosfaz 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 androidepnpm build:androida 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:
- 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.
- Mande-o em particular para o mantenedor, pelo contato em maarkn.dev, não numa issue pública.
- 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.