Pular para o conteúdo principal

Documentação oficial desta página · v0.20.6

Distribuições de perfil: compartilhe um agente inteiro

Uma distribuição de perfil empacota um agente Hermes completo — personalidade, skills, tarefas de cron, conexões MCP, configuração — como um repositório git. Qualquer pessoa com acesso ao repositório instala o agente inteiro com um comando, atualiza no lugar e mantém intactas as próprias memórias, sessões e chaves de API.

Se um perfil é um agente local, uma distribuição é esse agente tornado compartilhável.

Dois jeitos de compartilhar um perfil​

O Hermes tem dois caminhos de compartilhamento, e eles respondem perguntas diferentes. Distribuições são o caminho duradouro; arquivos de export são o caminho rápido.

Distribuição (repositório git)Arquivo de export (.tar.gz)
Como entregahermes profile install <repo>Manda um arquivo — chat, AirDrop, pendrive, e-mail
O que a outra pessoa precisagit, e acesso ao repositórioO arquivo
Atualizaçõeshermes profile update puxa as versões novasReenviar o arquivo
VersionamentoTags, branches, SHAs de commitNenhum — é uma foto de um momento
Custo de preparo para o autordistribution.yaml + .gitignore + um repositórioNenhum — um comando
Leva juntoSOUL, config, skills, cron, MCP, pluginsO mesmo, mais o tema e o layout do desktop
Feito comhermes profile install / update/export e /import, ou hermes profile export / import

Escolha uma distribuição quando o agente é um produto que você vai continuar melhorando e outras pessoas devem acompanhar: o agente interno revisado de um time, um lançamento para a comunidade, o mesmo agente implantado em cinco máquinas.

Escolha um arquivo de export quando você só quer que alguém tenha a sua configuração agora, ou quando está mudando para um notebook novo. Sem repositório, sem manifesto — rode /export no chat, entregue o arquivo, a pessoa roda /import. Veja Exportar e importar um arquivo de perfil.

Os dois não são excludentes. Muitos autores usam o perfil no dia a dia, fazem /export para um colega dar uma segunda opinião e depois publicam como distribuição quando aquilo já merece versionamento.

O que isso significa​

Antes das distribuições, compartilhar um agente Hermes era mandar para alguém:

  1. O seu SOUL.md
  2. Uma lista de skills para instalar
  3. O seu config.yaml, sem os segredos
  4. Uma descrição de quais servidores MCP você tinha ligado
  5. Quaisquer tarefas de cron que você tinha agendado
  6. Instruções sobre quais variáveis de ambiente definir

…e torcer para a pessoa montar tudo direito. Cada nova versão ou correção de bug significava repetir a entrega.

Com distribuições, tudo isso mora em um repositório git:

my-research-agent/
├── distribution.yaml    # manifesto: nome, versão, variáveis de ambiente exigidas
├── SOUL.md              # a personalidade / prompt de sistema do agente
├── config.yaml          # modelo, temperatura, raciocínio, padrões de ferramentas
├── skills/              # skills empacotadas que vêm com o agente
├── cron/                # tarefas agendadas que o agente roda
└── mcp.json             # servidores MCP aos quais o agente se conecta

Quem recebe roda:

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

…e agora tem o agente inteiro. A pessoa preenche as próprias chaves de API (.env.EXAMPLE → .env) e pode rodar my-research-agent chat ou falar com ele pelo Telegram / Discord / Slack / qualquer plataforma de gateway. Quando você publica uma versão nova, ela roda hermes profile update my-research-agent e puxa as suas mudanças — as memórias e sessões dela ficam no lugar.

Por que git?​

