Agente Hermes: Servidor Headless + Configuração de Área de Trabalho Remota

Executar o Hermes Agent em um servidor sem interface gráfica (headless) enquanto se conecta a partir de um cliente desktop em outra máquina requer dois processos de servidor e uma única conexão de cliente.

A arquitetura separa o backend do Hermes em dois processos no lado do servidor e uma interface no lado do cliente. O backend hermes serve lida com as conexões da API e do painel de controle (dashboard), enquanto o processo hermes gateway run gerencia os canais de mensagens independentemente. O cliente desktop conecta-se ao backend de serviço (serve), não ao gateway.

Dois processos no servidor, um aplicativo no cliente. Ambos os processos do servidor compartilham a mesma configuração ~/.hermes/, habilidades (skills), memória e sessões. Os agendamentos Cron são executados no servidor onde o gateway está em execução.

Para instalação, configuração do provedor e configuração inicial, comece com o Hermes AI Assistant — Instalação, Configuração, Fluxo de Trabalho e Solução de Problemas.

Configurar o servidor headless

1. Configurar autenticação

A autenticação básica fornece proteção suficiente para uma LAN confiável. Adicione as credenciais ao arquivo de ambiente:

cat >> ~/.hermes/.env << 'EOF'
HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=escolha-uma-senha-forte
HERMES_DASHBOARD_BASIC_AUTH_SECRET=$(openssl rand -base64 32)
EOF
chmod 600 ~/.hermes/.env

O arquivo .env reside junto ao config.yaml em ~/.hermes/. O Hermes resolve a configuração com substituições da CLI primeiro, depois config.yaml, depois .env e, por fim, os padrões internos. Segredos devem ficar no .env.

2. Iniciar o backend

Execute o backend de serviço em todas as interfaces:

hermes serve --host 0.0.0.0 --port 9119

O backend escuta na porta 9119 e aceita conexões WebSocket do cliente desktop. Verifique se está em execução com uma verificação rápida de status:

curl -s http://localhost:9119/api/status | jq '.auth_required, .auth_providers'
# Esperado: true  "basic"

3. Executar como um serviço systemd

Para um servidor persistente que sobreviva a reinicializações, instale um serviço systemd de nível de usuário. Crie o arquivo de unidade em /etc/systemd/user/hermes-serve.service:

[Unit]
Description=Backend de Serviço do Hermes Agent

[Service]
EnvironmentFile=%h/.hermes/.env
ExecStart=/home/rg/.hermes/hermes-agent/venv/bin/python -m hermes_cli.main serve --host 0.0.0.0 --port 9119
Restart=on-failure

[Install]
WantedBy=default.target

Recarregue o daemon, habilite o serviço e inicie-o:

systemctl --user daemon-reload
systemctl --user enable hermes-serve
systemctl --user start hermes-serve

Verifique o status do serviço:

systemctl --user status hermes-serve

4. Iniciar o gateway

O gateway é um processo separado que lida com canais de mensagens — Telegram, Discord, Slack e outros. Inicie-o independentemente:

hermes gateway run

O gateway e o backend de serviço (serve) são dois processos separados. O gateway gerencia sessões, executa agendamentos cron e roteia mensagens. O backend de serviço fornece a superfície da API para conexões de desktop e painel da web. Eles compartilham o mesmo diretório inicial, mas executam-se independentemente.

Para a lista completa de comandos e subcomandos do gateway, consulte o Guia de Referência Rápida da CLI do Hermes Agent. Se sua interface principal for mensagens móveis, combine esta configuração com Controle de Voz do Hermes pelo Celular para fluxos de trabalho focados em voz sobre o mesmo processo de gateway.

5. Verificar o backend

Confirme que o backend está respondendo e que a autenticação está ativa:

curl -s http://localhost:9119/api/status | jq '.auth_required, .auth_providers'

Saída esperada:

true
"basic"

Se a autenticação não estiver habilitada, a resposta mostrará false para auth_required. Verifique se o arquivo .env contém as variáveis corretas e se o serviço foi reiniciado após as alterações de configuração.

Conectar do cliente desktop

