Acesso remoto e MCP

borg mcp permite que um agente de IA como o Claude trabalhe no borg que tem aberto, seja no seu próprio computador, seja num servidor a que acede por SSH. Não precisa de instalar mais nada além do borg: o agente inicia borg mcp por si (através de SSH, no caso de um servidor) e este liga-se à sessão do borg que está a correr nessa máquina. O servidor não precisa de portas abertas nem de acesso à internet.

Ligar o Claude

Prima F1 e depois C (ou escolha F9 → Remoto → Partilhar este Borg como host…). O Borg mostra dois comandos para colar num terminal do seu computador: um inicia o Claude Code já ligado a este borg; o outro acrescenta a ligação ao Claude Code para todas as sessões. Tab escolhe um deles e Enter copia-o para a área de transferência do computador através do terminal. Isto funciona por SSH no iTerm2, Ghostty, kitty, WezTerm e Alacritty (no tmux, acrescente set -g set-clipboard on). Quando o terminal não o aceita, como acontece em muitos terminais de browser, F3 mostra o comando isolado em texto simples, para o poder selecionar com o rato; qualquer tecla volta ao borg.

Por SSH, o borg preenche o endereço a que se ligou. Se o seu computador chegar ao servidor por outro nome, como um alias de SSH ou através de um jump host, escreva antes esse nome. O SSH tem de iniciar sessão sem pedir palavra-passe, com uma chave ou um agente SSH. borg mcp setup prod mostra na linha de comando a mesma configuração para o Claude Code e o Claude Desktop.

O que o agente pode fazer

Depois de ligado, o agente vê o mesmo que o utilizador: o próprio ecrã em texto, quer esteja nos painéis quer na consola, os dois painéis, os ficheiros realçados e marcados, onde corre a linha de comando e o que está escrito nela. Refere-se a sítios como localizações: um caminho absoluto ou ~/… na máquina onde o borg corre, docker://web/etc/nginx dentro de um contentor, ou um caminho relativo ao painel ativo. Sem pedir autorização, pode ler pastas e ficheiros (por intervalo de linhas, ou apenas as linhas que contêm determinado texto), ver os processos mais ativos e os contentores, e mostrar um ficheiro ou uma pasta no seu outro painel. Também pode listar as portas abertas, as ligações e as interfaces de rede com o respetivo tráfego, medido durante um segundo e filtrado com as mesmas palavras que o filtro do ecrã de rede (consulte Filtrar). Também pode listar os itens de arranque, com a alteração mais recente primeiro, com os seus programas e as regras a que corresponderam, filtrados com as mesmas palavras que o filtro desse ecrã (consulte Itens de arranque).

Tudo o que altera a máquina fica à sua espera numa caixa de diálogo que mostra a alteração completa: um comando e o sítio onde vai ser executado, um ficheiro novo ou uma edição sob a forma de diff. Percorra as alterações longas com as setas, PgUp e PgDn ou a roda do rato, e prima F3 para ver a caixa de diálogo em ecrã inteiro. A opção Não mantém-se selecionada até escolher Sim, e a caixa de diálogo ignora o Sim durante o primeiro meio segundo, para que uma tecla ou um clique destinados a outra coisa não a possam aprovar. Uma edição é recusada se o ficheiro tiver mudado enquanto decidia. Um comando com tabulações, sequências de escape ou outros caracteres de controlo também é recusado, porque a caixa de diálogo não os consegue mostrar. A caixa de diálogo aparece por cima de tudo, incluindo o editor, o visualizador, outra caixa de diálogo e o protetor de ecrã, e recebe todas as teclas até responder. O que ela tapava volta a aparecer depois. Se o agente deixar de esperar antes disso, a caixa de diálogo fecha-se e um aviso indica-o. Para um computador emparelhado, approval_mode pede-lhe confirmação uma vez antes de ativar Aprovar tudo nessa sessão. Enquanto estiver ativo, fica visível um distintivo; clique nele ou prima Ctrl+Alt+A para o desativar de imediato. Desativa-se também quando essa ligação emparelhada fecha. As aprovações de emparelhamento são independentes.

Um pedido chega também ao seu próprio computador quando um painel remoto aí mostra a sessão em que o pedido espera (consulte Painéis remotos). O seu borg mostra-o no mesmo diálogo, com o nome do servidor no título, por cima do que estiver a fazer, e envia a sua resposta de volta pela ligação cifrada. O servidor mantém também o seu próprio diálogo aberto. Conta a primeira resposta, venha de onde vier, e os outros diálogos fecham com um aviso que diz onde foi respondido. Um pedido que o agente retire fecha em todo o lado. Quando outro computador controla a sessão através de um espelho, o seu diálogo mostra o pedido sem Sim e Não, e Esc fecha-o apenas no seu ecrã. Enquanto essa sessão aprovar tudo, o seu borg mostra um distintivo com o nome do servidor; clique nele ou prima Ctrl+Alt+A para desativar Aprovar tudo lá de imediato. Só as suas teclas e cliques respondem a estes diálogos: as ferramentas do agente, incluindo type, não conseguem premir nada neles.

