Hermes Agent Web Dashboard: acesso local, perfis e diagnóstico

A interface gráfica do Hermes Agent Web Dashboard oferece administração baseada em navegador para a sua instalação do agente, eliminando a necessidade de editar arquivos de configuração diretamente. O painel permite gerenciar chaves de acesso de API, alternar perfis ativos, inspecionar sessões anteriores e iniciar um terminal integrado sem modificar o ambiente do sistema manualmente.

Inicialização básica e dependências do sistema

Por padrão, o painel de controle é iniciado na interface de loopback:

hermes dashboard

Esse comando inicia um servidor HTTP local e abre o endereço http://127.0.0.1:9119 no navegador padrão. Se essa porta já estiver em uso por outro serviço local, você pode substituí-la com a flag --port:

hermes dashboard --port 9120 --no-open

A flag --no-open impede a abertura automática de uma nova aba no navegador, o que é ideal para processos em segundo plano ou scripts de automação.

O pacote básico hermes-agent não inclui a pilha web por padrão. Em ambientes Linux, macOS e WSL2, instale os componentes opcionais necessários dentro do ambiente virtual do agente:

cd ~/.hermes/hermes-agent && uv pip install -e ".[web,pty]"

O pacote extra web instala o FastAPI e o Uvicorn, enquanto o pty adiciona o ptyprocess para sistemas POSIX. A compilação da interface estática do painel requer uma instalação ativa do Node.js (quando o npm estiver presente, o frontend é compilado automaticamente na primeira inicialização).

Limites de plataforma: Windows nativo vs. WSL2

De acordo com o guia do Windows (Native), uma instalação nativa no Windows oferece suporte às páginas de configuração, métricas, tarefas e banco de dados de sessões. No entanto, a aba do terminal integrado /chat depende de pseudoterminais POSIX PTY. Como o Windows nativo não oferece suporte a essa chamada, é necessário executar o agente dentro do WSL2 para obter sessões de terminal interativas completas no navegador.

Também é fundamental separar os processos: o painel web e os gateways de mensagens (messaging gateways para Telegram, Discord e outras plataformas) operam como daemons independentes. Iniciar a interface web não ativa nem inicializa automaticamente o gateway da plataforma.

Gerenciamento de perfis e configuração de modelos

O painel de controle opera no nível de toda a máquina, administrando de forma centralizada todos os perfis criados. O seletor de perfis no menu lateral altera o contexto de trabalho por meio do parâmetro de URL ?profile=<nome>.

1. Seções Config e API Keys: A página Config edita parâmetros no config.yaml, onde as alterações são salvas clicando no botão Save. Já a página API Keys gerencia variáveis de ambiente em ~/.hermes/.env: as chaves são definidas e removidas individualmente para cada variável específica, sem um botão de salvamento geral ou validação em lote de todos os campos.
2. Consistência de provedor e modelo: O modelo selecionado e as credenciais devem corresponder estritamente ao mesmo provedor. Ao integrar um serviço de terceiros compatível com a API da OpenAI, consulte os parâmetros oficiais do fornecedor: por exemplo, configurações de conexão, IDs de modelo e campos obrigatórios estão descritos no guia da BetterToken. Um provedor de terceiros oferece apenas acesso independente de API aos modelos e não hospeda o próprio painel Hermes nem gerencia túneis de rede.
3. Verificação de funcionamento via Sessions: Para uma validação manual de integridade, envie um prompt curto somente de leitura. Lembre-se de que a consulta de teste pode ser tarifada pelo provedor. O sucesso da inferência é confirmado quando você recebe uma resposta substantiva na interface e o consumo de tokens é registrado nos metadados da sessão ou nos registros do provedor. A simples exibição de uma nova linha na lista da aba Sessions indica apenas que o registro da sessão foi criado, não que o modelo respondeu com êxito.

Acesso remoto seguro

