Hermes Agent

​

Overview

​

Architecture

• Hermes Agent — A single-replica stateful workload running the supervised gateway. It serves the OpenAI-compatible API on port 8642 and the web dashboard on port 9119. Headless Chromium for browser automation is baked into the image and launched on demand.
• Model — External. Every completion is dispatched to your LLM provider using a key you supply; the workload holds no model weights.

​

What Gets Created

• Stateful Hermes Agent Workload — Single replica. Gateway API on port 8642 (bearer auth, optionally public); web dashboard on port 9119 (internal only, basic auth).
• Volume Set — 10 GiB persistent storage at /opt/data for the SQLite memory database, sessions, learned skills, and agent config. Supports optional autoscaling.
• Identity & Policy — An identity bound to the workload with reveal access to exactly the one prerequisite secret, and nothing else.

​

Prerequisites

​

Configuration

image: nousresearch/hermes-agent:v2026.7.7.2

model:
  provider: anthropic # anthropic | openai | custom (any other OpenAI-compatible endpoint)
  name: "" # model override (e.g. claude-opus-4.6, gpt-5); empty = provider default
  baseUrl: "" # OpenAI-compatible endpoint; required when provider is "custom"
  reasoningEffort: medium # none | low | medium | high — use "none" for non-reasoning models

secret: # the dictionary secret you created (see Prerequisites)
  name: my-hermes-secret # name of your existing dictionary secret
  keys: # point each field at the key in YOUR secret that holds it
    apiKey: api-key # LLM API key for your provider
    apiServerKey: api-server-key # bearer token clients present to the gateway API
    dashboardPassword: dashboard-password # dashboard password (used when dashboard.enabled)

dashboard:
  enabled: true # internal-only web UI on port 9119
  username: admin # basic-auth username (password comes from the secret)

resources:
  minCpu: 500m # idle floor — cpu:minCpu ratio must stay under 4:1
  minMemory: 1Gi
  cpu: 2000m # burst ceiling (headroom for on-demand browser automation)
  memory: 4Gi

volumeset:
  capacity: 10 # initial GiB (minimum 10) — memory DB, sessions, skills, config
  autoscaling:
    enabled: false # set true to auto-expand the volume as state grows
    maxCapacity: 100 # ceiling in GiB when autoscaling is enabled
    minFreePercentage: 10 # scale up when free space drops below this
    scalingFactor: 1.2 # multiplier applied on each scale-up

publicAccess:
  enabled: false # expose the gateway API (8642) on the public canonical HTTPS endpoint

internalAccess:
  type: same-gvc # none | same-gvc | same-org | workload-list
  workloads: [] # used with workload-list, e.g. //gvc/GVC/workload/NAME

​

Model

• image — The Hermes Agent container image.
• model.provider — The LLM provider:

• model.name — Model override, e.g. claude-opus-4.6, gpt-5. Empty uses the provider default. Recommended for non-Anthropic providers.
• model.baseUrl — The OpenAI-compatible endpoint. Required when provider is custom.
• model.reasoningEffort — none, low, medium, or high (default medium).

model:
  provider: custom
  baseUrl: https://openrouter.ai/api/v1
  name: anthropic/claude-sonnet-4-5

​

Secret

• secret.name — Name of the dictionary secret you created. See Prerequisites.
• secret.keys.apiKey / secret.keys.apiServerKey / secret.keys.dashboardPassword — The key names within your secret that hold each value. Override these to match an existing secret rather than renaming its keys.

​

Dashboard

• dashboard.enabled — Serve the web dashboard on port 9119. Internal only — it is never published on the public endpoint.
• dashboard.username — Basic-auth username. The password comes from your secret.

​

Resources

• resources.minCpu / resources.minMemory — The idle floor.
• resources.cpu / resources.memory — The burst ceiling, giving headroom for the on-demand headless browser.

​

Storage

• volumeset.capacity — Initial volume size in GiB (minimum 10) for the memory database, sessions, skills, and config.
• volumeset.autoscaling.enabled — Automatically expand the volume as state grows. When enabled:
  • maxCapacity — Maximum volume size in GiB.
  • minFreePercentage — Trigger a scale-up when free space drops below this percentage.
  • scalingFactor — Multiply the current capacity by this factor when scaling up.

​

Access

• publicAccess.enabled — Expose the gateway API on the public canonical HTTPS endpoint. Defaults to false. Read the security note below before enabling.
• internalAccess.type — Internal firewall scope of the workload:

​

Connecting

curl https://ENDPOINT/v1/chat/completions \
  -H "Authorization: Bearer $API_SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"hello"}]}'

​

Messaging Platforms

cpln workload exec {release}-hermes-agent --gvc {gvc} --container hermes -- hermes gateway setup

​

Important Notes

• The API server key must be at least 16 characters — Hermes rejects anything shorter, and the workload will not become ready.
• The dashboard is internal-only — it is never on the public endpoint; reach it via cpln workload port-forward.
• Single replica by design — memory is a single-writer SQLite database and upstream forbids two gateways sharing one data directory. Do not scale up. State persists on the volume across restarts and the agent resumes; only in-flight work is lost.
• The model is external — cost and rate limits are governed by your LLM provider, not this workload.
• Failed model calls return HTTP 200 with the error inside the body ("finish_reason": "error", "hermes": {"failed": true}). A client that checks only the HTTP status will read a provider failure as success — inspect the body, or the agent log at /opt/data/logs/agent.log.
• Keep cpu under 4× minCpu — the platform rejects a wider ratio; raise minCpu if you raise cpu.
• Resetting requires an uninstall — changing the secret and redeploying does not wipe existing memory or config on the volume. cpln helm uninstall deletes the volume set.

​

External References