Execute o Relayium como um serviço de recepção sempre ativo

Última atualização: 2026-08-06

O relayium serve --once trata de uma única transferência recebida e então encerra — ótimo para um pull ocasional. Mas se você quer que uma máquina seja um ponto de recepção permanente — um servidor doméstico onde os backups chegam durante a noite, uma máquina de build para a qual o CI envia artefatos, um NAS para o qual seu celular pode mandar fotos a qualquer momento — você quer o serve em execução o tempo todo, em vez de iniciá-lo manualmente a cada transferência.

Este guia aborda como iniciar um processo à escuta de longa duração, aprovar quem tem permissão para enviar, pré-autorizar pares para os casos em que ninguém está diante do terminal, executá-lo com systemd, e permitir que um remetente usando sync --delete espelhe as exclusões.

Antes de começar

Tudo abaixo é a CLI do relayium, então instale-a primeiro se ainda não tiver. No macOS ou Linux, um comando coloca um binário pré-compilado no seu PATH:

curl -fsSL https://relayium.com/install.sh | sh

Prefere escolher o arquivo você mesmo, ou está no Windows? Pegue um binário na página de releases — relayium.com/cli lista todas as opções de instalação (ou go build -o relayium ./cmd/relayium se você tiver Go).
relayium --version confirma que está instalada. Pule isso e os comandos abaixo só imprimirão “command not found”.

Iniciar o processo à escuta

O que você precisa antes do passo 1

A CLI nas duas máquinas. relayium version imprime uma linha de versão em cada uma; se o shell responder command not found, ela ainda não está instalada ali.
Um diretório para os arquivos recebidos nesta máquina, e o disco para o que vai cair nele.
Um endereço que o remetente alcance e uma porta de entrada aberta. Sem --port, o serve escuta na 9031.
Se esta máquina vai rodar sem terminal — e é exatamente esse o sentido de virar um serviço —, a impressão digital do remetente, com antecedência. Há uma seção dedicada a isso abaixo, e é de longe o motivo mais comum de um receptor permanente recusar tudo.

