Building & Distributing Custom Hermes AI Agents with Profile Distributions

Learn how to package, version-control, and distribute custom Hermes AI agents using Profile Distributions without leaking private keys or session memories

Stop sending unorganized raw YAML files or copy-pasting massive system prompts into chat boxes.
When developing AI workflows locally, iteration often creates a messy mix of prompt tweaks, local tool dependencies, private session logs, and environment credentials. Sharing this raw setup with collaborators is error-prone and poses serious security risks.
In this tutorial, we will explore Hermes Profile Distributions—a clean framework for bundling an agent's identity (SOUL.md), bespoke abilities (skills/), and defaults (config.yaml) into a single, version-controlled repository.

🎯 What Makes an Agent "Shareable"?

Instead of sharing runtime state or hardcoded keys, a Profile Distribution creates a clean boundary between authored instructions (what you build) and runtime memory (what the end user owns).

   ┌─────────────────────────────────────────────────────────────────┐
   │                     Hermes Profile Package                      │
   │                                                                 │
   │   ┌───────────────┐   ┌───────────────┐   ┌─────────────────┐   │
   │   │    SOUL.md    │   │  skills/*.md  │   │distribution.yaml│   │
   │   │  (Identity)   │   │  (Tools/APIs) │   │   (Manifest)    │   │
   │   └───────────────┘   └───────────────┘   └─────────────────┘   │
   └───────────────────────────────┬─────────────────────────────────┘
                                   │
                         Git Remote Host (GitHub)
                                   │
                                   ▼
                   `hermes profile install <repo>`
                                   │
                  ┌────────────────┴────────────────┐
                  │      User's Local Machine       │
                  │  (Isolated Session & Memories)  │
                  └─────────────────────────────────┘

When users pull down your agent profile using the Hermes CLI, it clones the core template and initializes an isolated local environment on their machine without touching their existing profiles or private memory stores.

🛠️ Step-by-Step Guide

Step 1: Set Up Your Profile Directory

Start by creating a clean profile space for your project using the Hermes CLI:

hermes profile create my-first-agent

Navigate to ~/.hermes/profiles/my-first-agent/. This directory forms the core DNA of your agent:

~/.hermes/profiles/my-first-agent/
├── SOUL.md              # Core persona, rules & system prompt
├── distribution.yaml    # Package manifest and metadata
├── config.yaml          # Model parameters & defaults
├── .gitignore           # Shield file to block memory leaks
└── skills/              # Modular capabilities
    └── paper_search.md  # Custom tool instructions

Drafting SOUL.md

Your SOUL.md defines who your agent is and how it behaves. Here is an example template for a research assistant:

# Identity
You are "PaperGhost", an elite academic paper summarizer.

# Directives
- Focus on key methodologies, benchmarks, and dataset citations.
- Output summaries in concise markdown bullet points.
- Never invent citations. Use the paper_search skill when context is missing.

Step 2: Prepare the Distribution Manifest & Secret Isolation

Create a distribution.yaml file in the root of your profile directory. This manifest tells Hermes how to identify, label, and install your agent package.

# distribution.yaml - Package Manifest
name: "my-first-agent"
version: "1.0.0"
description: "A high-precision research assistant trained for academic paper synthesis"
author: "Digital Ghost Studio"
license: "MIT"
min_hermes_version: "0.8.2"

⚠️ CRITICAL SECURITY STEP: Never commit runtime databases, active chat sessions, or credential files.

Add a strict .gitignore to the root of your profile before committing:

# Hermes Local Runtime Data - DO NOT COMMIT
memories/
sessions/
*.db
*.log
.env
keys.yaml

Step 3: Publish to Git

Hermes natively resolves distributions via standard Git remotes (GitHub, GitLab, Gitea, or self-hosted remotes).
Initialize your repository and publish your release:

# Navigate to your profile directory
cd ~/.hermes/profiles/my-first-agent

# Initialize Git and commit your files
git init
git add .
git commit -m "feat: initial agent release v1.0.0"

# Link your remote repository and push
git remote add origin https://github.com/your-username/my-first-agent.git
git branch -M main
git push -u origin main

# Tag a release version
git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

Step 4: How Others Will Use It

Anyone with Hermes installed can now pull down and install your agent in seconds:

hermes profile install github.com/your-username/my-first-agent --alias paper-agent

The --alias flag maps the remote profile to a concise local keyword. End users can now invoke your agent directly from their terminal:

hermes --profile paper-agent "Summarize the latest arXiv paper on transformer attention layers"

🛡️ Key Rules & Best Practices

1. User Memory is Sacred: When an end-user updates your agent via Git (hermes profile update), Hermes performs a non-destructive merge. The user's accumulated session history and vector memories remain untouched.
2. Keep It Lean: Focus on a well-defined SOUL.md and 1–2 robust skills for your initial release. Avoid hardcoding rigid API settings unless strictly required.
3. Use Semantic Versioning: Always tag your releases (v1.0.0, v1.1.0). This enables downstream users and CI pipelines to pin their agent behavior to exact version tags. ## 💬 What are you building? Are you building CLI assistants, automated research agents, or continuous site monitors? Drop your repository links or ideas in the comments below! Originally published at digitalghost.blog.