Os comandos são escritos numa shell que pode acompanhar e ficam fora do respetivo histórico. Os comandos para esta máquina vão para a consola do próprio borg, que é mostrada enquanto correm para poder responder a um pedido como o do sudo; os comandos para um contentor vão para a shell desse contentor na vista Docker. A shell mantém a pasta e as variáveis entre comandos.

O agente também pode escrever texto para o utilizador rever: um comando no prompt, ou um script no vim ou no nano abertos na consola. Nada é executado: Enter nunca é premido, e o texto com várias linhas entra como colagem, que as shells e os editores inserem sem executar.

O agente pode ainda pesquisar a memória de um processo da mesma forma que a pesquisa de memória, à procura de cadeias de caracteres, indicadores, texto ou bytes. A memória pode conter palavras-passe, chaves e mensagens privadas, e tudo o que a pesquisa encontrar vai para o agente; por isso, a primeira pesquisa em cada processo aguarda a sua aprovação numa caixa de diálogo que indica o processo, o programa e a pesquisa. Depois de aprovar, o agente pode voltar a pesquisar e analisar esse processo até o borg terminar. Pode pedir para ler como administrador, o que abre o pedido de palavra-passe do próprio sistema.

O agente também pode analisar com regras YARA e verificar a integridade do código, como fazem Correspondências de regras na caixa de diálogo de Ctrl-F e as teclas Y e I no mapa de memória (consulte Analisar ficheiros com regras, Verificação de integridade do código e Analisar a memória com regras). Um ficheiro ou uma pasta na máquina onde o borg corre é analisado sem perguntar, tal como uma leitura. A análise de uma pasta lê todos os ficheiros abaixo dela no mesmo sistema de ficheiros, incluindo os ocultos. Deixa por ler os ficheiros com mais de 64 MiB e para ao fim de 20 000 ficheiros, 2000 correspondências ou 45 segundos. Os ficheiros em contentores não são analisados.

Com um processo é diferente, porque a análise lê a sua memória. A primeira análise de cada processo aguarda a sua aprovação em Pedido remoto para analisar a memória de um processo, que indica o processo, o programa e as verificações: a verificação de integridade, as regras, ou ambas. Uma aprovação cobre as análises e as pesquisas de memória desse processo até o borg terminar, seja qual for a que o agente pediu primeiro. Cada verificação para ao fim de 45 segundos, 1 GiB de memória ou 2000 resultados. O agente pode pedir para ler como administrador, o que abre o pedido de palavra-passe do próprio sistema uma única vez para as duas verificações.

As regras são as do Borg e as da sua pasta de regras, a não ser que o agente traga o seu próprio texto de regras, até 64 KiB. Assim, pode redigir uma regra a partir do que encontrou, experimentá-la numa pasta ou num processo e afiná-la. Esse texto corre sozinho, sem as regras do Borg nem as suas, não pode usar include e nunca é guardado. O texto que não compila volta para o agente com a mensagem do compilador, antes de qualquer caixa de diálogo. Para um processo, a caixa de diálogo mostra o texto de regras do agente abaixo das verificações, para que veja o que ele procura.

O agente recebe cada resultado, do mais grave para o menos grave, com a gravidade, o tipo, a regra e a sua origem, o ficheiro e o deslocamento ou o endereço e a região de memória, até 64 bytes do que correspondeu, como texto ou em hexadecimal, e o que mais o poderia explicar. Seguem-se quanto foi lido, o que não foi possível ler, se a análise terminou e os ficheiros de regras deixados de fora. As provas vão para o agente tal como foram encontradas, incluindo chaves e tokens, como na pesquisa de memória.

O agente também pode capturar tráfego como a tecla R faz no ecrã de rede (consulte Capturar tráfego). Indica o que gravar: uma porta, uma ligação, um processo pelo PID ou todo o tráfego da interface. Para um processo, o Borg grava a interface inteira e resume as conversas desse processo. Uma captura dura de 1 a 60 segundos, ou 5 se o agente não indicar a duração. Quando o agente não indica a interface, o Borg mede durante um segundo e escolhe a que a caixa de diálogo Capturar tráfego escolheria. Cada captura aguarda a sua aprovação numa caixa de diálogo, Pedido remoto para capturar tráfego, que mostra o tráfego, a interface, a duração, quanto de cada pacote guardar e a pasta. Enquanto decorre, o rodapé mostra-a, e no fim um aviso indica onde o Borg a guardou: na pasta do painel ativo ou numa pasta que o agente indique, legível só por si. A captura de um agente é sempre executada com o seu utilizador e nunca pede a palavra-passe de um administrador, por isso sem acesso termina com Sem permissão para capturar em e o nome da interface.

