Hermes multi-instância sem conflitos: o guia completo de perfis

Quando as pessoas experimentam o Hermes pela primeira vez, tendem a colocar tudo na sessão padrão: programação, e-mails, pesquisa, tarefas agendadas — tudo misturado. Em pouco tempo, a memória fica confusa, a personalidade se dilui e a fatura da API fica impossível de atribuir.

O Hermes tem uma resposta mais elegante: perfis. Um perfil é um diretório home do Hermes independente com seu próprio:

  • config.yaml (modelo, ferramentas, configurações do gateway)
  • .env (chaves API, tokens de bot)
  • SOUL.md (personalidade / prompt do sistema)
  • memories/ (memória)
  • sessions/ (histórico de conversas)
  • skills/ (habilidades)
  • cron (tarefas agendadas)
  • estado do gateway

Pense nisso como executar várias instâncias isoladas do Hermes em uma única máquina. Este guia mostra como transformar essa máquina em um verdadeiro estúdio de IA multi-inquilino.

1. Início rápido: criar um perfil de programação

hermes profile create coder
coder setup
coder chat

Três linhas. coder agora é um comando próprio com sua própria configuração, memória e sessões. Você pode:

coder config set model.default anthropic/claude-sonnet-4
echo "Você é um engenheiro sênior focado em Python e infraestrutura." > ~/.hermes/profiles/coder/SOUL.md
coder chat

Enquanto isso, o hermes chat padrão permanece inalterado.

2. O que realmente é um perfil: isolamento via HERMES_HOME

O Hermes decide onde fica o “home” através da variável de ambiente HERMES_HOME. O comando coder chat é essencialmente:

HERMES_HOME=~/.hermes/profiles/coder hermes chat

Como get_hermes_home() é usado em mais de 119 lugares, configuração, memória, sessões, habilidades, PID do gateway, logs e cron são automaticamente escopados para aquele diretório.

Mas atenção: um perfil não é um sandbox. No backend de terminal local padrão, o Hermes ainda executa como seu usuário do sistema operacional e pode acessar todo o sistema de arquivos. Para isolamento do sistema de arquivos, use Docker.

3. Três formas de criar um perfil

3.1 Perfil em branco

hermes profile create mybot

Cria um perfil novo com skills incluídos. Depois execute mybot setup para configurar as chaves API.

3.2 Clonar apenas configuração (--clone)

hermes profile create work --clone

Copia o config.yaml, .env, SOUL.md e skills do perfil atual. Mesmo modelo e capacidades, mas memória e sessões novas.

Ideal para: mesmo modelo, personalidade ou diretório de trabalho diferente.

3.3 Clonar tudo (--clone-all)

hermes profile create backup --clone-all

Copia tudo: configuração, chaves, personalidade, todas as memórias, habilidades, cron. Um snapshot de trabalho.

Observação: histórico de sessões, state.db, backups, state-snapshots e checkpoints são excluídos porque podem atingir dezenas de GB. Para backup completo incluindo histórico, use hermes profile export ou hermes backup.

3.4 Clonar de um perfil específico

hermes profile create work --clone-from coder
hermes profile create work-backup --clone-from coder --clone-all

3.5 Adicionar descrição para roteamento de kanban

hermes profile create researcher --description "Lê código-fonte e documentação externa, escreve resultados."

O orquestrador de kanban usa essa descrição para rotear tarefas ao perfil adequado.

4. Alternar e usar perfis

Aliases de comando automáticos

Cada perfil recebe um wrapper em ~/.local/bin/<name>:

coder chat
personal-bot gateway start
research config set model.default openai/gpt-4o

Flag explícito -p

hermes -p coder chat
hermes --profile=coder doctor
hermes chat -p coder -q "hello"    # funciona em qualquer posição

Padrão fixo (hermes profile use)

hermes profile use coder
hermes chat          # agora aponta para coder
hermes profile use default

Semelhante a kubectl config use-context.

Saber onde você está

  • O prompt muda para coder ❯
  • O banner de inicialização mostra Profile: coder
  • hermes profile mostra nome, caminho, modelo e status do gateway

5. Múltiplos gateways: um bot por perfil

Cada perfil pode executar seu próprio gateway:

coder gateway start
personal-bot gateway start
research gateway start

Cada gateway é um processo independente com seu próprio token de bot. Configure tokens diferentes do Telegram/Discord/Slack por perfil:

nano ~/.hermes/profiles/coder/.env
nano ~/.hermes/profiles/personal-bot/.env

Segurança: bloqueio de tokens

