Perfis: vários agentes na mesma máquina

Rode vários agentes Hermes independentes no mesmo computador — cada um com configuração, chaves de API, memória, sessões, skills e estado de gateway próprios.

O que é um perfil

Um perfil é um diretório Hermes separado. Cada perfil tem o próprio config.yaml, .env, SOUL.md, memórias, sessões, skills, tarefas de cron e banco de estado. Perfis servem para rodar agentes separados com propósitos diferentes — um assistente de código, um bot pessoal, um agente de pesquisa — sem misturar estado.

Um perfil para cada agente

Nunca aponte dois processos de agente para o mesmo perfil (o mesmo diretório do Hermes). Os dois gravam memória automaticamente, e cada um carrega o que o outro escreveu no próprio prompt de sistema no início da sessão — então dois escritores num diretório só vão empilhar estado até aquilo deixar de ser qualquer coisa que você configurou. Perfis existem exatamente para evitar isso; agentes que precisam de memória compartilhada devem usar um provedor externo de memória.

Ao criar um perfil, ele vira um comando automaticamente. Crie um perfil chamado coder e você já tem coder chat, coder setup, coder gateway start e assim por diante.

Começando

hermes profile create coder       # cria o perfil e o comando "coder"
coder setup                       # configura chaves de API e modelo
coder chat                        # começa a conversar

É isso. O coder agora é um perfil Hermes próprio, com configuração, memória e estado dele.

Criar um perfil

dica

Jeito mais rápido: rode hermes setup --portal dentro do perfil novo, para ligar modelos e ferramentas de uma vez. Veja Nous Portal.

Perfil em branco

hermes profile create meubot

Cria um perfil novo, já com as skills embutidas. Rode meubot setup para configurar chaves de API, modelo e tokens de bot.

Se você pretende usar esse perfil como trabalhador do kanban (ou quer que o orquestrador do kanban mande trabalho para ele), passe --description "<papel>" na criação, para o orquestrador saber no que ele é bom:

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

Dá para definir ou gerar a descrição depois, com hermes profile describe — veja o guia do Kanban para o modelo completo de roteamento.

Clonar só a configuração (--clone)

hermes profile create trabalho --clone

Copia o config.yaml, o .env, o SOUL.md e as skills do perfil atual para o novo. Mesmas chaves, mesmo modelo, mesmas capacidades, mas sessões e memória zeradas. Edite ~/.hermes/profiles/trabalho/.env para chaves diferentes, ou ~/.hermes/profiles/trabalho/SOUL.md para outra personalidade.

Clonar tudo (--clone-all)

hermes profile create backup --clone-all

Copia tudo — configuração, chaves, personalidade, todas as memórias, skills, tarefas de cron, plugins. Um retrato completo em funcionamento. O histórico de cada perfil fica de fora (histórico de sessões, state.db, backups/, state-snapshots/, checkpoints/) — isso pertence ao perfil de origem e pode chegar a dezenas de GB. Para um backup completo, com histórico, use hermes profile export ou hermes backup.

Clonar de um perfil específico

hermes profile create trabalho --clone-from coder

O --clone-from <origem> escolhe o perfil de origem diretamente e já implica clonar configuração, skills e SOUL. Combine com --clone-all quando quiser uma cópia completa daquela origem:

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

Memória Honcho e perfis

Com o Honcho ligado, as operações de clone criam automaticamente um par de IA dedicado ao perfil novo, compartilhando o mesmo espaço de trabalho do usuário. Cada perfil constrói as próprias observações e identidade. Veja Honcho — multiagente e perfis.

Usando perfis

Comandos por apelido

Todo perfil ganha um comando em ~/.local/bin/<nome>:

coder chat                    # conversa com o agente coder
coder setup                   # configura o coder
coder gateway start           # sobe o gateway do coder
coder doctor                  # confere a saúde do coder
coder skills list             # lista as skills do coder
coder config set model.default anthropic/claude-sonnet-4

O apelido funciona com qualquer subcomando do hermes — por baixo, é só hermes -p <nome>.

A opção -p

Também dá para escolher o perfil explicitamente, em qualquer comando:

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

Padrão fixo (hermes profile use)

hermes profile use coder
hermes chat                   # agora vai para o coder
hermes tools                  # configura as ferramentas do coder
hermes profile use default    # volta

Define um padrão, então os comandos hermes simples vão para aquele perfil. Como o kubectl config use-context.

Saber onde você está

A CLI sempre mostra qual perfil está ativo:

• Prompt: coder ❯ em vez de ❯
• Banner: mostra Profile: coder na abertura
• hermes profile: mostra nome, caminho, modelo e situação do gateway

Perfis, espaços de trabalho e sandbox

Perfis costumam ser confundidos com espaços de trabalho ou sandboxes, mas são coisas diferentes:

• Um perfil dá ao Hermes um diretório de estado próprio: config.yaml, .env, SOUL.md, sessões, memória, logs, tarefas de cron e estado de gateway.
• Um espaço de trabalho, ou diretório de trabalho, é onde os comandos de terminal começam. Isso é controlado à parte, por terminal.cwd.
• Um sandbox é o que limita o acesso ao sistema de arquivos. Perfis não colocam o agente em sandbox.

