prose-contracts/hermes-config-template.prose.md

---
kind: template
name: hermes-config-template
description: >
  Standard Hermes configuration template for Syslog Solution LLC agents.
  Enforces shared infrastructure setup (Firecrawl, SearXNG, local models,
  RA-H OS MCP) while keeping model/provider choices flexible per agent role.
  Every new agent profile should start from this template.
---

## Maintains

- template_version: string — Current template version (e.g., "1.0.0")
- last_applied: timestamp — When any agent was last configured from this template
- agents_configured: array — Which agents/profiles were created from this template
- infra_endpoints_verified: array — Firecrawl, SearXNG, RA-H OS, LiteLLM endpoints last confirmed working
- known_deviations: array — Profiles that diverge from the template (and why)

## Parameters

- agent_name: string — Name of the agent/profile (e.g., "syslog-code", "syslog-devops")
- default_model: string — Agent's primary model (e.g., "qwen3.6-27B-code", "syslog-auto")
- default_provider: string — Inference provider for the primary model (default: "harness")
- fallback_model: string — Fallback model when primary is down (default: "gemma-4-12b")
- fallback_provider: string — Fallback provider (default: "harness")
- auxiliary_model: string — Model for vision/compression/extraction tasks (default: "gemma-4-12b")
- enable_firecrawl_searxng: boolean — Whether to configure web search/extract (default: true)
- enable_ra_h_os_mcp: boolean — Whether to wire up RA-H OS MCP bridge (default: true)
- enable_compression: boolean — Whether to enable context compression (default: true)
- custom_provider_name: string — Custom provider name (default: "harness")
- custom_provider_model: string — Custom provider model (default: same as default_model)
- custom_provider_url: string — LiteLLM base URL (default: "http://litellm.sysloggh.net/litellm/v1")
- extra_auxiliary: array — Additional auxiliary tasks to configure (vision, compression, etc.)
- output_dir: string — Where to write the config (default: "~/.hermes/profiles/<agent_name>/config.yaml")

## Quickstart — How to Run This Contract

### For the Agent Running This Contract

Read this section first. It tells you exactly what to do.

**When to run:**
- Setting up a **new agent profile** for the first time
- An **existing profile** is missing web search, firecrawl, or MCP configs
- User says: `"apply the config template"` or `"fix my infra config"`
- User says: `"configure <agent_name> with <model>"`

**How to run (via OpenProse CLI):**
```bash
# Minimal — only agent name required
prose run hermes-config-template agent_name=syslog-code

# Full control
prose run hermes-config-template \
  agent_name=syslog-devops \
  default_model=claude-sonnet-4 \
  auxiliary_model=gemma-4-12b \
  fallback_model=deepseek-chat \
  fallback_provider=deepseek
```

### How to Follow the Template (Manual)

If `prose` CLI is not available:

1. **Fetch this contract:** `curl -sL https://git.sysloggh.net/SyslogSolution/prose-contracts/raw/branch/master/hermes-config-template.prose.md`
2. **Open the target config.yaml** — the profile you're updating
3. **Compare** each of the 5 required sections below against what exists in the profile
4. **For each section:**
   - If it says **SHARED INFRA — DO NOT CHANGE**: Copy the value exactly as shown
   - If it says **USER CHOOSES**: Use the agent's assigned model/provider
   - If missing entirely: Add the full section
5. **Verify** every endpoint responds (see Verification section at the end)
6. **Restart** the gateway

### Decision Tree

```
What kind of profile is this?
├── Main profile (~/.hermes/config.yaml)
│   └── Replace web.*, mcp_servers.*, compression.*, auxiliary.*, custom_providers.*
│   └── model.default + fallback: use current values (USER CHOOSES)
│
├── Worker profile (~/.hermes/profiles/<name>/config.yaml)
│   ├── Does it have web.search_backend?
│   │   ├── NO → Add the full web.* section (copy exactly)
│   │   └── YES → Verify it points to the right IP
│   ├── Does it have mcp_servers.ra-h-os?
│   │   ├── NO → Add mcp_servers.* section (copy exactly)
│   │   └── YES → Verify URL
│   └── model.default: USE the worker's assigned model (don't copy main)
│
└── Non-Syslog profile (personal/lifestyle agent)
    └── Skip — use default Hermes config or Tanko's config instead
```