Se dois perfis usarem acidentalmente o mesmo token de bot, o segundo gateway falha e indica o perfil conflitante. Suportado para Telegram, Discord, Slack, WhatsApp e Signal.

Serviços persistentes

coder gateway install      # cria o serviço hermes-gateway-coder
personal-bot gateway install

Serviços systemd/launchd são independentes e reiniciam independentemente.

Script de gerenciamento em massa

Salve isso como ~/.local/bin/hermes-gateways:

#!/bin/sh
set -eu

profiles="default coder personal-bot research"

usage() {
  echo "Usage: hermes-gateways {start|stop|restart|status|list}"
}

run_for_profile() {
  profile="$1"
  action="$2"
  if [ "$profile" = "default" ]; then
    hermes gateway "$action"
  else
    hermes -p "$profile" gateway "$action"
  fi
}

action="${1:-}"
case "$action" in
  start|stop|restart|status)
    for profile in $profiles; do
      echo "==> $action $profile"
      run_for_profile "$profile" "$action"
    done
    ;;
  list)
    hermes gateway list
    ;;
  *)
    usage
    exit 2
    ;;
esac

Depois:

chmod +x ~/.local/bin/hermes-gateways
hermes-gateways start
hermes-gateways stop
hermes-gateways restart
hermes-gateways status

6. Multiplexação: um gateway para todos os perfis

Quando você tem muitos perfis, um processo por perfil fica pesado. O Hermes suporta multiplexação: apenas o gateway do perfil padrão executa, e ele serve as mensagens recebidas para todos os perfis.

Ativar

hermes config set gateway.multiplex_profiles true
hermes gateway restart

Ou em ~/.hermes/config.yaml:

gateway:
  multiplex_profiles: true

O que muda no modo multiplexado

  1. Perfis secundários não podem iniciar seu próprio gateway Se coder já está sendo servido pelo multiplexador, coder gateway start falha.

  2. Plataformas HTTP de entrada usam o prefixo /p/<profile>/

    POST http://host:8644/webhooks/<route>          # perfil padrão
POST http://host:8644/p/coder/webhooks/<route>  # perfil coder

    Plataformas de ligação de porta (webhook, api_server, msgraph_webhook, feishu, wecom_callback, bluebubbles, sms, whatsapp_cloud, line) só podem ser configuradas no perfil padrão. Outros perfis são acessados pelo prefixo.

  3. Plataformas de polling/conexão ainda precisam de um token por perfil Telegram, Discord, Slack, Matrix, Signal etc. funcionam multiplexados, mas cada perfil deve ter seu próprio token de bot. Dois perfis não podem fazer polling do mesmo par (plataforma, token).

  4. Chaves de sessão são namespaceadas por perfil agent:<profile>:... garante que dois perfis na mesma plataforma/chat nunca colidam. O perfil padrão mantém o namespace histórico agent:main:....

  5. Um único PID, lock e superfície de status hermes status mostra o multiplexador e os perfis atendidos; hermes status -p coder filtra apenas o coder.

Quando usar multiplexação

  • Implantações em contêiner/VPS onde N unidades de supervisão são um fardo.
  • Muitos perfis de baixo tráfego que não justificam um processo cada.
  • Você quer uma única coisa para iniciar, monitorar e reiniciar.

Quando não usar:

  • Você precisa de isolamento rígido a nível de processo.
  • A falha de um perfil não deve afetar os outros.
  • Você quer reiniciar um perfil independentemente.

7. Rotas de perfil: atribuir comunidades diferentes a agentes diferentes

Quando várias comunidades compartilham o mesmo token de bot — por exemplo, um bot do Discord servindo muitos guilds — você pode rotear guilds/canais/threads específicos para perfis diferentes:

gateway:
  multiplex_profiles: true
  profile_routes:
    - name: acme-server
      platform: discord
      guild_id: "1234567890"
      profile: acme

    - name: acme-support
      platform: discord
      guild_id: "1234567890"
      chat_id: "9876543210"
      profile: acme-support

    - name: tg-group
      platform: telegram
      chat_id: "-1001234567890"
      profile: tg-profile

Regras de correspondência

  • Todos os campos declarados devem ser satisfeitos (AND).
  • Campos não declarados são ignorados.
  • Especificidade: thread_id (8) > chat_id (4) > guild_id (2) > apenas plataforma.
  • Uma rota com chat_id também corresponde a threads/posts de fórum cujo canal pai é aquele canal.

Se uma rota nomear um perfil que não existe, as mensagens voltam para o perfil padrão.