O agente recebe um resumo: os protocolos que o Borg reconheceu e depois cada processo, host e ligação com os seus pacotes e bytes, com os nomes dos hosts tirados das respostas DNS da própria captura e dos nomes de servidor TLS. O Borg acompanha os sockets enquanto a captura decorre, por isso as conversas ficam atribuídas aos seus processos mesmo com o ecrã de rede fechado. O resumo deixa de fora o que os pacotes transportam. Ler um ficheiro .pcap, .pcapng ou .cap dá o mesmo resumo, restringido com as palavras do filtro do visualizador de tráfego, e o agente pode pedir um pacote pelo número para obter as camadas e os bytes num dump hexadecimal. O Borg lembra-se dos processos das últimas 16 capturas do agente até terminar. Os outros ficheiros mostram as conversas em Processo desconhecido, a menos que os pacotes tragam o seu processo.

Enquanto houver um agente ligado, ◈ Remoto aparece no início da barra de atalhos. Clique nele, ou escolha F9 → Remoto → Registo remoto… a qualquer momento, para ver um registo do que o agente fez: o que viu, leu, analisou, mostrou e escreveu, e todos os comandos e alterações, aprovados ou recusados. Cada sessão guarda o seu registo no disco, legível apenas por si, para que possa voltar a uma sessão que deixou a correr e ver o que aconteceu nela, mesmo depois de o Borg terminar. Quando o registo fica grande, o Borg descarta as entradas mais antigas. Antes de guardar uma entrada, o Borg oculta as palavras-passe, os tokens e as chaves que reconhece, e deixa de fora a saída dos comandos. Uma palavra-passe passada como uma palavra simples parece uma palavra qualquer, por isso o Borg não a consegue ocultar. Para não guardar registo nenhum, desative Remoto: manter um registo do que faz em Opções → Plugins, o que também elimina o registo guardado.

Borg cloud

O borg cloud permite que o Claude chegue a um borg para o qual não tem caminho SSH: um servidor que abre num terminal de browser, um contentor ou uma máquina atrás de NAT. Ambos os lados se ligam a um relay, e o relay junta-os.

1. No borg do servidor, prima F1 e depois C. A primeira opção é borg pair com uma ligação; Enter copia-a. A ligação funciona uma única vez, durante dez minutos. Por baixo fica o relay: para usar outro relay, cole aí o respetivo endereço e prima Enter para o guardar e obter uma ligação através dele.
2. Execute o comando num terminal do seu computador, onde o borg também esteja instalado. É apresentado um código de emparelhamento: seis emojis, cada um com o seu nome, como 🐱 Cat · 🦁 Lion · 🐎 Horse.
3. O borg do servidor pergunta se quer emparelhar, mostrando o nome do seu computador e o código. A pergunta aparece de imediato, mesmo enquanto F3 mostra o comando em texto simples. Escolha Sim se os códigos coincidirem. Em seguida, borg pair propõe acrescentar o servidor ao Claude Code, como claude mcp add borg-NAME -- borg mcp remote NAME. Espera 5 minutos pela sua resposta; quando desiste ou o interrompe, a pergunta fecha-se e a ligação deixa de funcionar.

O código deriva do handshake cifrado que os dois borgs acabaram de concluir, pelo que só é igual nos dois ecrãs se for o seu computador a comunicar com o servidor. Alguém que tivesse obtido a ligação e a usasse primeiro mostraria ao servidor um código diferente, e não consegue escolher um que coincida com o seu. Se o terminal desenhar os emojis mais estreitos do que o borg espera, o borg mostra apenas os nomes; nesse caso, compare os nomes.

A partir daí, o Claude pode chegar a esse borg sempre que estiver a correr nessa máquina. borg pair sozinho lista os servidores emparelhados, e borg pair --forget NAME esquece um deles; no servidor, F8 na caixa de diálogo Acesso remoto esquece todos os computadores emparelhados. Através do borg cloud, o Claude obtém também download e upload, que copiam ficheiros entre o servidor e o seu computador; borg get NAME:PATH [TO] e borg put FROM NAME:PATH fazem o mesmo a partir do terminal. As transferências do Claude vão para a pasta Transferências e nunca substituem um ficheiro que já lá esteja. Os envios aguardam a sua aprovação no borg, que mostra o ficheiro enviado, e cada aprovação indica o computador que fez o pedido.