Consideramos tarballs, arquivos por HTTP, um formato próprio. Nenhum superou o git:

  • Zero etapa de build para o autor. Empurre para o GitHub; quem consome instala. Não existe o ciclo "empacota isso, sobe aquilo, atualiza o índice".
  • Tags, branches e commits já são o sistema de versionamento. Empurrar uma tag faz por nós o que "empacotar + subir um release" faz em outras ferramentas.
  • Atualizar é um fetch. Não é rebaixar o arquivo inteiro de novo.
  • Transparente. As pessoas podem navegar pelo repositório, ler os diffs entre versões, abrir issues e fazer fork para customizar.
  • Repositórios privados funcionam de graça. Chaves SSH, helpers de git credential, credenciais guardadas pelo GitHub CLI — qualquer autenticação que o seu terminal já tenha configurada vale de forma transparente.
  • Reprodutibilidade é um SHA de commit. A mesma coisa que pip e npm registram.

O custo: quem recebe precisa ter git instalado. Em qualquer máquina rodando Hermes em 2026, isso já é verdade.

Quando usar uma distribuição?​

Encaixa bem:

  • Você está compartilhando um agente especializado — um monitor de compliance, um revisor de código, um assistente de pesquisa, um bot de suporte — com um time ou com a comunidade.
  • Você está implantando o mesmo agente em várias máquinas e não quer copiar arquivos na mão toda vez.
  • Você está iterando em um agente e quer que as pessoas peguem as versões novas com um comando.
  • Você está construindo um agente como produto — padrões opinativos, skills curadas, prompts afinados — que outras pessoas devem usar como ponto de partida.

Não encaixa:

  • Você quer entregar a sua configuração para alguém uma vez, agora. Uma distribuição precisa de repositório, manifesto e .gitignore. O /export não precisa de nada disso — veja Exportar e importar um arquivo de perfil. Vale o mesmo para fazer backup ou mudar um perfil para outra máquina.
  • Você quer compartilhar o tema e o layout do seu desktop. Uma distribuição leva o agente — SOUL, config, skills, cron, MCP, plugins. Um export feito pelo app desktop leva também a aparência: skin, modo claro/escuro, temas customizados, cor da barra lateral e layout da janela.
  • Você quer compartilhar chaves de API junto com o agente. auth.json e .env são excluídos de propósito das distribuições. Cada pessoa que instala traz as próprias credenciais. (Arquivos de export também os removem.)
  • Você quer compartilhar memórias / sessões / histórico de conversa. Isso é dado do usuário, não conteúdo de distribuição. Nunca é enviado. (Arquivos de export são diferentes nesse ponto — leia o que vai dentro de um arquivo de export antes de mandar um.)
cuidado

O Hermes não controla o git. As exclusões de arquivo descritas nesta página são aplicadas pelo instalador, quando alguém roda hermes profile install ou hermes profile update. Elas não são aplicadas quando você roda git add ou git commit.

O ciclo de vida: do autor a quem instala, e daí à atualização​

Abaixo está o fluxo completo, de ponta a ponta. Escolha o lado que interessa a você.

Para autores: publicar uma distribuição​

Passo 1 — Comece de um perfil que funciona​

Construa e refine o agente como qualquer outro perfil:

hermes profile create research-bot
research-bot setup                    # configura modelo e chaves de API
# Edite ~/.hermes/profiles/research-bot/SOUL.md
# Instale skills, ligue servidores MCP, agende tarefas de cron etc.
research-bot chat                     # use no dia a dia até ficar bom

Passo 2 — Adicione um distribution.yaml​

Crie ~/.hermes/profiles/research-bot/distribution.yaml:

name: research-bot
version: 1.0.0
description: "Assistente de pesquisa autônomo com ferramentas de arXiv e web"
hermes_requires: ">=0.12.0"
author: "Seu Nome"
license: "MIT"

# Diga a quem instala de quais variáveis de ambiente o agente precisa. Elas são
# conferidas contra o shell de quem instala e contra o .env existente, para a
# pessoa não ser cobrada por chaves que ela já tem configuradas.
env_requires:
  - name: OPENAI_API_KEY
    description: "Chave de API da OpenAI (para acesso ao modelo)"
    required: true
  - name: SERPAPI_KEY
    description: "Chave da SerpAPI para busca na web"
    required: false
    default: ""