## Infrastructure Stack

This template provisions the following shared infrastructure. Every agent should point to the same endpoints unless explicitly overridden.

| Component | Endpoint | Purpose |
|---|---|---|
| Firecrawl | `http://192.168.68.7:3002/` | Web content extraction |
| SearXNG | `http://storepve:8888` | Privacy-respecting web search |
| LiteLLM | `http://litellm.sysloggh.net/litellm/v1` | Unified model gateway |
| RA-H OS MCP | `http://192.168.68.65:3100/mcp` | Knowledge graph bridge |
| Context7 MCP | `http://localhost:8079/mcp` | Documentation queries |

**API Key Rules:**
- `api_key: sk-_SW...B8nw` — Hardcoded LiteLLM master key for custom_providers and auxiliary tasks
- `api_key_env: DEEPSEEK_API_KEY` — Env-var based key for fallback provider
- Worker profiles should inherit proxy config via `harness` custom_provider, NOT hardcode LiteLLM keys

**For workers that need API keys overridden:** Set `api_key: ''` in the model section (inherits from custom_providers), or use `api_key_env` for env-based auth.

## Template Structure

### Required Sections (every agent MUST have)

```yaml
# ─── Model Selection (USER CHOOSES) ───
model:
  # !! CHANGE THIS for your agent !!
  default: <agent_default_model>
  provider: <agent_default_provider>
  # LiteLLM base URL (shared infra)
  base_url: http://litellm.sysloggh.net/litellm/v1

fallback_providers:
  # !! OPTIONAL: overridable fallback !!
  provider: <fallback_provider>
  model: <fallback_model>

# ─── Web Stack (SHARED INFRA — DO NOT CHANGE) ───
web:
  backend: firecrawl
  search_backend: searxng
  extract_backend: firecrawl
  firecrawl:
    base_url: http://192.168.68.7:3002/

# ─── MCP Servers (SHARED INFRA — DO NOT CHANGE) ───
mcp_servers:
  context7:
    connect_timeout: 60
    timeout: 300
    url: http://localhost:8079/mcp
  ra-h-os:
    url: http://192.168.68.65:3100/mcp
    timeout: 120
    connect_timeout: 60

# ─── Compression (SHARED — can override model) ───
compression:
  enabled: true
  provider: harness
  model: <auxiliary_model>  # default: gemma-4-12b
  threshold: 0.5
  target_ratio: 0.25
  protect_last_n: 30
  hygiene_hard_message_limit: 400

# ─── Auxiliary Tasks (SHARED INFRA + MODEL) ───
auxiliary:
  vision:
    provider: harness
    model: <auxiliary_model>
  web_extract:
    provider: harness
    model: <auxiliary_model>
  session_search:
    provider: harness
    model: <auxiliary_model>
    max_concurrency: 3

# ─── Custom Provider (SHARED INFRA — LiteLLM) ───
custom_providers:
  - name: <custom_provider_name>
    model: <custom_provider_model>
    base_url: http://litellm.sysloggh.net/litellm/v1
    api_key: <liteLLM_master_key>
    api_mode: chat_completions
```

### Optional Sections (agent-specific)

- **Platform configs** (Telegram, Discord, WhatsApp bot tokens)
- **Display/skin** options (compact mode, personality)
- **Plugin lists** (zulip-platform, etc.)
- **Terminal settings** (container image, timeouts)
- **Security/approvals** (command allowlists)
- **Kanban/worker** settings (if this profile is a Kanban worker)
- **Skills auto_load** list
- **Timezone** override

## Continuity

Configuration drift detection is **event-driven**:

- **On agent onboarding**: Always scaffold from this template
- **On infra change**: If Firecrawl/SearXNG/LiteLLM endpoints change, update template + all profiles
- **On new model**: When a new model is deployed on Litellm, any agent can change their `default` independently
- **Periodic**: Every 2 weeks — check if any profile's infra section has drifted from the template
- **On connection failure**: If web search/extract fails, check if that agent has missing `web.*` config

## Success Criteria

The configuration is CONSIDERED GOOD when ALL of these pass:

### Infra Connectivity
- `web.backend == "firecrawl"` — Firecrawl backend configured
- `web.search_backend == "searxng"` — SearXNG search configured
- `web.extract_backend == "firecrawl"` — Firecrawl extraction configured
- `web.firecrawl.base_url` points to `192.168.68.7:3002`
- `mcp_servers.ra-h-os.url` points to `192.168.68.65:3100/mcp`
- All endpoints respond to `curl` health checks

### Model Flexibility
- `model.default` is settable per agent (not hardcoded)
- `model.provider` is settable per agent
- `custom_providers[0].model` matches the agent's workload (code vs general)

### Completeness
- `auxiliary.vision` configured (even if provider=auto)
- `compression.enabled` set (true for most agents)
- Fallback provider configured (deepseek or another harness model)
- `_config_version` correctly set (currently `30`)

### No Drift
- No duplicate infra endpoints (one canonical Firecrawl URL)
- No stale endpoints (old IPs, dead services)
- All profiles consistent on shared infra

## Configuration Rules

### Rule 1: Shared Infra Is Locked
The following MUST be identical across ALL profiles:
- `web.backend`, `web.search_backend`, `web.extract_backend`
- `web.firecrawl.base_url`
- `mcp_servers.ra-h-os.url`
- `custom_providers[0].base_url`

### Rule 2: Model Choice Is Free
The following are OWNED by each agent and can differ:
- `model.default` — the primary model
- `model.provider` — where it runs
- `fallback_providers.model` — backup model
- `custom_providers[0].model` — what this agent uses LiteLLM for

### Rule 3: Workers Inherit, Not Duplicate
Worker profiles (syslog-code, syslog-devops, etc.) generally inherit from the main config. Only override what's DIFFERENT:
- Different default model → override `model.default`
- Different auxiliary model → override auxiliary sections
- No web search needed → still keep the config (tools won't enable without it)

### Rule 4: API Key Placement
- **Custom provider keys** (`custom_providers[0].api_key`): Must be hardcoded (the LiteLLM master key or a virtual key)
- **Model section keys** (`model.api_key`): Prefer empty. Workers inherit from custom_providers.
- **Environment keys** (`api_key_env`): For fallback providers that need separate auth (DeepSeek, OpenRouter)
- **Hardcoded keys in profile**: If a worker's `model.api_key` is set, it overrides custom_providers. Only use when the worker needs a DIFFERENT provider than Litellm.

### Rule 5: Verify After Every Config Change
After changing a profile's config:
1. `curl` the model endpoint to confirm auth works
2. `curl` the web stack endpoints (Firecrawl, SearXNG)
3. Check that `hermes gateway --restart` reloads cleanly

## Execution

1. **Check current config** — Read the target agent's config.yaml
2. **Compare against template** — Identify missing or divergent sections
3. **Apply shared infra** — Lock the web/MCP/compression sections to template values
4. **Apply model choice** — Set default/fallback/auxiliary models per agent's workload
5. **Preserve agent-specific** — Keep platform configs, plugins, terminal settings, skills
6. **Remove stale** — Drop any old infra endpoints that don't match the template
7. **Verify** — curl all shared endpoints, test the model
8. **Report** — What was changed, what was preserved, what's still custom

## Example Output

```
## Config Template Applied: syslog-code ✅

### Shared Infrastructure (Locked)
| Section | Before | After |
|---|---|---|
| web.backend | firecrawl | firecrawl ✅ |
| web.search_backend | NOT SET | searxng ✅ |
| web.firecrawl.base_url | NOT SET | http://192.168.68.7:3002/ ✅ |
| mcp_servers.ra-h-os | present | present ✅ |

### Agent Model Choices (Preserved)
| Setting | Value |
|---|---|
| model.default | qwen3.6-27B-code (code agent) |
| fallback | gemma-4-12b (harness) |
| auxiliary | gemma-4-12b (harness) |
| compression | gemma-4-12b (harness) |

### Endpoint Verification
| Endpoint | Status |
|---|---|
| Firecrawl :3002 | ✅ 200 OK |
| SearXNG :8888 | ✅ 200 OK |
| LiteLLM | ✅ 200 OK |
| RA-H OS MCP |  ✅ Connected |
```