A ligação é cifrada de ponta a ponta. Cada borg guarda uma chave de servidor, pela qual os computadores emparelhados o conhecem, e um computador que chega a servidores guarda também uma chave de computador própria. Só o utilizador pode ler ambas. A chave de servidor é um ficheiro na pasta link da pasta de estado. A chave de computador também é um ficheiro aí. Num Mac fica no porta-chaves de início de sessão, e no Linux o ficheiro é selado com uma palavra-passe (consulte Chaves de computador). O emparelhamento troca as chaves públicas, e cada ligação abre com um handshake Noise IK associado a elas, pelo que o relay só reencaminha texto cifrado e não consegue responder em nome de nenhum dos borgs. Os pedidos vindos de outro computador podem ler sem pedir autorização, tal como os locais; ative “perguntar antes de outro computador ler” em Opções → Plugins para que também essas leituras aguardem aprovação. O Borg não mantém nenhuma ligação ao relay a menos que esteja emparelhado ou a mostrar uma ligação de emparelhamento, e não mantém nenhuma quando o borg cloud está desativado em Opções → Plugins.

O Borg guarda o relay na configuração como relay = "wss://relay.example.com". Um computador chega ao servidor através do relay pelo qual emparelhou, por isso, depois de o servidor mudar de relay, volte a emparelhar o computador. Todos os borgs de uma máquina partilham as chaves, e o serviço em segundo plano liga-os todos ao relay. Com o serviço desativado, só o primeiro borg a ser aberto se liga, e os outros indicam qual deles tem o borg cloud.

Chaves de computador

A chave de computador prova a cada servidor emparelhado que uma ligação vem do seu computador. Quando um servidor ainda conhece este computador por outra chave, como a chave de servidor desta máquina, o Borg muda-o para a chave de computador na próxima vez que abrir uma sessão lá. O Borg prova ao servidor que tem a chave nova, e o servidor troca a chave na entrada desse computador e mantém o nome. As ligações que ainda usam a chave antiga terminam no pedido seguinte. O servidor mostra um aviso e escreve as duas impressões digitais no registo do agente, e a lista Clientes mostra quando a chave mudou e qual era. Um servidor com um Borg mais antigo mantém a chave antiga até ser atualizado.

Num Mac, o Borg guarda a chave de computador no porta-chaves de início de sessão, como um item chamado Borg Commander que só o Borg pode ler sem perguntar. Na primeira vez que um processo do Borg precisa da chave, o macOS pede o Touch ID ou a palavra-passe, por isso até um programa que inicie o borg por conta própria fica à vista. Depois de cada atualização do Borg, o macOS pergunta também uma vez se o novo Borg pode usar o item; escolha Permitir sempre. Um ficheiro de chave de computador de um Borg anterior passa para o porta-chaves na primeira vez que o Borg o usa, e o ficheiro é apagado. Um Borg executado sem o ecrã do Mac, como por SSH ou no serviço em segundo plano, não pode mostrar o pedido nem aceder a servidores. Quando $BORG_STATE_DIR indica uma pasta de estado diferente da habitual, o Borg guarda a chave de computador como ficheiro na pasta link dessa pasta. As versões do Borg para macOS são assinadas com o Hardened Runtime, por isso outros programas não podem ler a memória do Borg nem carregar código nele.

No Linux, o Borg sela a chave de computador com uma palavra-passe à sua escolha, no ficheiro computer-key.sealed da pasta link. Execute borg unlock num terminal para a escolher: o Borg sugere quatro palavras aleatórias, fáceis de escrever e difíceis de adivinhar, e pede a palavra-passe duas vezes. O Borg reforça a palavra-passe com Argon2id, o que demora alguns segundos e usa 1 GiB de memória, ou um oitavo da memória numa máquina com menos de 8 GiB, pelo que adivinhá-la a partir de uma cópia do ficheiro é lento. Um ficheiro de chave de computador de um Borg anterior é selado na primeira vez que executar borg unlock, e o ficheiro é apagado; até lá, o Borg pede que o execute. Quando $BORG_STATE_DIR indica uma pasta de estado diferente da habitual, o Borg também guarda no Linux a chave de computador como ficheiro normal, sem palavra-passe.

Depois de desbloqueada, a chave fica no keyring do kernel do utilizador até passarem 12 horas sem o Borg a usar, e cada utilização volta a contar as 12 horas desde o início. Um reinício bloqueia-a, e borg lock bloqueia-a de imediato. Onde o Borg não pode usar o keyring do kernel, como em muitos contentores e serviços do sistema, um pequeno processo do Borg guarda a chave, num socket da pasta link que só o utilizador pode abrir, e termina após 12 horas sem uso. Quando a chave está bloqueada, o Borg pede a palavra-passe: os painéis abrem o diálogo Desbloquear chave, e borg pair, borg get, borg put e borg mirror pedem-na no terminal. borg mcp remote, que o Claude inicia sem terminal, indica que deve executar borg unlock.