O manifesto é só isso. Todo campo, menos name, tem um padrão razoável.

Passo 3 — Crie um .gitignore antes do primeiro commit​

aviso

Faça isso antes de rodar git init ou git add. Se você já conversou com o perfil, rodou o setup ou usou o perfil de qualquer forma, o diretório agora tem arquivos que você não pode enviar: .env, auth.json, memories/, sessions/, state.db*, logs/ e mais.

Crie ~/.hermes/profiles/research-bot/.gitignore com, no mínimo:

# Credenciais e segredos — NUNCA versione
auth.json
.env
.env.EXAMPLE    # gerado na instalação, não é domínio do autor

# Bancos de dados e estado de execução
state.db
state.db-shm
state.db-wal
hermes_state.db
response_store.db
response_store.db-shm
response_store.db-wal
gateway.pid
gateway_state.json
processes.json
auth.lock
active_profile
.update_check

# Dados do usuário — NUNCA versione
memories/
sessions/
logs/
plans/
workspace/
home/

# Caches e artefatos gerados
image_cache/
audio_cache/
document_cache/
browser_screenshots/
cache/

# Infraestrutura (não deveria estar no diretório do perfil, mas é seguro excluir)
hermes-agent/
.worktrees/
profiles/
bin/
node_modules/

# Espaço de customização do usuário — seus overrides locais
local/

# Checkpoints e backups (podem ser enormes)
checkpoints/
sandboxes/
backups/

# Logs
errors.log
.hermes_history

Isso espelha os caminhos excluídos na marra que o instalador remove do lado dele. Qualquer outra coisa que você queira manter fora do repositório (arquivos de rascunho, arquivos grandes, skills só locais) também deve entrar aqui.

Passo 4 — Publique num repositório git​

cd ~/.hermes/profiles/research-bot
git init
git add .
git commit -m "v1.0.0"
git remote add origin git@github.com:voce/research-bot.git
git tag v1.0.0
git push -u origin main --tags

O repositório agora é uma distribuição. Qualquer pessoa com acesso pode instalar.

observação

O instalador ainda vai remover por conta própria os caminhos excluídos na marra, mesmo que um autor de alguma forma os envie — mas isso protege só quem instala, não o autor.

Passo 5 — Marque releases versionados​

Toda vez que o agente chegar a um ponto estável, suba a versão e crie a tag:

# Edite distribution.yaml: version: 1.1.0
git add distribution.yaml SOUL.md skills/
git commit -m "v1.1.0: SOUL de pesquisa mais enxuto, adiciona skill arxiv"
git tag v1.1.0
git push --tags

Quem rodar hermes profile update research-bot vai puxar a versão mais recente.

Como fica o repositório​

Uma distribuição completa, do lado do autor:

research-bot/
├── .gitignore                   # exclui segredos e dados do usuário (veja o Passo 3)
├── distribution.yaml            # obrigatório
├── SOUL.md                      # fortemente recomendado
├── config.yaml                  # modelo, provedor, padrões de ferramentas
├── mcp.json                     # conexões com servidores MCP
├── skills/
│   ├── arxiv-search/SKILL.md
│   ├── paper-summarization/SKILL.md
│   └── citation-lookup/SKILL.md
├── cron/
│   └── weekly-digest.json       # tarefas agendadas
└── README.md                    # descrição para humanos (opcional)

O que é da distribuição e o que é do usuário​

Quando alguém atualiza para uma versão nova, algumas coisas são substituídas (domínio do autor) e outras ficam no lugar (domínio de quem instalou). Os padrões:

CategoriaCaminhosNa atualização
Da distribuiçãoSOUL.md, config.yaml, mcp.json, skills/, cron/, distribution.yamlSubstituídos a partir do clone novo
Exceção da configconfig.yamlNa prática é preservado por padrão — quem instalou pode ter ajustado modelo ou provedor. Passe --force-config na atualização para resetar.
Do usuáriomemories/, sessions/, state.db*, auth.json, .env, logs/, workspace/, plans/, home/, *_cache/, local/Nunca são tocados

Você pode sobrescrever a lista do que é da distribuição no manifesto:

distribution_owned:
  - SOUL.md
  - skills/research/            # só as minhas skills de pesquisa; as outras instaladas ficam
  - cron/digest.json

Quando você omite, valem os padrões acima — que é o que a maioria das distribuições quer.

Para quem instala: usando uma distribuição​

Instalar​

hermes profile install github.com/voce/research-bot --alias

O que acontece:

  1. Clona o repositório num diretório temporário.
  2. Lê o distribution.yaml e mostra o manifesto (nome, versão, descrição, autor, variáveis de ambiente exigidas).
  3. Confere cada variável de ambiente exigida contra o ambiente do seu shell e contra o .env existente do perfil de destino. Marca cada uma como ✓ set ou needs setting, para você saber exatamente o que configurar.
  4. Pede confirmação. Passe -y / --yes para pular.
  5. Copia os arquivos da distribuição para ~/.hermes/profiles/research-bot/ (ou para onde o name do manifesto apontar). Os caminhos excluídos na marra são removidos durante essa cópia, mesmo que o autor tenha deixado eles no repositório sem querer.
  6. Escreve um .env.EXAMPLE com as chaves exigidas comentadas — copie para .env e preencha.
  7. Com --alias, cria um wrapper para você poder rodar research-bot chat direto.

Tipos de origem​

Qualquer URL de git funciona:

# Atalho do GitHub
hermes profile install github.com/voce/research-bot

# HTTPS completo
hermes profile install https://github.com/voce/research-bot.git

# SSH
hermes profile install git@github.com:voce/research-bot.git

# Auto-hospedado, GitLab, Gitea, Forgejo — qualquer host Git
hermes profile install https://git.exemplo.com/time/research-bot.git

# Repositório privado usando a autenticação git que você já configurou
hermes profile install git@github.com:sua-org/internal-bot.git

# Diretório local durante o desenvolvimento (sem precisar de git push)
hermes profile install ~/meu-perfil-em-andamento/

Trocar o nome do perfil​

Duas pessoas querendo a mesma distribuição com nomes de perfil diferentes:

# Alice
hermes profile install github.com/acme/support-bot --name support-us --alias
# Bob (mesma distribuição, nome local diferente)
hermes profile install github.com/acme/support-bot --name support-eu --alias

Preencher as variáveis de ambiente​

Depois da instalação, o perfil do agente contém um .env.EXAMPLE:

# Environment variables required by this Hermes distribution.
# Copy to `.env` and fill in your own values before running.

# OpenAI API key (for model access)
# (required)
OPENAI_API_KEY=

# SerpAPI key for web search
# (optional)
# SERPAPI_KEY=

Copie o arquivo:

cp ~/.hermes/profiles/research-bot/.env.EXAMPLE ~/.hermes/profiles/research-bot/.env
# Edite o .env e cole as suas chaves de verdade

Chaves exigidas que já estavam no ambiente do seu shell (por exemplo, OPENAI_API_KEY exportada no seu ~/.zshrc) aparecem como ✓ set durante a instalação — você não precisa duplicar elas no .env.

Conferir o que você instalou​

hermes profile info research-bot

Mostra:

Distribution: research-bot
Version:      1.0.0
Description:  Autonomous research assistant with arXiv and web tools
Author:       Your Name
Requires:     Hermes >=0.12.0
Source:       https://github.com/you/research-bot
Installed:    2026-05-08T17:04:32+00:00

Environment variables:
  OPENAI_API_KEY (required) — OpenAI API key (for model access)
  SERPAPI_KEY (optional) — SerpAPI key for web search

