O daemon
Vale para 0.7+
O daemon roda no computador: acompanha os transcripts das sessões, controla o tmux, recebe os hooks do Claude Code em 127.0.0.1 e atende o app por dois caminhos com a mesma criptografia de ponta a ponta: direto, num WebSocket que escuta em todas as interfaces (a rede de casa, ou qualquer endereço de VPN do computador), e pelo seu relay de conexão, onde mantém uma sala aberta. remote-harness --help é a fonte da verdade para os comandos.
Comandos
| Comando | O que faz |
|---|---|
remote-harness setup |
Instalação guiada: contas e aliases, hooks, serviço, pareamento. --yes mantém a configuração, --lang escolhe o idioma. |
remote-harness start |
Roda o daemon em primeiro plano. --dev prende só a 127.0.0.1 e nunca usa relay, --host define o endereço direto. |
remote-harness pair |
Pede ao daemon em execução um QR code de pareamento: ele pareia um celular e expira em 5 minutos. |
remote-harness doctor |
Confere as ferramentas, a configuração, os perfis e as chaves de provedor, a identidade do daemon, se os relays de conexão respondem, o serviço, o push e os celulares registrados. |
remote-harness install / uninstall |
Instala ou remove os atalhos, a entrada no PATH, os hooks e o wrapper da status line, sem perguntas. |
remote-harness service install / uninstall / status |
O serviço em segundo plano: um LaunchAgent do launchd no macOS, uma unidade de usuário do systemd no Linux e no WSL. |
remote-harness update |
Baixa a nova versão, recompila, atualiza os hooks e reinicia o serviço. `--ref <branch |
remote-harness updates status / check / `channel [main |
development]/auto on |
remote-harness push status / test |
Modo de push em uso e celulares registrados; envia uma notificação de teste. |
remote-harness push off / on |
Para (ou volta a enviar) todos os pushes e o status ao vivo deste computador, sem reiniciar o daemon. |
remote-harness provider key <perfil> |
Guarda a chave do provedor (OpenRouter) de um perfil no cofre do sistema. --stdin lê de um pipe. |
remote-harness devices list / revoke <id> |
Os celulares e tablets pareados com este computador (ID, nome, plataforma, pareado em, visto por último); revoke desconecta um, que precisa parear de novo. |
remote-harness rules list / undo <id> |
As regras "permitir sempre" criadas pelo celular. |
remote-harness approvals list |
O registro de aprovações: o que os aparelhos permitiram, negaram, desfizeram e apagaram (últimos 30 dias). |
| `remote-harness commands [on | off]` |
O comando antigo claude-remote e as variáveis CLAUDE_REMOTE_* continuam funcionando em instalações feitas antes da mudança de nome.
Arquivo de configuração
~/.remote-harness/config.json (uma instalação anterior à mudança de nome é movida para lá pelo próximo remote-harness update, e ~/.claude-remote vira um link para ela):
{
"profiles": [
{ "id": "pessoal", "name": "Pessoal", "configDir": "~/.claude", "color": "#D97757" },
{ "id": "trabalho", "name": "Trabalho", "configDir": "~/.claude-work", "color": "#61AFEF" }
],
"wsPort": 7337,
"hookPort": 7338,
"defaultRuleScope": "project",
"permissionTimeoutSec": 280,
"questionTimeoutSec": 3300,
"inputStrategy": "paste",
"recentDays": 7,
"tmuxSession": "claude-remote",
"tmuxSocket": "remote-harness",
"tmuxConfig": "minimal",
"push": "auto",
"update": { "channel": "main", "auto": false },
"tray": true,
"relays": ["wss://us.relay.remoteharness.app", "wss://br.relay.remoteharness.app"],
"relay": "on",
"direct": "on"
}
profiles: um por conta do Claude Code.idé o alias (o nome do atalho),configDiroCLAUDE_CONFIG_DIRda conta,colora cor da etiqueta no app. Opcionais:agent(claudepor padrão) eprovider(abaixo).wsPort,hookPort: as portas do app e dos hooks.defaultRuleScope: para onde vão as regras "permitir sempre" por padrão,projectouuser.permissionTimeoutSec: quanto tempo o daemon segura um pedido de permissão para o celular antes de o diálogo do terminal assumir. O pedido continua no app como "Responda no terminal" até a sessão seguir.questionTimeoutSec: o mesmo para perguntas e aprovação de plano (3300 por padrão). Uma pergunta ainda aberta depois de 10 minutos manda um push de lembrete. O timeout do hook gravado nas configurações do agente cobre os dois, eremote-harness installouupdateo reescreve.inputStrategy:paste(padrão) outypepara os prompts enviados pelo celular.recentDays: até quando sessões encerradas são listadas.tmuxSession: a sessão do tmux que os atalhos usam.tmuxSocket: o servidor tmux (tmux -L <nome>) que os atalhos e o daemon usam,remote-harnesspor padrão, separado do seu tmux e do seutmux.conf;nullusa o seu servidor padrão e a sua configuração.tmuxConfig:minimal(padrão) inicia esse servidor só com os poucos ajustes do Remote Harness (Esc entregue na hora, eventos de foco, histórico maior);usercarrega também o seu~/.tmux.conf(ou~/.config/tmux/tmux.conf) por cima, para os seus atalhos valerem dentro das janelas do agente.language:pt-BR,en-USoues-ESpara a CLI, a instalação e os textos de push; o idioma do sistema quando ausente.push:auto(a sua conta de serviço do Firebase quando existe, senão o relay) ouoff.update: o canal queupdatee a verificação seguem, e se as atualizações se aplicam sozinhas.tray: o ícone na barra de menus / bandeja.relays: os relays de conexão que o daemon pode usar. Ao iniciar ele mede todos e mantém a sala no mais rápido, trocando só quando ele cai; troque a lista para hospedar o seu.relay:offdeixa o daemon fora dos relays (os celulares só o alcançam direto).direct:offpara de escutar conexões diretas (só o relay). Não os dois.start --devnunca usa relay.trayPermissions: se a bandeja oferece Permitir / Sempre permitir / Negar para uma permissão pendente (ligado por padrão; também nas Preferências da bandeja).shellCommands:enabled(desligado por padrão; mude comremote-harness commands on|off),timeoutSec(300) emaxOutputKb(1024) para os comandos rodados pelo app.
Mudanças no arquivo valem quando o daemon reinicia (remote-harness service install de novo, ou reiniciar pela bandeja).
Perfis e OpenRouter
Um perfil pode rotear o Claude Code pelo OpenRouter em vez da conta Anthropic. O jeito mais fácil é remote-harness setup → "Adicionar um perfil OpenRouter": ele pergunta o nome, o alias, a pasta (~/.claude-openrouter), um modelo padrão opcional e a chave (oculta), confere a chave com o OpenRouter e mostra os créditos restantes quando a chave consegue lê-los. Rodar o setup de novo lista esses perfis e deixa manter, trocar a chave ou remover o perfil (o atalho, os hooks e a chave; a pasta fica).
À mão: acrescente um provider com kind: "openrouter" e, opcionalmente, baseUrl (outro gateway compatível com a Anthropic), um model padrão e um smallFastModel.
{
"id": "openrouter",
"name": "OpenRouter",
"configDir": "~/.claude-openrouter",
"color": "#8A8784",
"provider": { "kind": "openrouter", "model": "anthropic/claude-sonnet-5.5" }
}
Depois, remote-harness install regenera os atalhos e remote-harness provider key openrouter guarda a chave no mesmo cofre das chaves do próprio daemon (Keychain no macOS, Secret Service ou arquivo 0600 no Linux). O atalho lê a chave só dentro da janela do tmux, nunca numa linha de comando, e o daemon só a usa para mostrar os seus créditos no app. O doctor informa se cada perfil com provedor tem chave.
Perfis do Codex
Um perfil pode rodar o OpenAI Codex CLI em vez do Claude Code: defina "agent": "codex" e aponte configDir para a pasta do Codex (CODEX_HOME, ~/.codex por padrão). O remote-harness setup oferece ~/.codex quando o Codex já o usou.
{ "id": "cdx", "name": "Codex", "configDir": "~/.codex", "color": "#2FBF8F", "agent": "codex" }
O remote-harness install grava o atalho do perfil (ele abre o codex com o CODEX_HOME certo) e mescla os hooks do daemon em <CODEX_HOME>/hooks.json, ao lado dos seus e com backup; o seu config.toml não é alterado. O Codex pede uma vez para confiar em hooks novos: abra o codex e escolha "Trust all and continue" (ou revise em /hooks). Até lá, as sessões dele aparecem somente leitura e as aprovações ficam no terminal. O doctor verifica se o codex está no PATH e se os hooks estão instalados.
O que funciona como no Claude Code: a lista de sessões (rollouts recentes em sessions/), a conversa, prompts, fotos e teclas, iniciar e retomar pelo celular (num worktree com codex --worktree, e com nome, enviado como /rename), push, status ao vivo, aprovações com Permitir / Negar, Aprimorar ditado e mensagens de commit geradas (via codex exec). Diferenças: o chip de modo mostra o perfil de permissões e alterna entre somente leitura e workspace (/permissions, Codex 0.164 ou mais novo); acesso total só no terminal. Não há "Sempre" (hooks do Codex não criam regras) nem provedor.
Perfis do Gemini CLI
Um perfil pode rodar o Gemini CLI do Google: defina "agent": "gemini" e aponte o configDir para uma pasta de configuração do Gemini, que sempre se chama .gemini (~/.gemini por padrão; para outra, ~/work/.gemini, o atalho define GEMINI_CLI_HOME=~/work). O remote-harness setup oferece a ~/.gemini quando o Gemini CLI já a usou.
{ "id": "gem", "name": "Gemini", "configDir": "~/.gemini", "color": "#E3729E", "agent": "gemini" }
O remote-harness install grava o atalho do perfil (ele abre o gemini) e mescla os hooks do daemon no <configDir>/settings.json, ao lado dos seus hooks e configurações e com backup. O Gemini CLI não roda hooks numa pasta em que ele não confia: quando o gemini perguntar, confie na pasta (ou use /permissions). Até lá, as sessões dele nessa pasta aparecem somente leitura e as aprovações ficam no terminal. O doctor confere se o gemini está no PATH e se os hooks estão instalados.
O que funciona como no Claude Code: a lista de sessões (arquivos de sessão recentes em tmp/), a conversa (comandos de shell, edições e buscas em arquivos aparecem como os do Claude Code), prompts, fotos e teclas, iniciar e retomar pelo celular, push e status ao vivo. Aprovações: os hooks do Gemini CLI não conseguem aprovar uma ferramenta, então quando o diálogo de aprovação dele abre o celular recebe Permitir / Negar e o daemon aperta as teclas do próprio diálogo no terminal ("Allow once" ou Esc); se o diálogo já foi respondido lá, o app avisa. Diferenças: sem "Sempre", sem troca de modo (e nunca YOLO), sem worktree nem nome ao iniciar, sem ditado com Polish nem mensagens geradas, e sem provedor.
Perfis do Kimi CLI
Um perfil pode rodar o Kimi CLI da Moonshot: defina "agent": "kimi" e aponte o configDir para a pasta de dados do Kimi (KIMI_SHARE_DIR, ~/.kimi por padrão). O remote-harness setup oferece a ~/.kimi quando o Kimi CLI já a usou.
{ "id": "km", "name": "Kimi", "configDir": "~/.kimi", "color": "#5B9BF5", "agent": "kimi" }
O remote-harness install grava o atalho do perfil (ele abre o kimi com o KIMI_SHARE_DIR certo) e adiciona os hooks do daemon ao <configDir>/config.toml como tabelas [[hooks]], no fim e com backup; todas as outras linhas do arquivo ficam como estão. Se o seu config.toml define hooks = [...] como uma chave só, o install não mexe nele e o doctor mostra os hooks como ausentes: troque por tabelas [[hooks]] antes. O doctor confere se o kimi está no PATH e se os hooks estão instalados.
O que funciona como no Claude Code: a lista de sessões (sessões recentes em sessions/), a conversa (comandos de shell, edições e buscas em arquivos aparecem como os do Claude Code), prompts, fotos e teclas, iniciar e retomar pelo celular, push e status ao vivo. Aprovações: o Kimi CLI não tem hook para elas, então enquanto uma sessão do Kimi roda o daemon olha o painel do tmux dela a cada segundo; quando o painel de aprovação aparece, o celular recebe Permitir / Negar e o daemon aperta as teclas do próprio painel ("Approve once" ou "Reject"). Se você responder no terminal, o pedido some sozinho. Diferenças: sem "Sempre" (nem "aprovar nesta sessão"), sem modo plano, yolo ou afk pelo app, sem worktree nem nome ao iniciar, sem ditado com Polish nem mensagens geradas, e sem provedor. Um turno cancelado com Esc continua "rodando" no app até o próximo prompt.
Perfis do Qwen Code
Um perfil pode rodar o Qwen Code: defina "agent": "qwen" e aponte o configDir para a pasta de configuração do Qwen (QWEN_HOME, ~/.qwen por padrão). O remote-harness setup oferece a ~/.qwen quando o Qwen Code já a usou.
{ "id": "qw", "name": "Qwen Code", "configDir": "~/.qwen", "color": "#8C6CF5", "agent": "qwen" }
O remote-harness install grava o atalho do perfil (ele abre o qwen com o QWEN_HOME certo) e mescla os hooks do daemon no <configDir>/settings.json, ao lado dos seus hooks e configurações e com backup. O doctor confere se o qwen está no PATH e se os hooks estão instalados.
O que funciona como no Claude Code: a lista de sessões (transcripts recentes em projects/), a conversa (comandos de shell, edições e buscas em arquivos aparecem como os do Claude Code), prompts, fotos e teclas, iniciar e retomar pelo celular, push, status ao vivo e aprovações com Permitir / Negar pelo próprio hook de permissão do Qwen. Diferenças: sem "Sempre", sem troca de modo de aprovação (e nunca auto nem YOLO), sem worktree nem nome ao iniciar, sem ditado com Polish nem mensagens geradas, e sem provedor. Um QWEN_RUNTIME_DIR personalizado ainda não é suportado.
Atalhos e aliases
Cada perfil ganha um pequeno atalho em zsh em ~/.remote-harness/bin/<alias> (adicionado ao PATH em ~/.zshrc e ~/.bashrc). Rode o alias em vez de claude, com os mesmos argumentos: ele abre o Claude Code numa janela da sessão claude-remote no servidor tmux próprio do Remote Harness (tmux -L remote-harness, iniciado com ~/.remote-harness/tmux.conf em vez do seu tmux.conf, então as suas configurações, plugins e o seu tmux ls ficam em paz) com o CLAUDE_CONFIG_DIR certo e prende o seu terminal nela. Rode o alias dentro do seu próprio tmux e a sessão aparece aninhada naquele pane, sem tomar o seu cliente (aperte o prefixo duas vezes para falar com o tmux de dentro). remote-harness tmux anexa a esse servidor de qualquer terminal e remote-harness tmux ls lista as sessões dele; sessões iniciadas antes desse servidor existir continuam no seu tmux padrão até terminarem. O comando claude puro nunca é alterado.
Serviço em segundo plano
remote-harness service install mantém o daemon rodando depois que você fecha o terminal e o inicia no login: um LaunchAgent no macOS (aparece como item de login), uma unidade de usuário do systemd no Linux (~/.config/systemd/user/remote-harness.service). Em servidores Linux acessados por SSH, a instalação oferece loginctl enable-linger, para o serviço sobreviver ao logout; Servidor na nuvem explica como rodar o daemon numa VM na nuvem. Sem systemd (contêineres, alguns WSL) rode remote-harness start você mesmo, por exemplo numa janela do tmux. No WSL a instalação também pode criar uma tarefa agendada do Windows que inicia a distribuição no logon.
remote-harness service status mostra se está carregado; o menu da bandeja reinicia.
Atualizações e canais
O serviço confere o canal dele no remoto git a cada 6 horas e mostra uma notificação na área de trabalho quando há versão nova (nunca num clone de desenvolvimento). remote-harness update aplica; remote-harness updates auto on deixa o daemon se atualizar sozinho, só quando nenhuma sessão está rodando ou esperando e nenhuma permissão está pendente, e nunca para uma versão mais antiga. remote-harness updates channel development segue a branch de integração; voltar para main avisa que instala uma versão mais antiga.
Ícone na bandeja
O daemon do serviço mostra um ícone na barra de menus do macOS (um pequeno auxiliar em Swift compilado no primeiro início com as Command Line Tools) e um ícone na bandeja do Linux (python3 com GTK 3 e AyatanaAppIndicator3 ou AppIndicator3). O menu mostra as sessões em andamento e as permissões pendentes (responda por ali), abre uma sessão nova, mostra o código de pareamento, confere ou aplica atualizações, escolhe o canal, abre os logs, a configuração e a documentação, e reinicia o daemon. Parear um celular mostra o QR de pareamento no próprio menu no macOS, o endereço e o pareamento no terminal; cada código é de uso único e expira em 5 minutos. Preferências liga e desliga as respostas de permissão no menu, o modo de manter acordado e as notificações push, aplicados na hora, e abre o arquivo de configuração para o resto. Com o serviço, Sair esconde o ícone ou para o serviço até o próximo login. "tray": false desliga; sem o auxiliar, o daemon roda sem interface. No WSL o ícone aparece na área de notificação do Windows: o daemon inicia um pequeno auxiliar no lado do Windows via interop (o Windows PowerShell o compila na hora; nada é instalado no Windows), então ele aparece no login com a tarefa de logon e some quando o daemon para. Tem o mesmo menu da bandeja do Linux, as notificações de atualização viram notificações do Windows e as ações que abrem um terminal usam o Windows Terminal.
No macOS o ícone abre um popover em vez de um menu: o computador com seus caminhos (direto e/ou pelo relay, nunca um endereço), a permissão pendente como um cartão com Negar / Sempre / Permitir, até cinco sessões (clique para abrir uma no terminal, clique direito para renomear ou fechar), os dispositivos pareados e se estão online, e as ações rápidas. A janela de Preferências tem as abas Geral, Perfis (renomeie um perfil), Notificações, Rede (os endereços do caminho direto, o relay de conexão e o relay principal, os dispositivos conectados agora), Dispositivos (cada dispositivo pareado, com Revogar…), Pareamento, Atualizações e Avançado. No Linux o menu segue a mesma ordem, e cada dispositivo tem um submenu Revogar….
Hospedar o próprio relay de conexão
Quando o celular não alcança o computador diretamente, o daemon e o app se encontram num relay de conexão: us.relay.remoteharness.app e br.relay.remoteharness.app por padrão. O relay só repassa o tráfego que o daemon e o app criptografam de ponta a ponta; ele não consegue ler sessões, prompts nem arquivos, e não guarda log do que passa nem de endereços IP. Rodar o seu é um contêiner:
docker build -t remote-harness-relay apps/relay
docker run -d --restart unless-stopped -p 8080:8080 remote-harness-relay
Coloque-o atrás de um proxy que termine o TLS (Traefik, Caddy, nginx), para ser acessado por wss://, e defina RELAY_CLIENT_IP_HEADER com o cabeçalho em que o proxy põe o endereço do cliente (X-Real-Ip, por exemplo), para que os limites por endereço vejam o cliente real. GET /healthz responde {"status":"ok"}. Os limites vêm do ambiente: RELAY_MAX_DEVICES (10 celulares por computador), RELAY_MAX_FRAME_BYTES (8 MB), RELAY_ROOM_RATE_BYTES e RELAY_ROOM_BURST_BYTES (banda por computador), RELAY_IDLE_TIMEOUT, RELAY_IP_CONNECTS_PER_MINUTE, RELAY_IP_BURST e RELAY_IP_MAX_CONNS.
Depois liste-o no arquivo de configuração do daemon, no lugar dos relays padrão ou antes deles:
{ "relays": ["wss://relay.example.com"] }
Pareie o celular de novo em seguida: o código de pareamento diz ao app qual relay usar.
Dados e logs
Tudo o que o daemon guarda fica em ~/.remote-harness/: config.json, state.json (as sessões conhecidas), secrets/ (chaves de provedor quando o cofre é o arquivo), models-cache.json, bin/ (atalhos), logs/ e src/ (o código que o instalador compilou). Anexe os logs a um relato de bug depois de remover tokens e conteúdo de sessões.
Variáveis de ambiente: REMOTE_HARNESS_HOME muda a pasta de dados, REMOTE_HARNESS_TOKEN_STORE=keychain|secret-tool|file força o cofre de segredos (as chaves do daemon e as de provedor), REMOTE_HARNESS_LANG define o idioma.