borg unlock --ssh-agent permite também que o ssh-agent desbloqueie a chave. O Borg pede ao agente que assine um desafio fixo com uma chave Ed25519, ou com uma chave RSA se não tiver nenhuma, e sela a chave uma segunda vez com essa assinatura. A partir daí, o Borg desbloqueia a chave sem perguntar enquanto esse agente estiver acessível, e a palavra-passe continua a funcionar. O Borg verifica que o agente assina da mesma forma duas vezes e recusa uma chave cujas assinaturas mudem. Quem puder usar o seu agente consegue obter a mesma assinatura: se o reencaminhar com ssh -A, o root da máquina remota pode usá-lo enquanto estiver ligado e, com uma cópia do ficheiro selado, desbloquear esta chave. Reencaminhe o agente apenas para máquinas de confiança, ou deixe isto desligado. borg unlock --no-ssh-agent volta a desligá-lo.

borg pair --new-key dá a este computador uma chave nova, e cada servidor aceita-a na próxima vez que o Borg se ligar a ele. Até todos a terem, o Borg guarda também a chave antiga, e borg pair assinala cada servidor que ainda a aceita. Uma semana depois, sugere também esquecer os servidores que já não usa, com borg pair --forget NAME.

Quando um servidor recusa todas as chaves que este computador tem, o Borg indica-o. Ou alguém esqueceu este computador nesse servidor, ou alguém com uma cópia da chave mudou primeiro o servidor para uma chave sua. Uma chave nova é higiene e não desfaz uma fuga. Se suspeitar que alguém copiou uma chave, prima F8 em Acesso remoto em cada servidor para esquecer os computadores emparelhados, emparelhe de novo e verifique esses servidores.

Sessões com nome e serviço em segundo plano

Com espaços de trabalho com nome, borg sessions list mostra os respetivos IDs e nomes, borg sessions create NAME acrescenta um e borg --session NAME abre-o. Através de MCP, o agente pode chamar list_sessions, list_remote_sessions e use_session para escolher a sessão com que essa ligação trabalha. Uma única chamada de ferramenta pode também passar um ID em session para visar outra sessão apenas dessa vez. A sessão escolhida aplica-se apenas a essa ligação MCP.

Com mais de uma sessão, ou quando a única que existe está aberta noutro terminal, o borg começa pela janela Sessões do Borg. As primeiras linhas explicam o que é uma sessão, e a lista mostra cada sessão com a data em que foi usada pela última vez. Uma sessão ativa neste momento aparece marcada com o seu estado: Aberta noutro terminal, ou Mantida pelo serviço quando o serviço em segundo plano a executa. Fica escolhida a sessão usada por último, a menos que outro terminal a tenha aberta. Enter abre a sessão escolhida onde a deixou; uma sessão que o serviço mantém abre-se ligada a ele, como com borg service attach NAME. Um clique escolhe uma sessão e um segundo clique abre-a. F7 dá nome a uma nova sessão e abre-a, e Esc ou F10 sai sem abrir nenhuma. Enquanto a janela está aberta, verifica a cada 2 segundos que sessões estão ativas.

F8 ou Delete remove a sessão escolhida, depois de uma confirmação que tem Não por omissão. Isto elimina os painéis guardados e o histórico de terminal da sessão; os seus ficheiros e pastas mantêm-se. A sessão Default fica sempre, tal como uma sessão ativa neste momento: saia primeiro do Borg no outro terminal. Para remover uma sessão que o serviço mantém, abra-a com borg service attach NAME e saia com F10.

Quando indica com borg --session NAME uma sessão que outro Borg tem aberta num terminal, o borg para e identifica esse Borg: o número do processo, o terminal tal como o ps o mostra e há quanto tempo arrancou. Saia desse Borg com F10 no sítio onde está a correr. Se já não conseguir chegar ao terminal dele, termine-o com kill e o número do processo.

Todos os seus Borgs numa máquina partilham um serviço em segundo plano. O primeiro borg que abrir inicia-o, sem nada para instalar, e o serviço para 30 segundos depois de fechar a última sessão. Para desativar isto, defina start-service = false na configuração.

O serviço mantém o borg cloud ligado para todos os seus Borgs, por isso um computador emparelhado chega a todas as sessões abertas. Trabalha na sessão que indica, ou na que usou por último, e aguarda aí a sua aprovação. Pode emparelhar a partir de qualquer Borg.