8. Diretório de trabalho e isolamento de HOME

Definir um diretório de trabalho padrão

Se você quer que um perfil inicie em uma pasta de projeto específica:

terminal:
  backend: local
  cwd: /absolute/path/to/project

Observação: cwd: "." no backend local significa “o diretório a partir do qual o Hermes foi iniciado”, não o diretório do perfil.

HOME por perfil

Por padrão, instalações no host mantêm o HOME real do usuário do SO para que ferramentas como git, ssh, gh, npm, Claude Code e Codex possam reutilizar credenciais existentes. A contrapartida é que os perfis compartilham esse estado CLI em nível de usuário.

Para isolamento CLI estrito por perfil, defina:

terminal:
  home_mode: profile

O Hermes então inicia subprocessos com HOME={HERMES_HOME}/home. Você precisará inicializar ~/.ssh, ~/.gitconfig, ~/.config/gh etc. específicos dentro do home desse perfil.

O Hermes também expõe HERMES_REAL_HOME para que scripts ainda possam encontrar o home real da conta.

9. Distribuições de perfil: compartilhar um agente completo

Uma distribuição de perfil empacota um agente Hermes completo como um repositório git:

my-research-agent/
├── distribution.yaml    # manifesto
├── SOUL.md            # personalidade
├── config.yaml        # configuração
├── skills/            # habilidades incluídas
├── cron/              # tarefas agendadas
└── mcp.json           # servidores MCP

Instale com um comando:

hermes profile install github.com/you/my-research-agent --alias

Depois execute:

my-research-agent chat
my-research-agent gateway start

Atualize com:

hermes profile update my-research-agent

O que não está incluído em uma distribuição

  • auth.json, .env e outros segredos;
  • memories/, sessions/, state.db, logs (dados do usuário);
  • checkpoints, backups, caches.

Cada pessoa traz suas próprias chaves API e memórias; o compartilhado é personalidade + habilidades + configuração.

10. Gerenciar perfis

hermes profile list           # listar todos os perfis
hermes profile show coder     # ver detalhes de um perfil
hermes profile rename coder dev-bot   # renomear (atualiza alias + serviço)
hermes profile export coder   # exportar para coder.tar.gz
hermes profile import coder.tar.gz  # importar de arquivo
hermes profile delete coder   # excluir (requer confirmação)
hermes profile delete coder --yes  # forçar exclusão

O perfil padrão não pode ser excluído. Para remover tudo, use hermes uninstall.

11. Armadilhas comuns e recomendações

Armadilha Abordagem correta
Tratar um perfil como sandbox Perfis isolam o estado do Hermes, não o sistema de arquivos. Use Docker para isolamento de arquivos.
Dois perfis compartilham um token de bot Cada plataforma de polling/conexão de cada perfil precisa de seu próprio token.
Configurar plataformas de ligação de porta em perfis secundários multiplexados Configure webhook/api_server/feishu/etc. apenas no perfil padrão; alcance os outros via /p/<profile>/.
Achar que cwd: "." é o diretório do perfil No backend local significa o diretório de lançamento; use caminho absoluto para fixar um projeto.
Vazamento de memória em Hermes compartilhado Crie perfis separados para diferentes propósitos; cada um tem sua própria memória.
Skills dessincronizados após atualização hermes update sincroniza automaticamente skills incluídos em todos os perfis.

12. Um layout multi-perfil recomendado

Se você está planejando do zero, considere:

Perfil Propósito Modelo Toolsets
default Perguntas gerais do dia a dia modelo leve ferramentas básicas
coder Código, revisão, refatoração modelo de código forte code-wiki, git, docker
writer Documentação, blogs, copy modelo de contexto longo web, memory
research Pesquisa, artigos, análise competitiva modelo de raciocínio arxiv, web, browser
ops Deployments, monitoramento, CI/CD modelo de ferramentas forte docker, ssh, cron
personal-bot Assistente pessoal no Telegram/Discord modelo de chat plataformas de gateway

Cada perfil tem sua própria personalidade, memória e chaves API. Sem conflitos.

Conclusão

Os perfis do Hermes não são simplesmente “várias contas”. Eles são um sistema completo de isolamento de estado multi-inquilino que permite executar vários agentes especializados na mesma máquina, cada um com sua própria identidade, memória e ferramentas.

Quando um Hermes não for suficiente, não force todos os contextos em uma única sessão. Reserve dois minutos para criar um perfil. Você descobrirá que seus agentes de IA se tornam muito mais úteis quando não disputam estado compartilhado.