Share Hermes Agents with Profile Distributions

A profile distribution packages an agent's authored behavior—such as its personality, skills, configuration, cron definitions, and MCP connections—as a Git repository. Installers can update that agent while keeping their own credentials, memories, sessions, and runtime state.

Official documentation: https://hermes-agent.nousresearch.com/docs/user-guide/profile-distributions

Authoring checklist

[ ] Start from a working, tested profile.
[ ] Add a clear distribution.yaml with name, version, requirements, and environment-variable descriptions.
[ ] Create .gitignore before the first git add.
[ ] Exclude .env, auth files, memories, sessions, logs, state databases, caches, workspaces, and local overrides.
[ ] Review skills, MCP transports, and cron definitions as executable trust surfaces.
[ ] Tag stable releases and write human-facing setup notes.
[ ] Install from a local directory into a disposable test profile before publishing.
[ ] Inspect the repository itself for secrets before pushing.

Ownership boundaries

Distribution-owned files can be replaced on update, while user-owned state stays on the installer's machine. Configuration is preserved by default unless the installer deliberately forces the distribution's version. The local/ namespace is appropriate for installer-specific overrides that should never be replaced.

Installer hard-exclusions reduce accidental copying during install and update, but they do not protect an author who commits private files to Git. Repository hygiene remains the author's responsibility.

Trust and cron behavior

A distribution is software, not just a prompt pack. Review the source and history before installing. Skills and the personality file become active when the profile runs. Distributed cron definitions are not automatically scheduled; operators should inspect and explicitly enable the jobs they want.

Pitfalls

Committing a live profile before adding .gitignore.
Assuming installer exclusions remove secrets from the author's Git history.
Publishing local memories or sessions as “helpful defaults.”
Forcing config updates and overwriting the installer's model or provider choices.
Enabling distributed cron jobs without reviewing delivery targets and permissions.
Treating profiles as filesystem sandboxes; they isolate state, not host access.

Verification steps

Scan the staged repository for secret-like values and runtime files.
Install the distribution into a disposable profile from the local source.
Confirm required environment variables are documented but not populated.
Run one safe chat and one read-only tool workflow.
Inspect cron definitions without enabling them automatically.
Update the test install and confirm its memories, sessions, credentials, and local overrides remain intact.
Tag and publish only after the disposable installation passes.