Para manter uma sessão em execução sem terminal, execute borg service keep NAME. Abra-a com borg service attach NAME ou a partir da janela Sessões do Borg, e prima Ctrl-] para se desligar. Sair do Borg aí com F10 termina a sessão. Quando um computador emparelhado pede uma sessão que não está em execução, o serviço inicia-a em segundo plano.

Para iniciar o serviço com a máquina, execute borg service install, enable e start. Estes comandos usam o sudo, que pede a sua palavra-passe, a menos que seja root. borg service stop, disable e uninstall desfazem-nos. Também pode escolher F9 → Remoto → Serviço em segundo plano…: a caixa de diálogo mostra o comando do passo seguinte, e Enter executa-o na shell do Borg. Num contentor sem systemd, configure o supervisor de processos do contentor para executar borg service run.

Atualizar com sessões abertas

borg update instala a nova versão, passa o serviço em segundo plano para ela e avisa quando o serviço já a corre. O serviço arranca de novo no seu próprio processo, por isso as sessões que mantém conservam as suas shells e os programas que nelas correm. Cada Borg aberto acompanha-o quando está inativo: espera que as tarefas em curso terminem, que os ficheiros editados sejam guardados ou fechados e que o pedido do agente esteja concluído. Depois arranca de novo no mesmo terminal, mantém a sua shell e indica a versão que corre agora.

A atualização guarda a versão que substituiu junto do ficheiro do programa, como .borg.previous. Se a nova versão não assumir o lugar da anterior em 60 segundos, o Borg repõe a anterior e o serviço volta a arrancar com ela. As sessões que mantinha arrancam então com shells novas.

Um serviço iniciado por um Borg mais antigo não consegue mudar sozinho de versão. O borg update indica-o, e o serviço usa a nova versão da próxima vez que arrancar.

Para atualizar uma máquina emparelhada, selecione-a em Hosts remotos e prima U. Depois de confirmar, o host obtém a versão mais recente tal como o borg update faz, e o seu serviço passa para ela. Esc fecha o seletor enquanto a atualização continua. Em seguida, o Borg indica a versão que o host corre, ou que a nova versão não arrancou e o host voltou à que corria. Um espelho de uma das suas sessões espera por ele e volta a mostrar o host quando este regressa (consulte Espelhar uma sessão). Execute antes borg update no host quando o seu Borg for mais antigo ou correr sem o serviço em segundo plano. Um Borg instalado aí com o Homebrew ou o cargo atualiza-se com essa ferramenta no host, e o Borg indica o comando.

Painéis remotos

Depois do emparelhamento, borg --remote MACHINE:SESSION abre os ficheiros dessa sessão no painel esquerdo. Enter ou F3 pré-visualiza um ficheiro remoto transferindo uma cópia local temporária. F5 copia ficheiros e pastas marcados entre painéis locais e remotos, ou entre dois hosts emparelhados, e a caixa de diálogo de destino indica que cliente ou host está de cada lado. As cópias correm como tarefas em segundo plano, com progresso em bytes, pausa e cancelamento, e a opção de substituir, ignorar ou manter ambos. As pastas são copiadas com as subpastas vazias e as ligações simbólicas, e os ficheiros normais mantêm a permissão de execução e a data de modificação. Um ficheiro só aparece no destino depois de todo o seu conteúdo ter chegado. F6 (mover) e F8 (eliminar) não estão disponíveis em painéis remotos.

O painel direito fica no seu computador. Com Opções → Plugins → Seguir ativo, a linha de comando e Ctrl-O usam uma shell interativa no host remoto. O terminal é desenhado localmente, enquanto as teclas, as colagens, Ctrl-C e os programas de terminal correm no host remoto. Cada sessão remota mantém a sua shell e a linha de comando por terminar enquanto muda de painel, e selecionar um painel do cliente traz de volta a shell local.

Os programas de ecrã inteiro, e os que leem diretamente o teclado, como top, recebem todas as teclas enquanto correm, incluindo Ctrl-O, e redimensionar o terminal redimensiona o PTY remoto. Saia desses programas com as respetivas teclas (q no top). Se o tiver iniciado a partir da linha de comando do painel, o Borg volta depois aos painéis; se o tiver iniciado na consola remota, a consola fica aberta. Os painéis e a shell do próprio Borg remoto são independentes desta consola. Para transferir ficheiros a partir da linha de comando, use borg get MACHINE/SESSION:PATH [TO] e borg put FROM MACHINE/SESSION:PATH.

Escrever exit na shell principal Bash, Zsh ou Fish do Borg pede confirmação. Não está selecionado por omissão e mantém em execução a mesma shell, as variáveis, a pasta e os espelhos. Numa consola remota, exit pergunta se quer fechar a shell no host; depois de Sim, escolha de novo a sessão com Alt-H para obter uma nova.