O hermes profile list também mostra uma coluna Distribution, para você ver de relance quais dos seus perfis vieram de repositórios e quais você montou na mão:

 Profile          Model                        Gateway      Alias        Distribution
 ───────────────    ───────────────────────────    ───────────    ───────────    ────────────────────
 ◆default         claude-sonnet-4              stopped      —            —
  coder           gpt-5                        stopped      coder        —
  research-bot    claude-opus-4                stopped      research-bot research-bot@1.0.0
  telemetry       claude-sonnet-4              running      telemetry    telemetry@2.3.1

Atualizar​

hermes profile update research-bot

O que acontece:

  1. Reclona o repositório a partir da URL de origem registrada.
  2. Substitui os arquivos que são da distribuição (SOUL, skills, cron, mcp.json).
  3. Preserva o seu config.yaml — você pode ter ajustado o modelo, a temperatura ou outras opções. Passe --force-config para sobrescrever.
  4. Nunca toca nos dados do usuário: memórias, sessões, autenticação, .env, logs, estado.

Sem rebaixar o arquivo inteiro de novo. Sem atropelar as suas mudanças locais na configuração. Sem apagar o seu histórico de conversa.

Remover​

hermes profile delete research-bot

O aviso de exclusão mostra as informações da distribuição antes de pedir confirmação:

Profile: research-bot
Path:    ~/.hermes/profiles/research-bot
Model:   claude-opus-4 (anthropic)
Skills:  12
Distribution: research-bot@1.0.0
Installed from: https://github.com/you/research-bot

This will permanently delete:
  • All config, API keys, memories, sessions, skills, cron jobs
  • Command alias (~/.local/bin/research-bot)

Type 'research-bot' to confirm:

Assim você nunca apaga um agente sem saber de onde ele veio nem sem conseguir reinstalar.

Casos de uso e padrões​

Pessoal: sincronizar um agente entre máquinas​

Você construiu um assistente de pesquisa no notebook. Quer o mesmo agente na estação de trabalho.

# Notebook — crie o .gitignore primeiro (veja o Passo 3 de "Para autores"), depois:
cd ~/.hermes/profiles/research-bot
git init && git add . && git status   # confirme que nenhum segredo entrou
git commit -m "inicial"
git remote add origin git@github.com:voce/research-bot.git
git push -u origin main

# Estação de trabalho
hermes profile install github.com/voce/research-bot --alias
# Preencha o .env. Pronto.

Qualquer iteração no notebook (git commit && push) chega na estação de trabalho com hermes profile update research-bot. As memórias ficam por máquina — o notebook lembra das conversas dele, a estação lembra das dela, e elas não se misturam.

Time: entregar um agente interno revisado​

Seu time de engenharia quer um bot de revisão de PR compartilhado, com um SOUL específico, skills específicas e um cron que passa todo PR por ele.

# Líder de engenharia — crie o .gitignore primeiro (veja o Passo 3 de "Para autores"), depois:
cd ~/.hermes/profiles/pr-reviewer
# ... construa e ajuste ...
git init && git add . && git status   # confirme que nenhum segredo entrou
git commit -m "v1.0 revisor de PR"
git tag v1.0.0
git push -u origin main --tags    # publique no host Git interno da empresa

# Cada pessoa do time
hermes profile install git@github.com:sua-org/pr-reviewer.git --alias
# Preencha o .env com a chave de API dela (cobrada nela); o .env.EXAMPLE aponta o que é exigido
pr-reviewer chat

Quando o líder publica a v1.1 (SOUL melhor, skill nova), o time roda hermes profile update pr-reviewer e todo mundo está na versão nova em minutos.

Comunidade: publicar um agente público​

Você construiu algo novo — talvez um "trader de Polymarket", um "resumidor de artigos acadêmicos" ou um "assistente de operação de servidor de Minecraft". Você quer compartilhar.