Por padrão, o servidor web escuta exclusivamente em 127.0.0.1. Ao vincular a interfaces externas (--host 0.0.0.0), um portal de autenticação (auth gate) é ativado automaticamente. Se nenhum provedor de autenticação estiver configurado, o agente encerra a execução com erro (fail-closed). A flag legada --insecure não desativa mais a verificação de autenticidade. Vinculações a redes públicas ou externas exigem autenticação obrigatória, conforme a documentação do Hermes Agent.

O método recomendado para conectar-se a um servidor remoto sem expor portas externas é o encaminhamento local de porta via túnel SSH (substitua user@your-server pelo endereço e usuário do seu servidor remoto):

ssh -N -L 9119:127.0.0.1:9119 user@your-server

Se a porta local 9119 na sua estação de trabalho já estiver ocupada por outro processo, use a alternativa com porta local diferente:

ssh -N -L 9120:127.0.0.1:9119 user@your-server

Com essa configuração, o servidor Hermes na máquina remota continua rodando estritamente na interface de loopback 127.0.0.1, todo o tráfego é criptografado pelo túnel SSH e você acessa o painel a partir da sua estação de trabalho no endereço http://127.0.0.1:9119 (ou http://127.0.0.1:9120 se tiver alterado a porta local).

Diagnóstico de problemas passo a passo

Ao se deparar com erros, isole a camada em que ocorreu a falha em vez de testar a cadeia inteira de uma só vez.

+----------------------------------------------------------------+
| 1. HTTP-транспорт      | 127.0.0.1:9119 /api/status            |
+------------------------+---------------------------------------+
| 2. Окружение и PTY     | Node.js / POSIX ptyprocess (WSL2)     |
+------------------------+---------------------------------------+
| 3. Сокеты и каналы     | /api/pty (Chat) / /api/ws (Desktop)   |
+------------------------+---------------------------------------+
| 4. Провайдер инференса | Ключи API, лимиты и сетевой эндпоинт  |
+----------------------------------------------------------------+

As camadas de diagnóstico representadas na árvore de decisão acima correspondem a:

• Camada 1 (Transporte HTTP / HTTP-транспорт): 127.0.0.1:9119 /api/status
• Camada 2 (Ambiente e PTY / Окружение и PTY): Node.js / POSIX ptyprocess (WSL2)
• Camada 3 (Sockets e canais / Сокеты и каналы): /api/pty (Chat) / /api/ws (Desktop)
• Camada 4 (Provedor de inferência / Провайдер инференса): chaves de API, limites e endpoint de rede (Ключи API, лимиты и сетевой эндпоинт)

1. Camada de rede (HTTP): A disponibilidade de GET /api/status comprova apenas que o processo Uvicorn está em execução e respondendo a requisições HTTP. Esse endpoint é aberto e não garante que a autorização tenha sido concluída com êxito nem que o chat interativo esteja pronto.
2. Camada de PTY e interface: A mensagem de erro Connection closed pode ter várias causas distintas. No ambiente nativo do Windows, uma causa diagnóstica primária é a ausência de suporte a POSIX PTY (nesse caso, a execução deve ser migrada para o WSL2). Em outros sistemas operacionais, esse sintoma não se resume ao PTY e requer a inspeção dos logs do sistema e da conexão do socket. Falhas de compilação de estilos ou tela em branco exigem verificar a versão do Node.js e reinstalar/recompilar as dependências.
3. Canais de socket e autorização: O terminal integrado do navegador utiliza a rota /api/pty, enquanto o cliente Desktop remoto conecta-se através de /api/ws. Se o cliente indicar que o backend está acessível, mas a sessão não responder, verifique a conexão do respectivo canal: problemas costumam decorrer da ausência ou expiração do ticket de sessão, ou do bloqueio pela proteção contra DNS-rebinding quando o cabeçalho Host não coincide com o endereço de vinculação.
4. Camada do provedor de modelo: Lentidão na geração ou mensagens de erro exibidas após o envio de uma mensagem no terminal ativo normalmente estão associadas ao nível da API (validade da chave no .env, acessibilidade do endpoint do provedor, limites de uso e saldo). No entanto, erros do provedor não comprovam que o servidor do painel esteja 100% íntegro: em situações de falha, também pode ser necessário verificar o estado do runtime e o ciclo de vida da sessão.