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

---
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/<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

```bash
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

```bash
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`:

```bash
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):
```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/<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:

```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/<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:

```bash
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:

```bash
# 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

```bash
# 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:
```bash
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.