No backend de terminal padrão, o local, o agente continua tendo o mesmo acesso ao sistema de arquivos que a sua conta de usuário. Um perfil não o impede de acessar pastas fora do diretório do perfil.

Se você quer que um perfil comece numa pasta de projeto específica, defina um terminal.cwd absoluto e explícito no config.yaml daquele perfil:

terminal:
  backend: local
  cwd: /caminho/absoluto/para/o/projeto

Usar cwd: "." no backend local significa "o diretório de onde o Hermes foi aberto", não "o diretório do perfil".

Vale notar também:

• O SOUL.md pode orientar o modelo, mas não impõe fronteira de espaço de trabalho.
• Mudanças no SOUL.md valem numa sessão nova. Sessões abertas ainda podem estar usando o prompt antigo.
• Perguntar ao modelo "em que diretório você está?" não é um teste confiável de isolamento. Se você precisa de um diretório inicial previsível para as ferramentas, defina o terminal.cwd.

Rodando gateways

Cada perfil roda o próprio gateway, num processo separado e com token de bot próprio:

coder gateway start           # sobe o gateway do coder
assistente gateway start      # sobe o gateway do assistente (outro processo)

Tokens diferentes

Cada perfil tem o próprio .env. Configure um token de Telegram, Discord ou Slack diferente em cada:

# tokens do coder
nano ~/.hermes/profiles/coder/.env

# tokens do assistente
nano ~/.hermes/profiles/assistente/.env

Proteção: trava de token

Se dois perfis usarem o mesmo token de bot por acidente, o segundo gateway é bloqueado com um erro claro, nomeando o perfil em conflito. Vale para Telegram, Discord, Slack, WhatsApp e Signal.

Serviços persistentes

coder gateway install         # cria o serviço hermes-gateway-coder no systemd/launchd
assistente gateway install    # cria o serviço hermes-gateway-assistente

Cada perfil ganha o próprio nome de serviço. Eles rodam de forma independente.

Dentro da imagem Docker oficial

Os gateways por perfil são supervisionados pelo s6-overlay (o PID 1 do container), então hermes profile create <nome> registra automaticamente um serviço s6 em /run/service/gateway-<nome>/. O hermes -p <nome> gateway start/stop/restart chama o s6-svc em vez de criar um processo solto — falhas reiniciam sozinhas e o docker restart preserva o conjunto de gateways que estava rodando. Detalhes em supervisão de gateway por perfil.

Configurar perfis

Cada perfil tem o próprio:

• config.yaml — modelo, provedor, conjuntos de ferramentas, todas as opções
• .env — chaves de API, tokens de bot
• SOUL.md — personalidade e instruções

coder config set model.default anthropic/claude-sonnet-4
echo "Você é um assistente de código focado." > ~/.hermes/profiles/coder/SOUL.md

Se quiser que esse perfil trabalhe num projeto específico por padrão, defina também o terminal.cwd dele:

coder config set terminal.cwd /caminho/absoluto/para/o/projeto

Pelo painel

O painel web é uma superfície de máquina, capaz de gerenciar a configuração, as chaves, as skills, os MCPs e o modelo de qualquer perfil, pelo seletor na barra lateral — não é preciso um painel por perfil. O coder dashboard abre o painel da máquina com o perfil coder já selecionado. A aba de conversa do painel também segue o seletor, abrindo a conversa no diretório do perfil escolhido.

Atenção: "Set as active" na página de Perfis do painel é o padrão fixo para execuções futuras de CLI e gateway (o mesmo que hermes profile use) — para editar um perfil pelo painel, use o seletor.

Atualizar

O hermes update puxa o código uma vez (compartilhado) e sincroniza as skills embutidas novas em todos os perfis, automaticamente:

hermes update
# → Code updated (12 commits)
# → Skills synced: default (up to date), coder (+2 new), assistant (+2 new)

Skills modificadas por você nunca são sobrescritas.

Gerenciar perfis

hermes profile list           # mostra todos os perfis e a situação de cada um
hermes profile show coder     # detalhes de um perfil
hermes profile rename coder dev-bot   # renomeia (atualiza apelido e serviço)
hermes profile export coder   # empacota em coder.tar.gz (compartilhável; sem chaves)
hermes profile import coder.tar.gz   # instala um arquivo como perfil novo

Na conversa, os dois últimos existem como /export e /import — e no aplicativo desktop como ⌘K → Export/Import profile…. Veja compartilhar um perfil.

Dar nome ao perfil padrão

O identificador interno do perfil padrão é sempre default — ele não pode ser renomeado de verdade, porque ~/.hermes é a raiz da instalação. Renomeá-lo define, na prática, um nome de exibição, que as interfaces mostram no lugar do identificador:

hermes profile rename default Harumesu   # Unicode funciona: 小助手