Opção A: Aplicativo Hermes Desktop

Instale o Hermes Desktop no site oficial. Inicie o aplicativo, navegue até Configurações → Gateway → Gateway Remoto e insira o endereço do servidor:

http://<ip-do-servidor>:9119

Faça login com o nome de usuário e a senha que você configurou no servidor.

Alternativamente, defina a URL remota via variável de ambiente:

HERMES_DESKTOP_REMOTE_URL=http://<ip-do-servidor>:9119 hermes desktop

Opção B: Painel web (Dashboard)

Abra http://<ip-do-servidor>:9119 em um navegador e faça login com as credenciais de autenticação básica. O painel web fornece uma interface baseada em navegador para o backend do Hermes, sem exigir a instalação do desktop.

Opção C: CLI

A partir do terminal do PC desktop, configure a URL remota nas configurações do aplicativo desktop ou na variável de ambiente HERMES_DESKTOP_REMOTE_URL. A superfície da CLI conecta-se através do mesmo canal WebSocket que o aplicativo desktop.

Considerações de rede e segurança

Para uma rede local confiável, a autenticação básica em 0.0.0.0 é adequada. Se o servidor estiver exposto à internet, use o Tailscale para vincular ao IP do Tailscale em vez de 0.0.0.0, ou configure um provedor OAuth para autenticação mais forte. Sempre abra a porta TCP 9119 no firewall do servidor quando o backend precisar aceitar conexões externas.

Distinções importantes de processos

Compreender a separação entre os dois processos do servidor evita erros comuns de configuração:

• hermes serve — O backend ao qual o aplicativo desktop e o painel web se conectam. Lida com a superfície da API e conexões WebSocket.
• hermes gateway run — O processo que lida com Telegram, Discord, Slack e outros canais de mensagens. Gerencia sessões, executa agendamentos cron e roteia mensagens.
• Estes são dois processos separados no servidor. Eles compartilham a configuração ~/.hermes/, habilidades, memória e sessões, mas executam-se independentemente.
• Agendamentos Cron são executados no servidor onde o gateway está em execução.
• Perfis, habilidades e memória são configurados no lado do servidor. O cliente conecta-se ao backend já configurado.

Para configuração focada em perfis e habilidades ajustadas para diferentes funções de produção, consulte Habilidades do Hermes AI Assistant para Configurações Reais de Produção.

Solução de Problemas

O desktop não consegue conectar ao servidor

1. Verifique se o backend está em execução: systemctl --user status hermes-serve
2. Verifique se a porta está aberta: ss -tlnp | grep 9119
3. Teste do servidor: curl -s http://localhost:9119/api/status
4. Teste da máquina cliente: curl -s http://<ip-do-servidor>:9119/api/status
5. Se o teste do cliente falhar, verifique as regras do firewall: sudo ufw status ou sudo iptables -L

Falha na autenticação

1. Confirme se o arquivo .env tem permissões corretas: ls -la ~/.hermes/.env (deve ser 600)
2. Verifique se o segredo foi gerado: grep HERMES_DASHBOARD_BASIC_AUTH_SECRET ~/.hermes/.env
3. Reinicie o serviço após alterações de configuração: systemctl --user restart hermes-serve

O gateway não responde às mensagens

O gateway é um processo separado do backend. Se o desktop se conecta, mas as plataformas de mensagens não funcionam:

1. Verifique o status do gateway: hermes gateway status
2. Inicie o gateway, se estiver parado: hermes gateway start
3. Revise os logs: hermes logs gateway -f

Referências

• Documentação do Aplicativo Desktop do Hermes Agent
• Guia de Configuração do Hermes Agent
• Gateway de Mensagens do Hermes Agent
• Hermes AI Assistant — Instalação, Configuração, Fluxo de Trabalho e Solução de Problemas
• Guia de Referência Rápida da CLI do Hermes Agent — comandos, flags e atalhos de barra (/)
• Habilidades do Hermes AI Assistant para Configurações Reais de Produção

Este artigo faz parte do cluster Sistemas de IA, que cobre assistentes autogerenciados, arquitetura de recuperação, infraestrutura de LLM local e observabilidade.