O serve escuta envios daemon direto (relayium://host:port) por uma conexão TLS 1.3 com fixação e grava o que recebe em um diretório. Nada precisa ser compartilhado de antemão para iniciá-lo — nenhuma impressão digital para copiar, nenhum servidor para registrar:

relayium serve --dir ~/inbox
relayium serve --dir /srv/drop --port 9040   # porta diferente da padrão
relayium serve --dir ~/inbox --allow-delete  # permitir que um remetente com sync --delete espelhe as exclusões

Escolha onde os arquivos devem cair e inicie o receptor. Até aqui nada precisa ser combinado de antemão.
```
relayium serve --dir ~/inbox
```
Da máquina que envia, empurre algo para este host pelo endereço relayium:// dele.
```
relayium push ./report.pdf relayium://drop.example.com:9031
```
De volta ao receptor, responda ao pedido de aprovação. Um y grava essa impressão digital em authorized_fingerprints, e os envios seguintes da mesma máquina não perguntam mais.
Confirme que o arquivo caiu mesmo em --dir e não no diretório de onde você iniciou o serve.
```
ls -l ~/inbox
```

Como é um receptor que funciona

O serve avisa logo de cara que não tem pares autorizados, pergunta no primeiro envio de uma máquina nova e fica em silêncio em todos os seguintes. Quem envia termina com 0 e o arquivo está em --dir.

$ relayium serve --dir ~/inbox
no authorized peers yet — you'll be asked to approve each new peer on its first push.
Incoming push from 203.0.113.7:54021
  fingerprint: 74318e3b…
Accept and remember this peer? [y/N] y

--dir define onde os arquivos chegam (por padrão, o diretório atual).
--port define a porta de escuta (por padrão, 9031); abra-a no seu firewall se o remetente estiver em outro lugar.
Sem --once, o serve continua em execução e aceitando envios até você pará-lo ou um gerenciador de processos reiniciá-lo — é isso que o torna um serviço sempre ativo.

Aprovar quem tem permissão para enviar

Na primeira vez que um novo par envia algo, o serve — se estiver rodando em um terminal — mostra de onde veio o envio e sua impressão digital, e pede que você o aprove, do mesmo jeito que o SSH pergunta sobre um host desconhecido na primeira conexão:

Incoming push from 203.0.113.7:54021
  fingerprint: 74318e3b…
Accept and remember this peer? [y/N] y

Responda y uma vez e essa impressão digital é gravada em authorized_fingerprints; todo envio posterior da mesma máquina passa sem nenhuma solicitação.
Uma impressão digital identifica uma máquina, não um endereço de rede, então continua válida mesmo que o IP do remetente mude.
Esta etapa é interativa por decisão de projeto — precisa de alguém diante do teclado, o que deixará de valer assim que o serve passar para o systemd (a seguir).

Pré-autorizar pares para configurações não interativas

Quando o serve não tem um terminal onde perguntar — um serviço systemd, um processo em segundo plano, um pipe — ele não pode perguntar, então rejeita qualquer impressão digital que ainda não reconheça. Em vez disso, autorize os pares com antecedência. Na máquina que vai enviar, execute relayium id para imprimir a impressão digital dela; no receptor, adicione-a antes que o primeiro envio chegue:

# na máquina que vai ENVIAR: imprima a impressão digital dela
relayium id

# neste RECEPTOR sempre ativo: autorize-a de antemão
relayium authorize 74318e3b...

Na máquina que vai empurrar, imprima a impressão digital dela. São 64 caracteres hexadecimais e identificam a máquina, não o endereço.
```
relayium id
```
Autorize-a neste receptor, com o mesmo --config-dir sob o qual o serviço vai rodar. Autorizar como outro usuário, ou no caminho padrão enquanto a unidade usa outro, grava a impressão digital num arquivo que o serviço nunca lê.
```
relayium authorize 74318e3b… --config-dir /etc/relayium
```

authorize é idempotente — executá-lo de novo para uma impressão digital em que você já confia não faz nada.
Os arquivos de identidade e de confiança ficam em --config-dir, cujo padrão é ~/.config/relayium (id.key/id.crt é a identidade deste host, authorized_fingerprints é a lista de permissões de pares).

Executá-lo com systemd

Para um serviço que sobrevive a reinicializações e falhas, entregue o serve ao systemd. Aponte --config-dir para um caminho fixo para que a identidade do host e sua lista de pares autorizados permaneçam no lugar entre reinicializações:

# /etc/systemd/system/relayium-serve.service
[Unit]
Description=Relayium always-on receiver
After=network-online.target

[Service]
ExecStart=/usr/local/bin/relayium serve --dir /srv/drop --port 9031 --config-dir /etc/relayium --allow-delete
Restart=always
User=relayium

[Install]
WantedBy=multi-user.target

Autorize todos os pares que devem poder empurrar, antes mesmo de o serviço existir. Ele não consegue perguntar, então recusa tudo que já não seja confiável.
Escreva a unidade acima em /etc/systemd/system/relayium-serve.service, com --config-dir apontando para o mesmo caminho fixo sob o qual você autorizou.
Recarregue o systemd e inicie o serviço, habilitando-o para que volte depois de um reboot.
```
sudo systemctl daemon-reload
```
```
sudo systemctl enable --now relayium-serve
```
Confirme que está rodando e que o aviso que recusa tudo não aparece no log. Só a segunda checagem é específica desta montagem.
```
systemctl is-active relayium-serve
```
```
journalctl -u relayium-serve -n 20 --no-pager
```

Como é um serviço que funciona

is-active responde active, e o aviso de inicialização sobre não haver pares autorizados não aparece. Esse aviso é a única linha que diz, antes de qualquer remetente reclamar, que este serviço vai recusar todo envio.

$ systemctl is-active relayium-serve
active
$ journalctl -u relayium-serve -n 20 --no-pager | grep -c 'all pushes will be rejected'
0

Antes de habilitar o serviço, execute relayium authorize <fingerprint> para cada par que deva poder enviar — o próprio serviço não pode perguntar.
systemctl enable --now relayium-serve o inicia e o traz de volta a cada inicialização.
Mantenha /etc/relayium/id.key legível apenas pelo usuário do serviço; o relayium se recusa a carregar uma chave com permissões mais frouxas.

Executá-lo na inicialização no macOS (launchd)

O macOS não tem systemd — seu gerenciador de serviços é o launchd. Para manter o serve em execução em um Mac (por exemplo, um Mac mini deixado ligado como ponto de recepção), instale-o como LaunchDaemon para que ele inicie na inicialização, antes de qualquer login. Defina UserName para que ele rode como você e não como root, e dê a --dir e --config-dir caminhos absolutos para que seus arquivos de identidade e de confiança permaneçam no seu próprio ~/.config/relayium:

<!-- /Library/LaunchDaemons/com.relayium.serve.plist  (replace YOU with your macOS username) -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>              <string>com.relayium.serve</string>
  <key>UserName</key>           <string>YOU</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/relayium</string>
    <string>serve</string>
    <string>--dir</string>         <string>/Users/YOU/inbox</string>
    <string>--port</string>        <string>9031</string>
    <string>--config-dir</string>  <string>/Users/YOU/.config/relayium</string>
    <string>--allow-delete</string>
  </array>
  <key>RunAtLoad</key>   <true/>
  <key>KeepAlive</key>   <true/>
  <key>StandardOutPath</key>    <string>/Users/YOU/relayium-serve.log</string>
  <key>StandardErrorPath</key>  <string>/Users/YOU/relayium-serve.log</string>
</dict>
</plist>

# 1) authorize each pusher first — launchd gives serve no terminal to prompt on:
relayium authorize <fingerprint>     # get the fingerprint from the pusher's  relayium id

# 2) save the plist above to that path, then load it (root-owned, starts at boot):
sudo chown root:wheel /Library/LaunchDaemons/com.relayium.serve.plist
sudo launchctl bootstrap system /Library/LaunchDaemons/com.relayium.serve.plist

# check it's running / follow logs / stop it:
sudo launchctl print system/com.relayium.serve | grep state
tail -f ~/relayium-serve.log
sudo launchctl bootout system/com.relayium.serve

O launchd não dá nenhum terminal ao serve, então ele não pode perguntar — execute primeiro relayium authorize <fingerprint> para cada remetente, igual ao systemd. A impressão digital vem do relayium id daquela máquina.
O KeepAlive reinicia o serve se ele travar; o RunAtLoad junto com um LaunchDaemon em /Library/LaunchDaemons o inicia na inicialização sem login — a opção certa para um Mac mini sem tela.
Prefere um serviço no escopo de login? Coloque o mesmo plist (removendo a chave UserName) em ~/Library/LaunchAgents/ e carregue-o com launchctl bootstrap gui/$(id -u) <path> — ele inicia no seu login em vez de na inicialização.
Se o firewall de aplicativos do macOS estiver ativado, permita conexões de entrada para o relayium (Ajustes do Sistema → Rede → Firewall), ou os envios para a sua porta serão bloqueados.

Permitir que um remetente com sync --delete espelhe as exclusões

Por padrão, o serve apenas adiciona ou atualiza arquivos — um remetente que executa sync --delete contra ele ainda copia os arquivos novos e alterados, mas qualquer exclusão que ele solicite é ignorada, com um aviso registrado no receptor. Inicie o serve com --allow-delete para optar por um espelhamento verdadeiro, em que os arquivos removidos no lado do remetente também são removidos aqui:

relayium serve --dir /srv/mirror --allow-delete

--allow-delete é uma opção do lado do receptor; o remetente ainda precisa solicitá-la com sync --delete.
Sem ela, nada é jamais excluído nesta máquina, não importa o que um remetente solicite.

Quando não funciona

Em quatro dessas cinco falhas o serviço continua rodando e parece saudável — um receptor que recusa tudo ainda é um receptor. Cada uma se resolve com uma linha para ler ou um comando para rodar.

Sintoma, checagem, correção

O serviço inicia e continua de pé, mas todo envio é recusado.

journalctl -u relayium-serve -n 20 --no-pager
# warning: no authorized peers and no terminal to approve on; all pushes will be rejected.

Um serviço não tem terminal, então nunca consegue executar a aprovação do primeiro envio, e tudo que ele vê é uma impressão digital desconhecida. Autorize cada remetente antes: relayium id na máquina que envia e relayium authorize <impressão> aqui, com o mesmo --config-dir que a unidade usa. Esse aviso é impresso na inicialização, então está no log desde a primeira linha.

O serviço não inicia de jeito nenhum e reclama de permissões inseguras no id.key.

stat -c '%a %U %n' /etc/relayium/id.key
# 400 relayium /etc/relayium/id.key

A chave precisa estar exatamente em 0600. Nem 0644 e — é aqui que quase todo mundo tropeça — nem 0400: apertar mais quebra o serviço com a mesma certeza que afrouxar. Dê chmod 600 na chave e confirme que ela pertence ao User= da unidade.

Quem envia relata que a conexão foi recusada.

relayium push ./build relayium://drop.example.com:9031
# hint: if the peer refused the connection, it may not have authorized this host.

O receptor não reconhece esse remetente. Rode relayium id na máquina que envia e relayium authorize com essa impressão no receptor. Se já fez isso, verifique se foi sob o --config-dir da unidade: o arquivo de confiança é por diretório, e uma impressão autorizada em ~/.config/relayium simplesmente não existe para um serviço que lê /etc/relayium.

Os envios funcionam quando você roda o serve na mão, mas não pelo serviço ou não de outra máquina.

sudo ss -tlnp | grep 9031

Duas causas distintas que uma única checagem separa. Se nada estiver escutando, a unidade não está habilitada: systemctl is-enabled relayium-serve. Se estiver escutando, a porta está bloqueada: abra a 9031 no firewall do host e em qualquer grupo de segurança da nuvem. Um --port fora do padrão precisa bater com a porta do relayium://host:N de quem envia.

As exclusões pedidas por um remetente com sync --delete nunca acontecem nesta máquina.

journalctl -u relayium-serve | grep -i delete

A exclusão é uma opção do lado receptor e vem desligada: arquivos novos e alterados continuam sendo copiados, e cada exclusão ignorada fica aqui como aviso no log. Acrescente --allow-delete ao ExecStart da unidade e reinicie. O remetente pedir não basta, e essa assimetria é proposital — um receptor não perde arquivos por causa de uma opção digitada em outro lugar.

Perguntas frequentes

Em que porta o serve escuta por padrão?

9031. Mude-a com --port tanto no processo à escuta (serve --port N) quanto no destino do remetente (relayium://host:N).

Preciso aprovar cada envio manualmente?

Apenas o primeiro envio de uma dada impressão digital, e somente quando o serve está rodando com um terminal conectado. Depois disso, fica memorizado. Rodar o serve de forma não interativa (systemd, um pipe) ignora completamente a solicitação e rejeita pares desconhecidos — pré-autorize-os com relayium authorize em vez disso.

Um remetente pode excluir arquivos no meu receptor sempre ativo?

Só se você iniciou o serve com --allow-delete e o remetente está executando sync --delete. Sem --allow-delete, as exclusões são ignoradas silenciosamente e todo o resto é transferido normalmente.

Executar um receptor sempre ativo é gratuito?

Sim. O relayium serve faz parte da CLI gratuita e auto-hospedável — sem conta, sem nível pago, em nenhum dos lados da conexão.

Onde o serve guarda sua identidade e sua lista de pares?

Em ~/.config/relayium por padrão (id.key/id.crt para a identidade deste host, authorized_fingerprints para a lista de permissões). Aponte --config-dir para um lugar fixo, como /etc/relayium, para um serviço systemd.

Como executo o serve na inicialização no macOS?

O macOS não tem systemd — use o launchd. Instale o serve como LaunchDaemon em /Library/LaunchDaemons (inicia na inicialização; defina UserName para rodar como você), ou como LaunchAgent em ~/Library/LaunchAgents (inicia no login). Este guia tem um plist pronto para editar; não há serviço do Homebrew. Pré-autorize os remetentes com relayium authorize primeiro, já que o launchd não dá ao serve nenhum terminal para perguntar.

Transforme qualquer máquina que você tenha em um receptor gratuito e sempre ativo — envios diretos sobre TLS com fixação, sem nenhum retransmissor envolvido.

Obter a CLI