# Você — crie o .gitignore primeiro (veja o Passo 3 de "Para autores"), depois:
cd ~/.hermes/profiles/polymarket-trader
# Escreva um README.md decente na raiz do repositório — o GitHub mostra ele na página
git init && git add . && git status   # confirme que nenhum segredo entrou
git commit -m "v1.0"
git tag v1.0.0
# Publique num repositório público do GitHub
git remote add origin https://github.com/voce/hermes-polymarket-trader.git
git push -u origin main --tags

# Qualquer pessoa
hermes profile install github.com/voce/hermes-polymarket-trader --alias

Tuíte o comando de instalação. Quem experimentar vai te mandar issues e PRs. Se alguém quiser customizar, faz um fork — o mesmo fluxo git que todo mundo já conhece.

Produto: entregar um agente opinativo​

Você construiu algo em cima do Hermes — talvez um arcabouço de monitoramento de compliance, uma pilha de suporte ao cliente, uma plataforma de pesquisa de domínio específico. Você quer distribuir isso como produto.

# distribution.yaml
name: telemetry-harness
version: 2.3.1
description: "Arcabouço de telemetria de compliance — monitora e revisa fluxos regulados"
hermes_requires: ">=0.13.0"
author: "Acme Compliance Inc."
license: "Commercial"

env_requires:
  - name: ACME_API_KEY
    description: "Sua chave de licença da Acme Compliance (escreva para support@acme.com)"
    required: true
  - name: OPENAI_API_KEY
    description: "Chave de API da OpenAI para acesso ao modelo"
    required: true
  - name: GRAPHITI_MCP_URL
    description: "URL da sua instância do grafo de conhecimento Graphiti"
    required: false
    default: "http://127.0.0.1:8000/sse"

Seus clientes instalam com um único comando; a prévia da instalação diz exatamente quais chaves ter em mãos; as atualizações saem no momento em que você marca um release novo; e os dados de compliance deles (memories/, sessions/) nunca saem da máquina deles.

Efêmero: scripts pontuais em infra compartilhada​

Você é o líder de operações. Quer um agente temporário que diagnostique um incidente em produção — um SOUL pronto, com as ferramentas e as conexões MCP certas — rodando nos notebooks de três pessoas de plantão pela próxima semana.

# Você — crie o .gitignore primeiro (veja o Passo 3 de "Para autores"), depois:
# Construa o perfil, faça o commit e publique num repositório privado
git push -u origin main

# Cada pessoa de plantão
hermes profile install git@github.com:sua-org/incident-2026-q2.git --alias

# Incidente resolvido — desmonte
hermes profile delete incident-2026-q2

O ciclo instalar-apagar é barato o bastante para ser descartável.

Receitas​

Fixar uma versão específica​

observação

