hermes-skills/hermes-minimal-profile-setup/SKILL.md

name, description, version, author, license, platforms, metadata

name	description	version	author	license	platforms	metadata
hermes-minimal-profile-setup	Create a minimal Hermes profile cloned from an existing one, trimmed to only the tools, MCP servers, and skills needed for a specific backend role (API server, Open WebUI, gateway-only, etc.).	1.0.0	Hermes Agent	MIT	linux	hermes tags related_skills hermes profile configuration api-server open-webui minimal hermes-agent hermes-webui-docker

Hermes Minimal Profile Setup

Create a new Hermes profile cloned from an existing one, then trim it down to only the tools, MCP servers, and skills needed for a specific backend role — e.g., an API server backend for Open WebUI, a gateway-only profile, or a headless worker.

When to Use

• Setting up a Hermes API server profile for Open WebUI or another frontend
• Creating a gateway-only profile with no terminal/file access
• Spinning up a worker profile with a focused toolset
• Any scenario where you want a profile with fewer tools/skills than the source

Workflow

1. Create workspace folder

mkdir -p /home/n8n/workspace/<name>

Create an AGENTS.md in the workspace describing the profile's purpose. This gets injected into the system prompt when the profile runs from that directory.

Include the Plan-Before-Build Rule in the AGENTS.md under a ## Conventions section. The canonical text lives in any existing profile's AGENTS.md (e.g., /home/n8n/workspace/dev/AGENTS.md). Copy the ### Plan-Before-Build Rule block verbatim. Exception: Open WebUI API server profiles (open1, openz, open_guest) intentionally omit this rule — they're minimal-toolset profiles where plan enforcement adds friction without benefit.

2. Clone the profile

hermes profile create <name> --clone-from <source>

This copies config.yaml, .env, skills/, and all other profile state from the source.

3. Update terminal.cwd

hermes -p <name> config set terminal.cwd /home/n8n/workspace/<name>

4. Set up API server env vars (if this is an API server profile)

Edit ~/.hermes/profiles/<name>/.env:

API_SERVER_ENABLED=true
API_SERVER_PORT=<port>          # pick a port that doesn't conflict with other profiles
API_SERVER_KEY=<random-key>     # generate: python3 -c "import secrets; print(secrets.token_urlsafe(32))"
API_SERVER_MODEL_NAME="Hermes Agent (<name>)"

Port selection: check what other profiles use to avoid conflicts. The dev profile default is 8642. Increment or pick a unique port.

5. Trim toolsets to minimal

Edit ~/.hermes/profiles/<name>/config.yaml. Under platform_toolsets.cli, reduce to only what's needed.

Minimal API server set (what Open WebUI needs):

platform_toolsets:
  cli:
  - web
  - memory
  - session_search
  - terminal
  - file
  - skills
  - todo
  - clarify

Remove (not needed for API server role): browser, delegation, cronjob, vision, image_gen, code_execution, tts, video, video_gen, x_search, context_engine, homeassistant, spotify, computer_use, yuanbao.

6. Trim MCP servers

Edit ~/.hermes/profiles/<name>/config.yaml. Under mcp_servers, keep only what's needed.

Minimal set: usually just searxng for web search. Remove nuntius-mcp, playwright, better-qdrant, and any others.

Pitfall: regex-based stripping of YAML sections is fragile. Use a Python script instead:

import yaml
with open('config.yaml') as f:
    c = yaml.safe_load(f)
# Keep only searxng
c['mcp_servers'] = {k: v for k, v in c['mcp_servers'].items() if k == 'searxng'}
with open('config.yaml', 'w') as f:
    yaml.dump(c, f, default_flow_style=False)

7. Trim skills

Remove all skill directories except the essentials:

cd ~/.hermes/profiles/<name>/skills
# Keep only hermes-agent and searxng-smart-search
find . -mindepth 1 -maxdepth 1 -type d | while read cat; do
  case "$cat" in
    ./autonomous-ai-agents)
      for sub in "$cat"/*/; do
        case "$sub" in
          ./autonomous-ai-agents/hermes-agent/) ;;
          *) rm -rf "$sub" ;;
        esac
      done
      ;;
    ./mcp)
      for sub in "$cat"/*/; do
        case "$sub" in
          ./mcp/searxng-smart-search/) ;;
          *) rm -rf "$sub" ;;
        esac
      done
      ;;
    *) rm -rf "$cat" ;;
  esac
done

8. Clean up stale env vars

The cloned .env may have vars that shadow config.yaml settings. Remove any that the doctor flags:

hermes -p <name> doctor
# If it flags HERMES_MAX_ITERATIONS or similar:
sed -i '/^HERMES_MAX_ITERATIONS=/d' ~/.hermes/profiles/<name>/.env

9. Seed holographic memory files

After cleaning stale runtime artifacts, the memories/ directory will be empty. Create seed files so the profile has working memory from first use:

# MEMORY.md — behavioral directives
cat > ~/.hermes/profiles/<name>/memories/MEMORY.md << 'EOF'
MEMORY.md is for behavioral directives and environment conventions only. All factual claims about people, projects, and entities go to fact_store. Get explicit permission before modifying MEMORY.md or USER.md.
§
Stay in `~/workspace/<name>`. No cross-profile access without explicit direction.
§
Always do a web search to get details on any changes or software modified, updated, or created. Never say "I don't know" if a web search has not been performed.
EOF

# USER.md — who the user is (customize per persona)
cat > ~/.hermes/profiles/<name>/memories/USER.md << 'EOF'
<persona description — who they are, how they access Hermes, any relevant details>
EOF

The memory_store.db auto-creates on first use — no manual creation needed. The holographic provider (memory.provider: holographic) and hermes-memory-store.auto_extract: true are inherited from the clone source and should already be correct.

10. Verify

# Profile registration
hermes -p <name> profile show <name>

# Config parses
python3 -c "import yaml; yaml.safe_load(open('$HOME/.hermes/profiles/<name>/config.yaml')); print('YAML OK')"

# Toolsets match
hermes -p <name> tools list

# Health check
hermes -p <name> doctor

# Skills count
hermes -p <name> profile show <name> | grep Skills

11. Peer validation (recommended)

Delegate to a peer Hermes for independent validation of the full setup. See ask-hermes skill for the pattern. The peer should:

• Read the config.yaml, .env, AGENTS.md, and the original plan document
• Run actual commands (not guess): YAML parse, tools list, profile show, filesystem checks
• Verify each change against the intended design
• Return a structured PASS/FAIL report with evidence

Example peer prompt structure:

Validate profile <name>: read config.yaml, .env, AGENTS.md, and the plan doc.
Check: terminal.cwd, API server env vars, port uniqueness, toolsets, MCP servers,
skills, YAML parse, model/provider, workspace existence.
Run actual commands for each check. Return PASS/FAIL with evidence.

Common Pitfalls

1. --clone-from DOES copy hindsight/config.json but with the SOURCE's bank_id. The clone copies the full hindsight/ directory including config.json. After cloning, you MUST change bank_id in ~/.hermes/profiles/<name>/hindsight/config.json from the source's bank (e.g., hermes-open1) to the new profile's bank (e.g., hermes-open_guest). If you skip this, the new profile silently writes memories to the source's bank — a cross-profile bank_id leak. Also apply bank-level settings (retain_extraction_mode, missions, disposition) via the daemon API PATCH endpoint — these are NOT in config.json. The bank auto-creates on first use; no explicit creation step is needed.

2. Regex stripping YAML is fragile. The MCP servers and toolsets sections have nested structure that simple sed/awk can't handle reliably. Use Python with PyYAML instead.

3. Stale HERMES_MAX_ITERATIONS in .env. When cloning from a profile that had this set, it shadows config.yaml and the doctor will flag it. Remove it.

4. Skills directory structure. Skills are organized as category/name/SKILL.md. When trimming, remove entire category directories except the ones you're keeping, then remove unwanted subdirectories from kept categories.

5. Port conflicts. Always check what ports other profiles use before assigning. The dev default is 8642.

6. Model/provider inheritance. The cloned profile inherits the source's model and provider. Verify these are correct for the new profile's role — especially base_url if the source used a non-standard endpoint.

7. Runtime artifacts from clone. The clone copies state.db, response_store.db, gateway_state.json, logs/, cache/, cron locks, and other runtime artifacts from the source. These must be cleaned before first use or the profile will carry stale state. Clean with:

cd ~/.hermes/profiles/<name>
rm -f state.db state.db-wal state.db-shm response_store.db response_store.db-wal response_store.db-shm verification_evidence.db gateway_state.json gateway.pid gateway.lock .hermes_history interrupt_debug.log .update_check .skills_prompt_snapshot.json context_length_cache.yaml ollama_cloud_models_cache.json models_dev_cache.json cron/.tick.lock cron/.jobs.lock cron/ticker_heartbeat cron/ticker_last_success 2>/dev/null
rm -rf cache/ logs/ 2>/dev/null
# Also clean stale memory files cloned from source
rm -f memory_store.db memory_store.db-wal memory_store.db-shm 2>/dev/null
rm -f memories/MEMORY.md memories/USER.md 2>/dev/null

Verification Checklist

• Workspace folder exists with AGENTS.md
• hermes -p <name> profile show <name> shows correct model, skills count
• hermes -p <name> tools list shows only intended toolsets enabled
• hermes -p <name> doctor passes (or only non-blocking warnings)
• YAML parses without errors
• API server env vars present and correct (if applicable)
• Port doesn't conflict with other profiles
• Memory seed files created (MEMORY.md, USER.md in memories/)
• Peer validation passed (if performed)

Support Files

• references/open1-session-example.md — Full session transcript of creating the open1 profile for Open WebUI, including exact config changes and peer validation output.