As pastas remotas carregam por partes, com um indicador de atividade e a contagem das entradas recebidas até ao momento; mudar para outra pasta cancela o pedido.

Enquanto um painel remoto mostra uma sessão, os pedidos do agente que aí esperam aparecem também no seu ecrã, e pode responder-lhes aqui (consulte O que o agente pode fazer).

Hosts remotos

No Borg local, prima Alt-H, clique em Hosts remotos na barra de atalhos ou escolha F9 → Remoto → Explorar hosts e sessões… para ver as máquinas emparelhadas e as respetivas sessões com nome. Enter abre os ficheiros da sessão selecionada no painel a partir do qual abriu o seletor, substituindo o que esse painel mostrava. Prima M para espelhar o ecrã da sessão, U para atualizar o host (consulte Atualizar com sessões abertas) e R para atualizar a lista.

Tab alterna entre Hosts (computadores a que este Borg chega) e Clientes (computadores que chegam a este Borg). Clientes lista os computadores emparelhados com este Borg, as impressões digitais das respetivas chaves públicas, se estão ligados e quantas ligações tem cada um. Depois de um computador mudar de chave, a linha da impressão digital indica também em que dia e a impressão digital que tinha antes. Um computador aparece uma só vez, mesmo que um espelho use várias ligações. O estado é atualizado enquanto o seletor está aberto, incluindo numa sessão cujas ligações são mantidas pelo serviço em segundo plano. O emparelhamento funciona num único sentido: um cliente autorizado não passa automaticamente a ser um host cujos ficheiros este Borg possa explorar. Quando quem detém a ligação não consegue indicar o estado da ligação, os clientes emparelhados continuam a ser listados, com Estado da ligação indisponível. O mesmo Borg pode ser host e cliente ao mesmo tempo. O menu Remoto oferece também Espelhar host montado, Partilhar este Borg como host…, Registo remoto… e Serviço em segundo plano….

O seletor mostra a versão do Borg de cada host. Selecionar uma sessão mostra o sistema operativo e a arquitetura, se corre como serviço em segundo plano ou num terminal, a latência dos pedidos e o endereço do relay. Os hosts são verificados em paralelo, pelo que um host indisponível não atrasa os outros. Um host que não consiga indicar a versão mostra versão indisponível; a versão do relay não é a do host. Mantenha o Borg atualizado nos dois computadores: um host a que falte uma funcionalidade remota mostra uma mensagem a pedir que o atualize.

Enquanto um espelho se liga, o seletor mostra um estado animado, e Esc cancela de imediato. Cada passo da ligação tem 10 segundos, e a tentativa completa tem 30. Se a tentativa falhar, o seletor fica aberto e indica o passo que falhou; M volta a tentar a sessão selecionada.

No seletor, F2 muda o nome do host selecionado para todas as suas sessões, e Shift-F2 muda o nome da sessão selecionada. Estes nomes ficam guardados neste cliente e aparecem no seletor, nos títulos dos painéis e no rodapé da consola. Deixe um nome vazio para voltar ao original. Os detalhes continuam a mostrar os nomes originais do host e da sessão. Os nomes ficam associados à chave do host emparelhado e ao ID da sessão; os destinos dos comandos e os nomes no host remoto não mudam.

F8 num host indisponível esquece o respetivo emparelhamento neste cliente, e Shift-F8 esquece o host selecionado mesmo que esteja online. A confirmação tem Não por omissão. Esquecer um host fecha os painéis e as consolas deste cliente ligados a ele; as sessões e os ficheiros do host mantêm-se, tal como a identidade deste cliente e os seus outros emparelhamentos. Volte a emparelhar para restabelecer a ligação.

F8 ou Delete numa sessão de um host remove-a, depois de uma confirmação que tem Não por omissão. Isto fecha a sessão e as respetivas consolas remotas e elimina os painéis do Borg e o histórico de terminal guardados; os ficheiros e as pastas no host mantêm-se. A sessão Default não pode ser removida. Uma sessão autónoma que esteja a alojar a ligação não se pode remover a si própria; feche-a primeiro no host e execute o Borg noutra sessão. Se a remoção falhar, a sessão continua na lista para poder tentar de novo. Uma sessão em execução é parada primeiro, e o serviço não a volta a iniciar.

Espelhar uma sessão

borg mirror MACHINE:SESSION mostra o ecrã em direto da sessão remota no seu terminal local; Alt+Shift+M abre o mesmo espelho a partir de um Borg local com um painel remoto. Ctrl-G (mantenha Control premido e prima G) sai do espelho e volta aos painéis locais, tal como um clique na faixa na parte inferior. A linha acima dela indica quem tem o controlo; Ctrl-] também sai.