O nome de exibição aparece em hermes profile list e show, no comando /profile, no painel e no aplicativo desktop (inclusive na lista do Bot Mode). É só apresentação: -p default, nomes de serviço, tarefas de cron e todas as outras referências continuam usando o identificador canônico default. Ele fica gravado como display_name em ~/.hermes/profile.yaml; apague essa linha para voltar. Perfis com nome também podem ter um display_name (que sobrevive a uma renomeação de verdade), mas nesses o rename continua renomeando o perfil em si.

Apagar um perfil

hermes profile delete coder

Isso para o gateway, remove o serviço do systemd/launchd, remove o comando e apaga todos os dados do perfil. Você vai precisar digitar o nome do perfil para confirmar.

Use --yes para pular a confirmação: hermes profile delete coder --yes.

observação

Não dá para apagar o perfil padrão (~/.hermes). Para remover tudo, use hermes uninstall.

Autocompletar no shell

# Bash
eval "$(hermes completion bash)"

# Zsh
eval "$(hermes completion zsh)"

Acrescente a linha ao seu ~/.bashrc ou ~/.zshrc para o autocompletar ficar permanente. Ele completa nomes de perfil depois do -p, os subcomandos de perfil e os comandos de topo.

Como funciona por dentro

Perfis usam a variável de ambiente HERMES_HOME. Quando você roda coder chat, o script define HERMES_HOME=~/.hermes/profiles/coder antes de abrir o hermes. Como mais de 119 arquivos do código resolvem caminhos por get_hermes_home(), o estado do Hermes passa a viver no diretório do perfil sozinho — configuração, sessões, memória, skills, banco de estado, PID do gateway, logs e tarefas de cron.

Isso é separado do diretório de trabalho do terminal. A execução de ferramentas começa em terminal.cwd (ou no diretório de abertura, quando cwd: "." no backend local), não automaticamente no HERMES_HOME.

Em instalações no próprio sistema, os subprocessos de ferramenta mantêm o HOME real do seu usuário por padrão, para as credenciais de CLI que já existem em ~ continuarem funcionando em todos os perfis. O isolamento dos dados do perfil vem do HERMES_HOME, não de mudar o HOME. Backends de container continuam usando {HERMES_HOME}/home para estado persistente de ferramenta, e quem precisa de configuração de ferramenta estritamente separada por perfil pode optar por terminal.home_mode: profile.

Isso significa duas coisas fáceis de confundir:

• HERMES_HOME é a fronteira do perfil. Ele controla a configuração do Hermes, o .env, a memória, as sessões, as skills, os logs, as tarefas de cron, o estado do gateway e os outros dados do Hermes.
• HOME é o diretório do usuário no sistema operacional, que as CLIs externas esperam. Em instalações no próprio sistema, o Hermes o mantém como o diretório real por padrão, para ferramentas como git, ssh, gh, az, npm, Claude Code e Codex encontrarem as mesmas credenciais que usam no seu shell normal.

O custo é que, por padrão, os perfis compartilham o estado de CLI no nível do usuário. Se você precisa de identidades separadas por perfil, defina terminal.home_mode: profile no config.yaml daquele perfil. Nesse modo o Hermes abre os subprocessos com HOME={HERMES_HOME}/home; aí você precisa criar ou ligar, dentro do diretório do perfil, o ~/.ssh, o ~/.gitconfig, o ~/.config/gh, as autenticações das CLIs de nuvem, as do Claude e do Codex, o estado do npm e arquivos parecidos.

O Hermes também expõe o HERMES_REAL_HOME aos subprocessos, para os scripts ainda encontrarem o diretório real da conta quando o home_mode: profile estiver ativo.

O perfil padrão é simplesmente o próprio ~/.hermes. Não é preciso migrar nada — instalações existentes funcionam igual.

Compartilhar um perfil

Um perfil que você montou numa máquina pode ir para outra — sua própria estação, o notebook de um colega, ou a comunidade. Dois caminhos:

Mandar um arquivo. O /export empacota o perfil num .tar.gz — skills, memória, persona, tarefas de cron, plugins, configurações e, no desktop, o tema e o layout. As chaves de API são removidas. Quem recebe roda o /import.

# Na conversa, rode /export, entregue o arquivo, e a pessoa roda /import nele
hermes profile export coder
hermes profile import ./coder.tar.gz --name coder

Publicar uma distribuição. Empacote o perfil como repositório git, para quem recebe instalar com um comando e puxar atualizações versionadas depois. Leva o SOUL, a configuração, as skills, as tarefas de cron e as conexões MCP; credenciais, memórias e sessões ficam em cada máquina.

# Instalar um agente inteiro de um repositório git
hermes profile install github.com/voce/research-bot --alias

# Atualizar depois, quando o autor publicar uma versão nova (mantém memórias e .env)
hermes profile update research-bot

Use um arquivo de exportação para uma entrega única ou uma mudança de máquina; use uma distribuição para um agente que você vai continuar publicando. Veja Distribuir um Agente Inteiro para os dois — a tabela de comparação, a autoria, a publicação, a semântica de atualização e o modelo de segurança.