--- name: hermes-minimal-profile-setup description: 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.). version: 1.0.0 author: Hermes Agent license: MIT platforms: [linux] metadata: hermes: tags: [hermes, profile, configuration, api-server, open-webui, minimal] related_skills: [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 ```bash mkdir -p /home/n8n/workspace/ ``` 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 ```bash hermes profile create --clone-from ``` This copies config.yaml, .env, skills/, and all other profile state from the source. ### 3. Update terminal.cwd ```bash hermes -p config set terminal.cwd /home/n8n/workspace/ ``` ### 4. Set up API server env vars (if this is an API server profile) Edit `~/.hermes/profiles//.env`: ```bash API_SERVER_ENABLED=true API_SERVER_PORT= # pick a port that doesn't conflict with other profiles API_SERVER_KEY= # generate: python3 -c "import secrets; print(secrets.token_urlsafe(32))" API_SERVER_MODEL_NAME="Hermes Agent ()" ``` **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//config.yaml`. Under `platform_toolsets.cli`, reduce to only what's needed. **Minimal API server set** (what Open WebUI needs): ```yaml 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//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: ```python 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: ```bash cd ~/.hermes/profiles//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: ```bash hermes -p doctor # If it flags HERMES_MAX_ITERATIONS or similar: sed -i '/^HERMES_MAX_ITERATIONS=/d' ~/.hermes/profiles//.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: ```bash # MEMORY.md — behavioral directives cat > ~/.hermes/profiles//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/`. 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//memories/USER.md << 'EOF' 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 ```bash # Profile registration hermes -p profile show # Config parses python3 -c "import yaml; yaml.safe_load(open('$HOME/.hermes/profiles//config.yaml')); print('YAML OK')" # Toolsets match hermes -p tools list # Health check hermes -p doctor # Skills count hermes -p profile show | 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 : 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//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: ```bash cd ~/.hermes/profiles/ 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 profile show ` shows correct model, skills count - [ ] `hermes -p tools list` shows only intended toolsets enabled - [ ] `hermes -p 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.