Hermes Operator

Kubernetes operator for nousresearch/hermes-agent: a Python-based self-improving multi-platform AI agent. Declarative spec,
opinionated security defaults, S3 backups, OCI-registry auto-update,
SSA-based GitOps coexistence, and a one-shot migration path from
openclaw-operator.

hermes-operator ships as v1.0.0 with v1 stability commitments
in place from day one: no v0.x grind.

Inspired by openclaw-rocks/openclaw-operator;
openclaw lessons #437, #446, #433, #471, #479, #458, #469 (and many more)
informed concrete guardrails baked into v1. See
docs/superpowers/specs/2026-05-12-hermes-operator-design.md §1.G3.

Quickstart

# 1. Install the CRDs and operator via Helm (OCI chart; Helm 3.8+).
#    Omit --version for the latest release, or add --version X.Y.Z to pin.
helm install hermes-operator \
  oci://ghcr.io/paperclipinc/charts/hermes-operator \
  -n hermes-operator --create-namespace

# 2. Apply a minimal instance.
kubectl apply -n agents -f - <<'YAML'
apiVersion: hermes.agent/v1
kind: HermesInstance
metadata:
  name: my-hermes
spec:
  image:
    repository: ghcr.io/paperclipinc/hermes-agent
    tag: "v2026.5.29.2"
  storage:
    persistence:
      enabled: true
      size: 10Gi
YAML

# 3. Watch it converge.
kubectl get hi -n agents -w
# NAME        READY   PHASE   IMAGE                                AGE
# my-hermes   True    Ready   ghcr.io/paperclipinc/hermes-agent:v2026.5.29.2    30s

For more involved scenarios, see examples/.

Architecture

flowchart LR
  subgraph User
    GitOps[FluxCD / Argo]
    Kubectl[kubectl apply]
  end

  subgraph ControlPlane["Kubernetes control plane"]
    APIServer[(kube-apiserver)]
    HInstance["HermesInstance"]
    HSelfConfig["HermesSelfConfig"]
    HClusterDefaults["HermesClusterDefaults<br/>(singleton)"]
  end

  subgraph Operator["hermes-operator pod"]
    DefaulterWebhook[Defaulter]
    ValidatorWebhook[Validator]
    InstanceCtrl[HermesInstance<br/>controller]
    SelfConfigCtrl[HermesSelfConfig<br/>controller<br/>SSA: hermes.agent/selfconfig]
    ClusterDefaultsCtrl[ClusterDefaults<br/>controller]
  end

  subgraph Workload["agent workload (per HermesInstance)"]
    STS[StatefulSet]
    Svc[Service]
    NetPol[NetworkPolicy default-deny]
    PVC[PVC ~/.hermes]
    Honcho[Honcho Deploy<br/>profile store]
    CronJob[Backup CronJob]
  end

  S3[(S3-compatible<br/>backup target)]
  OCI[(OCI registry<br/>hermes-agent tags)]

  GitOps --> APIServer
  Kubectl --> APIServer
  APIServer <-->|admission| DefaulterWebhook
  APIServer <-->|admission| ValidatorWebhook
  APIServer --> HInstance
  APIServer --> HSelfConfig
  APIServer --> HClusterDefaults
  HInstance --> InstanceCtrl
  HSelfConfig --> SelfConfigCtrl
  HClusterDefaults --> ClusterDefaultsCtrl
  InstanceCtrl --> STS
  InstanceCtrl --> Svc
  InstanceCtrl --> NetPol
  InstanceCtrl --> PVC
  InstanceCtrl --> Honcho
  InstanceCtrl --> CronJob
  SelfConfigCtrl -.SSA patch.-> HInstance
  CronJob --> S3
  InstanceCtrl -.poll.-> OCI

The agent runs as a StatefulSet (single replica by default) under a default-
deny NetworkPolicy. The HermesSelfConfig controller uses Server-Side Apply
under field manager hermes.agent/selfconfig, so FluxCD/Argo can own the
parent HermesInstance for other fields without flap. HermesClusterDefaults
is a cluster-scoped singleton (name must be cluster) that fills nil
fields only: explicit values on the instance always win.

Features

Worked example: self-configure

The agent can persist a learned skill, env var, config patch, workspace file,
or Honcho profile by creating a HermesSelfConfig in its namespace. The
operator validates against the parent instance's selfConfigure.protectedKeys
allowlist and applies via SSA:

apiVersion: hermes.agent/v1
kind: HermesSelfConfig
metadata:
  name: install-finance-skill
  namespace: agents
spec:
  instanceRef: my-hermes
  addSkills:
    - source: "git+https://github.com/foo/[email protected]"
  patchConfig:
    schedules:
      morning-brief: "0 8 * * *"
  addEnvVars:
    - name: FINANCE_TZ
      value: Europe/Berlin

Apply, then watch:

kubectl get hsc -n agents
# NAME                      PHASE     INSTANCE    AGE
# install-finance-skill     Applied   my-hermes   3s

The audit trail lives in kubectl describe hsc install-finance-skill and on
the instance via the per-field SSA field manager
hermes.agent/selfconfig: kubectl get hi my-hermes -o jsonpath='{.metadata.managedFields}'
shows exactly which fields the agent owns vs. Flux owns vs. you own.

See examples/ for end-to-end recipes.

Supported Kubernetes versions

We drop the oldest k8s minor when Kubernetes EOLs it, on the next operator
minor release. Patch releases never change the supported matrix.

Distribution

Documentation

• Design spec: the canonical product/architecture doc.
• API reference: every field on every CR.
• Condition catalogue: every status condition, reason code, troubleshooting hint.
• API versioning policy: what is and is not a breaking change.
• Deprecation policy: the 3-step flow + active deprecations.
• Roadmap: shipped, planned, future, non-goals.
• Examples: 9 worked YAML recipes.
• Grafana dashboard: operator-overview dashboard JSON.

Contributing

See CONTRIBUTING.md. Pull requests follow
Conventional Commits (feat:, fix:,
docs:, ci:, chore:, refactor:, test:); release-please drives the
release-PR loop from feat:/fix:.

Security

See SECURITY.md. Report vulnerabilities via the GitHub
security advisory flow; do not file public issues for security bugs.

License

Apache-2.0. See LICENSE.