Um borg normal ou borg --session NAME pode ser espelhado enquanto corre, sem o serviço em segundo plano. O terminal original continua visível, e qualquer entrada de teclado ou rato nele retoma o controlo ao espelho. Enquanto tem o controlo, o Borg do host organiza o ecrã para a sua janela: quando o espaço acima da faixa é mais pequeno do que o terminal do host, o Borg desenha no canto superior esquerdo desse terminal com o seu tamanho, e o resto fica em branco. Quando o controlo volta ao terminal do host ou sai do espelho, o Borg volta a ocupar esse terminal inteiro. Um espelho sem controlo segue o esquema do terminal do host e é cortado para caber numa janela mais pequena; aumentar a janela mostra o resto. Uma sessão que o serviço em segundo plano mantém continua ativa depois de o seu terminal fechar, e o computador que tem o controlo define o seu tamanho.

Se outro terminal tiver o controlo da sessão remota, o espelho abre em modo só de visualização e as suas teclas não chegam à sessão. Prima Ctrl-T ou clique na linha de estado para assumir o controlo e desligar o outro terminal, ou comece com borg mirror MACHINE:SESSION --take; --take assume sempre o controlo retirando-o a outro visualizador. Depois de ter o controlo, a primeira tecla acorda um ecrã remoto em repouso, e as teclas e a entrada de rato seguintes chegam-lhe. Um visualizador que fique para trás salta os fotogramas de animação antigos e passa diretamente para o ecrã atual.

Quando o host deixa de responder, por exemplo durante uma atualização, o espelho mantém o último ecrã, indica-o na linha de estado e tenta de novo a cada 2 segundos, durante 100 segundos no máximo. Entretanto, Ctrl-G sai do espelho. Quando o host regressa, o espelho volta a mostrar o seu ecrã, com a versão que corre agora no canto inferior direito. Se o host continuar ausente depois disso, o espelho termina com uma mensagem.

Um pedido do agente aparece no espelho tal como o servidor o mostra, e responde-lhe aí quando tiver o controlo. Se abriu o espelho a partir de um painel remoto e o pedido ainda esperar quando sair do espelho, o borg desse painel volta a mostrá-lo.

Executar um relay

borg-relay é o relay através do qual os borgs se encontram. Num servidor Linux com um domínio apontado para ele e a porta 443 livre, um só comando instala-o como serviço, com um certificado TLS da Let’s Encrypt:

curl -fsSL https://raw.githubusercontent.com/0xcd21h/borg-commander/main/scripts/install-relay.sh | sudo sh -s -- relay.example.com you@example.com

Execute o mesmo comando para o atualizar.

No Dokploy, no Coolify ou noutro host Docker cujo proxy trate do TLS, execute a imagem ghcr.io/0xcd21h/borg-relay:latest e atribua-lhe um domínio na porta 8080. No Dokploy, crie uma aplicação a partir dessa imagem Docker com um domínio na porta 8080 do contentor e HTTPS ativo; no Coolify, crie um recurso a partir dessa imagem Docker com a porta 8080 exposta e um domínio. Ambos aceitam também packaging/relay/docker-compose.yml como serviço Compose. A imagem executa borg-relay --behind-proxy: o proxy serve HTTPS e deixa passar os WebSockets, e o relay aplica os seus limites por endereço de cliente, tal como o proxy o indica em X-Forwarded-For. Corre como utilizador sem privilégios e tem uma verificação de estado (GET /health).

Num host Docker sem esse proxy, a mesma imagem serve TLS diretamente:

docker run -d --restart unless-stopped -p 443:443 -v borg-relay:/data ghcr.io/0xcd21h/borg-relay --domain relay.example.com --cache /data

Atrás de outro proxy que trate do TLS, execute borg-relay --behind-proxy --listen 127.0.0.1:8080. Execute-o desta forma apenas atrás de um proxy, porque o relay confia no endereço de cliente que o proxy indica. O relay impõe limites por endereço para servidores e sessões, tamanho de frame, largura de banda, bytes por sessão, tempo de inatividade e duração da sessão. Não guarda nada além do seu certificado.

O relay regista apenas contagens: uma vez por minuto, se algo tiver mudado, escreve uma linha como

stats: connections=3 servers=2 sessions=1 joined=14 carried=3.2MiB limited=0

Esta linha mostra as ligações que mantém, os servidores registados e as sessões abertas e, desde que arrancou, as sessões estabelecidas, os bytes que transportaram e as ligações e sessões que um limite recusou ou terminou. Para depuração, --log, ou a variável de ambiente BORG_RELAY_LOG=1 no caso da imagem, regista também a inscrição de cada servidor, identificado pelo início da sua chave, cada sessão com os bytes que transportou e cada limite atingido com o endereço do cliente.