Fixar um ref do git (#v1.2.0) está planejado, mas não entrou no lançamento inicial — hoje a instalação acompanha a branch padrão. Acompanhe a versão instalada com hermes profile info <nome> e segure as atualizações até você estar pronto.

Ver em que versão você está, comparada à mais recente​

# A sua versão instalada
hermes profile info research-bot | grep Version

# A mais recente lá em cima (sem instalar)
git ls-remote --tags https://github.com/voce/research-bot | tail -5

Manter customizações locais de configuração entre atualizações​

O comportamento padrão da atualização já faz isso: o config.yaml é preservado. Para garantir, escreva os seus ajustes locais num arquivo que a distribuição não é dona:

# ~/.hermes/profiles/research-bot/local/meus-overrides.yaml
# (a distribuição nunca toca em local/)

…e referencie ele a partir do config.yaml ou do seu SOUL, conforme a necessidade.

Forçar uma reinstalação limpa​

# Destrua e reinstale do zero (perde memórias e sessões também)
hermes profile delete research-bot --yes
hermes profile install github.com/voce/research-bot --alias

# Atualize para a main atual, mas resete o config.yaml para o padrão da distribuição
hermes profile update research-bot --force-config --yes

Fazer fork e customizar​

É o fluxo git de sempre — distribuições são só repositórios:

# Faça fork do repositório no GitHub, depois instale o seu fork
hermes profile install github.com/seunome/forked-research-bot --alias

# Itere localmente em ~/.hermes/profiles/forked-research-bot/
# Edite o SOUL.md, faça commit, empurre para o seu fork
# Mudanças de cima: puxe para o seu fork do jeito de sempre

Testar uma distribuição antes de publicar​

Da máquina do autor:

# Instale a partir de um diretório local (sem precisar de git push)
hermes profile install ~/.hermes/profiles/research-bot --name research-bot-test --alias

# Ajuste, apague, reinstale até ficar do jeito certo
hermes profile delete research-bot-test --yes
hermes profile install ~/.hermes/profiles/research-bot --name research-bot-test

Exportar e importar um arquivo de perfil​

Quando você não precisa de versionamento, pule o repositório. O /export empacota um perfil num único .tar.gz; o /import desempacota como um perfil novo do outro lado. As credenciais são removidas na saída.

Exportar​

Na CLI, na TUI ou no chat do desktop:

/export                          # o perfil ativo → <nome>.tar.gz
/export research-bot             # um perfil pelo nome
/export research-bot -o ~/Desktop/research-bot.tar.gz

Ou pelo shell, com a mesma maquinaria:

hermes profile export research-bot
hermes profile export research-bot -o ./research-bot.tar.gz

No app desktop existem três portas, todas indo parar num diálogo nativo de salvar arquivo:

  • ⌘K → Export profile…
  • Clique com o botão direito num quadrado de perfil na barra lateral → Export profile…
  • O botão de importar ao lado do + da barra cobre o caminho inverso

Um export do desktop acrescenta um arquivo que a CLI não gera: o desktop.json, que leva a sua skin, o modo claro/escuro, quaisquer definições de tema customizado de que a skin precise, a cor da barra do perfil e o layout da sua janela. É por isso que um perfil compartilhado do desktop chega parecendo o seu, não só se comportando como o seu.

Importar​

/import ~/Downloads/research-bot.tar.gz
/import ~/Downloads/research-bot.tar.gz --name research-bot-2
hermes profile import ./research-bot.tar.gz
hermes profile import ./research-bot.tar.gz --name research-bot-2

O nome do perfil é inferido do arquivo, a menos que você passe --name. Importar por cima de um perfil existente é recusado — renomeie ou apague o antigo primeiro. Um wrapper de shell (research-bot → hermes -p research-bot) é criado quando o nome não colide com um comando existente.

Importar no app desktop também aplica a camada do desktop.json e te joga no perfil novo, num chat em branco. Importar pela CLI um arquivo feito no desktop não tem problema — o arquivo da camada visual vai junto para o disco e é aplicado na próxima vez que você abrir aquele perfil no desktop.

observação

Você não pode importar com o nome default — esse nome é o perfil raiz embutido (~/.hermes). Passe --name outra-coisa.

O que vai dentro de um arquivo de export​

Sempre excluídos, nos dois tipos de perfil: auth.json e .env. As suas chaves de API nunca saem da máquina.

O perfil padrão (~/.hermes) é exportado por uma lista de permissão — só artefatos conhecidos do Hermes, para que um arquivo qualquer parado no seu diretório de usuário não seja arrastado junto:

config.yaml, SOUL.md, MEMORY.md, USER.md, todo.json, system_prompt.md, AGENTS.md, CLAUDE.md, .cursorrules, skills/, plugins/, cron/, scripts/, sessions/, memories/, knowledge/, preferences/, e o desktop.json quando o desktop preparou um.

Um perfil nomeado (~/.hermes/profiles/<nome>) copia o diretório inteiro menos auth.json / .env. Isso é mais abrangente — se o perfil tem state.db, logs ou caches, eles também entram no arquivo, e ele fica grande.

Leia o seu arquivo antes de mandar

Um export é uma foto do seu perfil, não um release curado. Diferente de uma distribuição, ele pode incluir memories/, sessions/ e o USER.md — e nada varre skills, memórias ou a sua persona atrás de algo pessoal que você tenha escrito ali. As credenciais são filtradas pelo nome do arquivo; o conteúdo, não.

Antes de compartilhar com alguém, liste o que tem lá dentro:

tar -tzf research-bot.tar.gz | less

Se ele carrega histórico de conversa que você prefere não entregar, publique uma distribuição no lugar — distribuições nunca levam memórias nem sessões.

O que NUNCA vai numa distribuição (em hipótese alguma)​

O instalador exclui estes caminhos na marra, mesmo que um autor os envie sem querer. Nenhuma opção de configuração permite sobrescrever isso — essa proteção é um invariante coberto por testes de regressão:

  • auth.json — tokens OAuth, credenciais de plataforma
  • .env — chaves de API, segredos
  • memories/ — memória das conversas
  • sessions/ — histórico das conversas
  • state.db, state.db-shm, state.db-wal — metadados de sessão
  • logs/ — logs do agente e de erro
  • workspace/ — arquivos de trabalho gerados
  • plans/ — planos de rascunho
  • home/ — o diretório de usuário montado em backends Docker
  • *_cache/ — caches de imagem / áudio / documentos
  • local/ — espaço de customização reservado ao usuário

Quando você clona uma distribuição do lado de quem instala, isso simplesmente não é copiado para o seu diretório de perfil. Quando você atualiza, as suas cópias ficam no lugar. Se você instalou a mesma distribuição em cinco máquinas, você tem cinco conjuntos isolados desses dados — um por máquina.

cuidado

Essa exclusão roda no momento da instalação / atualização, na máquina de quem instala. Ela não impede um autor de versionar arquivos sensíveis ou desnecessários. Autores precisam usar um .gitignore para manter segredos fora do repositório.

Segurança e confiança​

Distribuições de perfil não são assinadas por padrão. Você está confiando:

  • No host git (GitHub / GitLab / onde for) para servir os bytes que o autor publicou.
  • No autor para não enviar um SOUL, skills ou tarefas de cron maliciosos.

Tarefas de cron vindas de uma distribuição não são agendadas automaticamente — o instalador imprime hermes -p <nome> cron list e você habilita elas explicitamente. O SOUL.md e as skills, sim, ficam ativos assim que você começa a conversar com o perfil, então leia eles antes da primeira execução se estiver instalando de alguém que você não conhece.

Uma analogia grosseira: instalar uma distribuição é como instalar uma extensão de navegador ou uma extensão do VS Code. Pouco atrito, muito poder, confie na origem. Para distribuições internas da empresa, use um repositório privado e a sua autenticação git normal — não há nada novo a configurar.

Versões futuras podem trazer assinatura, um lockfile (.distribution-lock.yaml) com um SHA de commit resolvido e uma flag --dry-run que imprime o diff antes de aplicar uma atualização. Nada disso está pronto ainda.

Por dentro​

Para detalhes de implementação, o comportamento exato da CLI e todas as flags, veja a referência de Comandos de Perfil.

A versão curta:

  • install, update e info vivem dentro de hermes profile — não numa árvore de comandos paralela.
  • O formato do manifesto é YAML, com um esquema obrigatório minúsculo (só name).
  • O instalador usa o binário git local para clonar, então qualquer autenticação que o seu shell já resolve (chaves SSH, credential helpers) funciona de forma transparente.
  • Depois do clone, o .git/ é removido — o perfil instalado não é ele mesmo um checkout git, o que evita a armadilha do "ai, meu Deus, versionei o meu .env sem querer no histórico git da distribuição".
  • Nomes de perfil reservados (hermes, test, tmp, root, sudo) são recusados na instalação, para evitar colisão com binários comuns.

Veja também​