Skip to content

api-reference-generated.md

Latest commit

 

History

History
1664 lines (878 loc) · 62.2 KB

api-reference-generated.md

File metadata and controls

1664 lines (878 loc) · 62.2 KB
Raw

API Reference

Packages

hermes.agent/v1

Package v1 contains API Schema definitions for the hermes v1 API group.

Resource Types

AutoUpdateRollbackSpec

AutoUpdateRollbackSpec configures the rollback path.

Appears in:

Field Description Default Validation
enabled boolean true Optional: {}
probeFailureThreshold integer 3 Maximum: 100
Minimum: 1
Optional: {}

AutoUpdateSourceSpec

AutoUpdateSourceSpec is the OCI registry source for the channel.

Appears in:

Field Description Default Validation
registry string Optional: {}
channel string Optional: {}

AutoUpdateSpec

AutoUpdateSpec controls opt-in OCI-registry polling for newer agent images.

Appears in:

Field Description Default Validation
enabled boolean false Optional: {}
source AutoUpdateSourceSpec Optional: {}
pollInterval string 1h Optional: {}
backupBeforeUpdate boolean true Optional: {}
rollback AutoUpdateRollbackSpec Optional: {}

AvailabilitySpec

AvailabilitySpec bundles PDB, HPA, and topology-spread.

Appears in:

Field Description Default Validation
podDisruptionBudget PDBSpec Optional: {}
horizontalPodAutoscaler HPASpec Optional: {}
topologySpreadConstraints TopologySpreadConstraint array Optional: {}

BackupS3Spec

BackupS3Spec configures the S3-compatible remote target.

Appears in:

Field Description Default Validation
bucket string
endpoint string
region string Optional: {}
pathPrefix string Optional: {}
credentialsSecretRef LocalObjectReference

BackupSpec

BackupSpec controls S3-compatible PVC snapshots for this instance.

Appears in:

Field Description Default Validation
s3 BackupS3Spec Optional: {}
schedule string Optional: {}
onDelete boolean false Optional: {}
preUpdate boolean true Optional: {}
historyLimit integer 30 Maximum: 10000
Minimum: 1
Optional: {}
failedHistoryLimit integer 3 Maximum: 1000
Minimum: 0
Optional: {}
image string Optional: {}

CABundleSpec

CABundleSpec optionally mounts a CA bundle into the agent container. Exactly one of ConfigMapName / SecretName SHOULD be set.

Appears in:

Field Description Default Validation
configMapName string ConfigMapName references a ConfigMap in the same namespace. Optional: {}
secretName string SecretName references a Secret in the same namespace. Optional: {}
key string Key is the data-map key holding the PEM bundle. Default "ca.crt". ca.crt Optional: {}

ConfigMergeMode

Underlying type: string

ConfigMergeMode controls how Raw and ConfigMapRef are combined.

Validation:

  • Enum: [replace merge]

Appears in:

Field Description
replace ConfigMergeModeReplace: Raw replaces ConfigMapRef entirely when both are set.
This is the default to avoid surprising merges.
merge ConfigMergeModeMerge: YAML deep-merge Raw onto ConfigMapRef. Raw wins on conflict.

ConfigSpec

ConfigSpec holds the agent's ~/.hermes/config.yaml. Exactly one of Raw or ConfigMapRef SHOULD be set; the validating webhook rejects both unset and emits a warning if both are set with MergeMode unset.

Appears in:

Field Description Default Validation
raw RawConfig Raw is the inline YAML body of config.yaml. Stored as a RawExtension so
users may write structured YAML in the manifest without escaping.		 Optional: {}
configMapRef LocalObjectReference ConfigMapRef references a ConfigMap in the same namespace whose
"config.yaml" key holds the body.		 Optional: {}
mergeMode ConfigMergeMode MergeMode controls combination when both Raw and ConfigMapRef are set. replace Enum: [replace merge]
Optional: {}

DiscordGatewaySpec

DiscordGatewaySpec binds the agent to a Discord bot application.

Appears in:

Field Description Default Validation
enabled boolean false Optional: {}
botTokenSecretRef SecretKeySelector Optional: {}
applicationID string ApplicationID is the Discord application's snowflake. Optional: {}
guildIDs string array GuildIDs scopes slash-command registration to specific guilds. Optional: {}

FFmpegSpec

FFmpegSpec controls the FFmpeg dependency check.

Appears in:

Field Description Default Validation
enabled boolean true Optional: {}

GatewaysSpec

GatewaysSpec is the union of all supported messaging-platform bindings.

Appears in:

Field Description Default Validation
telegram TelegramGatewaySpec Optional: {}
discord DiscordGatewaySpec Optional: {}
slack SlackGatewaySpec Optional: {}
whatsapp WhatsAppGatewaySpec Optional: {}
signal SignalGatewaySpec Optional: {}

GrafanaDashboardSpec

GrafanaDashboardSpec configures auto-provisioned Grafana dashboard ConfigMaps.

Appears in:

Field Description Default Validation
enabled boolean Enabled enables Grafana dashboard ConfigMap creation. false Optional: {}
labels object (keys:string, values:string) Labels to add to the dashboard ConfigMaps (in addition to grafana_dashboard: "1"). Optional: {}
folder string Folder is the Grafana folder to place the dashboards in. Hermes Optional: {}

HPASpec

HPASpec controls HorizontalPodAutoscaler emission.

Appears in:

Field Description Default Validation
enabled boolean false Optional: {}
minReplicas integer MinReplicas: default 1. 1 Minimum: 1
Optional: {}
maxReplicas integer MaxReplicas: default 5. 5 Minimum: 1
Optional: {}
targetCPUUtilization integer TargetCPUUtilization: default 80 (percent). 80 Maximum: 100
Minimum: 1
Optional: {}
targetMemoryUtilization integer TargetMemoryUtilization: optional, when set adds a memory metric. Maximum: 100
Minimum: 1
Optional: {}
behavior HorizontalPodAutoscalerBehavior Behavior is forwarded onto HPA's autoscaling/v2 behavior field.
Plan 6 conformance suite asserts the field is exposed; v1 forwards it raw.		 Optional: {}

HTTPRouteParentRef

HTTPRouteParentRef references a parent (typically a Gateway) the route attaches to.

Appears in:

Field Description Default Validation
name string Name of the parent resource (e.g. the Gateway name). MinLength: 1
namespace string Namespace of the parent. Defaults to the HermesInstance namespace when empty. Optional: {}
sectionName string SectionName is the name of a section within the parent (e.g. a Gateway listener). Optional: {}

HTTPRouteSpec

HTTPRouteSpec controls optional Gateway API HTTPRoute creation. It mirrors the IngressSpec shape for consistency: a single prefix rule routing to the agent Service. The route is only created when Enabled is true.

Appears in:

Field Description Default Validation
enabled boolean Enabled: when true, the operator creates an HTTPRoute for the agent.
Default false.		 false Optional: {}
parentRefs HTTPRouteParentRef array ParentRefs are the Gateways (or other parents) this route attaches to.
At least one is required for the route to take effect.		 Optional: {}
hostnames string array Hostnames are the hostnames matched by this route. Optional: {}
path string Path is the path prefix routed to the agent Service. Default "/". / Optional: {}
servicePortName string ServicePortName: name of the Service port the route should target.
Default "gateway".		 gateway Optional: {}
annotations object (keys:string, values:string) Annotations are applied verbatim onto the HTTPRoute. Optional: {}

HermesClusterDefaults

HermesClusterDefaults is the Schema for the hermesclusterdefaults API

Field Description Default Validation
apiVersion string hermes.agent/v1
kind string HermesClusterDefaults
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata. Optional: {}
spec HermesClusterDefaultsSpec spec defines the desired state of HermesClusterDefaults Required: {}

HermesClusterDefaultsSpec

HermesClusterDefaultsSpec is the cluster-wide default set applied by the defaulting webhook when a HermesInstance leaves a field nil. ClusterDefaults only fills nil fields; an explicit value on the instance always wins.

Appears in:

Field Description Default Validation
image ImageSpec Image defaults the instance's spec.image. Optional: {}
registry RegistryDefaults Registry defaults image-pull plumbing. Optional: {}
storage StorageSpec Storage defaults the instance's spec.storage. Optional: {}
security SecurityDefaults Security defaults SA annotations + NetworkPolicy on/off + container-level
defaults (read-only rootfs etc. are operator-baked, not defaultable).		 Optional: {}
observability ObservabilityDefaults Observability defaults metrics / ServiceMonitor / PrometheusRule. Optional: {}
networking NetworkingDefaults Networking defaults Service kind + NetworkPolicy enablement. Optional: {}
resources ResourcesSpec Resources defaults requests + limits when the instance leaves them nil. Optional: {}

HermesInstance

HermesInstance is the Schema for the hermesinstances API

Field Description Default Validation
apiVersion string hermes.agent/v1
kind string HermesInstance
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata. Optional: {}
spec HermesInstanceSpec spec defines the desired state of HermesInstance Required: {}

HermesInstanceSpec

HermesInstanceSpec defines the desired state of HermesInstance. Field order follows design §4.

Appears in:

Field Description Default Validation
image ImageSpec Image selects the hermes-agent container image. Optional: {}
config ConfigSpec Config is the YAML content of ~/.hermes/config.yaml, supplied inline,
from a referenced ConfigMap, or merged from both.		 Optional: {}
workspace WorkspaceSpec Workspace seeds initial files and directories into ~/.hermes on first start. Optional: {}
resources ResourcesSpec Resources sets the agent container's CPU/memory requests + limits. Optional: {}
security SecuritySpec Security configures pod/container security contexts, RBAC, NetworkPolicy,
and the optional cluster CA bundle injection.		 Optional: {}
storage StorageSpec Storage controls the PVC backing ~/.hermes for this instance. Optional: {}
networking NetworkingSpec Networking exposes the agent via Service / Ingress. Optional: {}
observability ObservabilitySpec Observability turns on metrics, ServiceMonitor, PrometheusRule, and logging. Optional: {}
availability AvailabilitySpec Availability sets PDB, HPA, and topology-spread constraints. Optional: {}
probes ProbesSpec Probes lets users override the built-in liveness/readiness/startup probes. Optional: {}
scheduling SchedulingSpec Scheduling targets the agent pod at specific nodes. Optional: {}
shareProcessNamespace boolean ShareProcessNamespace enables PID namespace sharing between all containers
in the pod. Defaults to false: the upstream hermes-agent image runs under
s6-overlay, whose /init must be PID 1 (s6-overlay-suexec aborts otherwise),
and s6 already reaps zombies non-blocking on SIGCHLD — so sharing the process
namespace (which makes the pause container PID 1) is both incompatible and
unnecessary.
Security note: enabling this lets every container in the pod see and signal
every other container's processes. A compromised sidecar could send signals
to the agent and vice versa. Leave false to keep per-container PID isolation.		 false Optional: {}
initContainers Container array InitContainers is a user-supplied list of init containers appended after
any operator-managed init containers (e.g. runtime-init from Plan 3).		 Optional: {}
sidecars Container array Sidecars is a user-supplied list of sidecars appended after operator-managed
sidecars (e.g. ollama / web-terminal / tailscale from Plan 3).		 Optional: {}
extraVolumes Volume array ExtraVolumes is a user-supplied list of additional pod volumes. Optional: {}
extraVolumeMounts VolumeMount array ExtraVolumeMounts is a user-supplied list of additional volume mounts
applied to the agent container.		 Optional: {}
envFrom EnvFromSource array EnvFrom is a list of EnvFrom sources (ConfigMap/Secret refs) injected
into the agent container.		 Optional: {}
env EnvVar array Env is a list of explicit environment variables for the agent container.
SSA list-map key is "name" so HermesSelfConfig can merge entries without
replacing the whole list.		 Optional: {}
skills InstanceSkill array Skills is the declarative list of uv-installable skill sources. Plan 3
wires the runtime; the field is declared here so SSA from HermesSelfConfig
(Plan 4) can target it without a CRD schema change.		 Optional: {}
selfConfigure SelfConfigureSpec SelfConfigure is the allowlist policy for HermesSelfConfig mutations. Optional: {}
suspended boolean Suspended scales the StatefulSet to zero replicas without deleting state. Optional: {}
backup BackupSpec Backup controls scheduled and on-delete PVC snapshot behaviour. Optional: {}
restoreFrom string RestoreFrom names a backup snapshot to restore from on next boot. Optional: {}
autoUpdate AutoUpdateSpec AutoUpdate controls opt-in OCI-registry polling for newer agent images. Optional: {}
migration MigrationSpec Migration is a one-shot migration source (set on initial create only). Optional: {}
runtime RuntimeSpec Runtime configured the agent's Python toolchain and OS-level dependencies
for the old hand-rolled agent image. It is now IGNORED: the published agent
image is the upstream NousResearch/hermes-agent s6 runtime, which ships its
own Python env, browser, node, and dependencies (see docs/runtime.md), so
the operator no longer builds a runtime via init containers. Setting this
has no effect.
Deprecated: ignored since the upstream-image runtime (v0.1.19); scheduled
for removal no earlier than v0.3.0 and 2027-01-01. See docs/deprecations.md.		 Optional: {}
gateways GatewaysSpec Gateways configures the platform-side messaging bindings (Telegram, Discord,
Slack, WhatsApp, Signal). Each gateway is opt-in and references its own
Secret(s) so tokens are rotatable independently.		 Optional: {}
profileStore ProfileStoreSpec ProfileStore configures the optional Honcho profile-store companion. Optional: {}
tailscale TailscaleSpec Tailscale exposes the gateway over a Tailscale tailnet. Optional: {}

HermesSelfConfig

HermesSelfConfig is the Schema for the hermesselfconfigs API

Field Description Default Validation
apiVersion string hermes.agent/v1
kind string HermesSelfConfig
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata. Optional: {}
spec HermesSelfConfigSpec spec defines the desired state of HermesSelfConfig Required: {}

HermesSelfConfigSpec

HermesSelfConfigSpec is an agent-driven, audited request to mutate the parent HermesInstance. The operator validates against the parent's .spec.selfConfigure policy, then applies via Server-Side Apply with field manager "hermes.agent/selfconfig".

Appears in:

Field Description Default Validation
instanceRef string InstanceRef is the name of the parent HermesInstance in the same namespace. MaxLength: 253
MinLength: 1
addSkills SelfConfigSkill array AddSkills appends skills to the parent's .spec.skills. MaxItems: 20
Optional: {}
patchConfig JSON PatchConfig is a JSON merge patch (RFC 7396) applied to the agent's
runtime config at ~/.hermes/config.yaml.		 Optional: {}
addEnvVars SelfConfigEnvVar array AddEnvVars appends environment variables to the parent's .spec.env. MaxItems: 20
Optional: {}
addWorkspaceFiles SelfConfigWorkspaceFile array AddWorkspaceFiles writes files into the workspace ConfigMap. MaxItems: 50
Optional: {}
addProfileSnapshot SelfConfigProfileSnapshot AddProfileSnapshot writes an opaque Honcho profile snapshot via a one-shot Job. Optional: {}

HonchoImageSpec

HonchoImageSpec selects the Honcho image.

Appears in:

Field Description Default Validation
repository string ghcr.io/plastic-labs/honcho Optional: {}
tag string 0.1.0 Optional: {}
pullPolicy string IfNotPresent Enum: [Always IfNotPresent Never]
Optional: {}

HonchoPersistenceSpec

HonchoPersistenceSpec controls the Honcho-side PVC.

Appears in:

Field Description Default Validation
enabled boolean true Optional: {}
size string 5Gi Optional: {}
storageClassName string Optional: {}

HonchoSpec

HonchoSpec controls the Honcho companion Deployment.

Appears in:

Field Description Default Validation
enabled boolean false Optional: {}
image HonchoImageSpec Optional: {}
persistence HonchoPersistenceSpec Optional: {}
resources ResourceRequirements Optional: {}
apiKeySecretRef SecretKeySelector APIKeySecretRef points at the Secret holding the Honcho API key. Optional: {}

ImageSpec

ImageSpec selects an OCI image.

Appears in:

Field Description Default Validation
repository string ghcr.io/paperclipinc/hermes-agent Optional: {}
tag string Tag is the container image tag. Either tag or digest must be set; there is
no default, because pinning to a mutable tag like :latest can silently pull
a broken upstream build.		 Optional: {}
digest string Digest overrides the tag with an image digest (e.g. sha256:abc...). When set
it takes precedence over the tag for the resolved image reference.		 Optional: {}
pullPolicy string IfNotPresent Enum: [Always IfNotPresent Never]
Optional: {}

IngressSpec

IngressSpec controls optional Ingress creation.

Appears in:

Field Description Default Validation
enabled boolean Enabled: when true, the operator creates an Ingress for the agent.
Default false.		 false Optional: {}
host string Host is the primary hostname. Optional: {}
className string ClassName is the IngressClass (nginx, traefik, ...). Optional: {}
tls IngressTLSSpec array TLS is the list of TLS settings. Optional: {}
annotations object (keys:string, values:string) Annotations are applied to the Ingress. The operator merges
provider-specific defaults (force-https, etc.) on top of these.		 Optional: {}
pathType PathType PathType: default Prefix. Prefix Enum: [Exact Prefix ImplementationSpecific]
Optional: {}
path string Path: default "/". / Optional: {}
servicePortName string ServicePortName: name of the Service port the Ingress should route to.
Default "gateway".		 gateway Optional: {}

IngressTLSSpec

IngressTLSSpec is a single TLS section on the Ingress.

Appears in:

Field Description Default Validation
secretName string MinLength: 1
hosts string array

InstanceSkill

InstanceSkill: Plan 3 fills the runtime semantics. The field exists here so SSA from HermesSelfConfig (Plan 4) can patch the slice with listMapKey=source.

Appears in:

Field Description Default Validation
source string Source is the uv/pip-compatible install source. MinLength: 1
version string Version optionally pins the install version. Mirrors SelfConfigSkill.Version
so HermesSelfConfig can carry the field through SSA without truncation.		 Optional: {}

LocalObjectReference

LocalObjectReference is a same-namespace reference by name.

Appears in:

Field Description Default Validation
name string

LogFormat

Underlying type: string

LogFormat is the agent's log output format.

Validation:

  • Enum: [text json]

Appears in:

Field Description
text
json

LoggingSpec

LoggingSpec controls the agent's logger configuration via env vars.

Appears in:

Field Description Default Validation
format LogFormat text Enum: [text json]
Optional: {}
level string Level: Plan 3 wires HERMES_LOG_LEVEL on the agent container. info Enum: [trace debug info warn error]
Optional: {}

MetricsSpec

MetricsSpec controls the agent's Prometheus metrics endpoint.

Appears in:

Field Description Default Validation
enabled boolean true Optional: {}
port integer Port for the /metrics endpoint. 9090 Maximum: 65535
Minimum: 1
Optional: {}
secure boolean Secure: when true, /metrics requires bearer-token auth and uses HTTPS.
The ServiceMonitor scheme/scrape settings must agree (lesson #435/#440).		 false Optional: {}
grafanaDashboard GrafanaDashboardSpec GrafanaDashboard configures auto-provisioned Grafana dashboard ConfigMaps
(operator overview + per-instance). When enabled, the operator emits
ConfigMaps labeled grafana_dashboard="1" so the Grafana sidecar provisioner
picks them up automatically.		 Optional: {}

MigrationBackupRef

MigrationBackupRef points at an OpenClaw backup snapshot in S3.

Appears in:

Field Description Default Validation
s3 MigrationBackupS3

MigrationBackupS3

MigrationBackupS3 mirrors BackupS3Spec but adds an explicit Key.

Appears in:

Field Description Default Validation
bucket string
endpoint string
region string Optional: {}
key string
credentialsSecretRef LocalObjectReference

MigrationFromOpenClawSource

MigrationFromOpenClawSource is exactly-one-of (validated by webhook).

Appears in:

Field Description Default Validation
openclawInstanceRef NamespacedObjectReference Optional: {}
backupRef MigrationBackupRef Optional: {}

MigrationFromOpenClawSpec

MigrationFromOpenClawSpec describes an OpenClaw source.

Appears in:

Field Description Default Validation
source MigrationFromOpenClawSource
mode string copy Enum: [copy move]
Optional: {}
image string Optional: {}

MigrationSpec

MigrationSpec is a one-shot migration source (immutable once status.migration.completed is true).

Appears in:

Field Description Default Validation
fromOpenClaw MigrationFromOpenClawSpec Optional: {}

NamedServicePort

NamedServicePort is a single Service port. The TargetPort is optional and defaults to Port when nil.

Appears in:

Field Description Default Validation
name string MaxLength: 63
MinLength: 1
port integer Maximum: 65535
Minimum: 1
targetPort integer Optional: {}
protocol Protocol TCP Enum: [TCP UDP SCTP]
Optional: {}
nodePort integer NodePort is honored only when the Service is NodePort or LoadBalancer. Optional: {}

NamespacedObjectReference

NamespacedObjectReference is a name+namespace pointer.

Appears in:

Field Description Default Validation
name string
namespace string

NetworkPolicyDefaults

NetworkPolicyDefaults defaults whether per-instance NetworkPolicies are created.

Appears in:

Field Description Default Validation
enabled boolean Optional: {}
allowDNS boolean Optional: {}

NetworkPolicySpec

NetworkPolicySpec controls per-instance NetworkPolicy creation.

Appears in:

Field Description Default Validation
enabled boolean Enabled: when true (the default), the operator creates a deny-all
NetworkPolicy plus selective allow rules (DNS + 443 egress + Service ingress
from the same namespace).		 true Optional: {}
allowDNS boolean AllowDNS: emit the standard DNS egress rule (UDP+TCP 53 to any peer).
Default true. Disable only when CoreDNS is reachable via a different
transport (e.g. node-local DNS via hostNetwork).		 true Optional: {}
allowedIngressNamespaces string array AllowedIngressNamespaces is the set of additional namespaces (beyond the
instance's own) whose pods may connect to the agent's exposed ports.		 Optional: {}
allowedIngressCIDRs string array AllowedIngressCIDRs is the set of CIDRs that may connect to the agent's
exposed ports.		 Optional: {}
allowedEgressCIDRs string array AllowedEgressCIDRs is the set of CIDRs the agent may connect to in addition
to the operator-built defaults (DNS + 443).		 Optional: {}
additionalEgress NetworkPolicyEgressRule array AdditionalEgress is a list of user-supplied egress rules appended verbatim
to the generated NetworkPolicy.		 Optional: {}

NetworkingDefaults

NetworkingDefaults mirrors the defaultable subset of NetworkingSpec.

Appears in:

Field Description Default Validation
service ServiceDefaults Optional: {}
networkPolicy NetworkPolicyDefaults Optional: {}

NetworkingSpec

NetworkingSpec exposes the agent via Service + (optionally) Ingress.

Appears in:

Field Description Default Validation
service ServiceSpec Service controls the Service kind and ports. Optional: {}
ingress IngressSpec Ingress controls optional Ingress creation. Optional: {}
httpRoute HTTPRouteSpec HTTPRoute controls optional Gateway API HTTPRoute creation. The operator
emits an unstructured gateway.networking.k8s.io/v1 HTTPRoute; the Gateway
API CRDs must be installed in the cluster for this to take effect.		 Optional: {}

ObservabilityDefaults

ObservabilityDefaults mirrors the defaultable subset of ObservabilitySpec.

Appears in:

Field Description Default Validation
metrics MetricsSpec Optional: {}
serviceMonitor ServiceMonitorSpec Optional: {}
prometheusRule PrometheusRuleSpec Optional: {}
logging LoggingSpec Optional: {}

ObservabilitySpec

ObservabilitySpec controls metrics, scraping, alerting, logging.

Appears in:

Field Description Default Validation
metrics MetricsSpec Optional: {}
serviceMonitor ServiceMonitorSpec Optional: {}
prometheusRule PrometheusRuleSpec Optional: {}
logging LoggingSpec Optional: {}

PDBSpec

PDBSpec controls PodDisruptionBudget emission.

Appears in:

Field Description Default Validation
enabled boolean false Optional: {}
minAvailable IntOrString MinAvailable: optional, mutually exclusive with MaxUnavailable. Optional: {}
maxUnavailable IntOrString MaxUnavailable: optional, mutually exclusive with MinAvailable.
Default 1 when neither is set and PDB is enabled.		 Optional: {}

PersistenceSpec

Appears in:

Field Description Default Validation
enabled boolean true Optional: {}
size string 1Gi Optional: {}
storageClassName string Optional: {}

ProbesSpec

ProbesSpec overrides the operator's built-in probes. Each field is a complete probe: set every value you want non-default because we apply it verbatim.

Appears in:

Field Description Default Validation
liveness Probe Optional: {}
readiness Probe Optional: {}
startup Probe Optional: {}

ProfileStoreSpec

ProfileStoreSpec is the union of supported profile-store backends. Only honcho is supported in v1.

Appears in:

Field Description Default Validation
honcho HonchoSpec Optional: {}

PrometheusRule

PrometheusRule is a minimal copy of monitoringv1.Rule so we don't depend on the Prometheus-Operator Go types at compile time. The runtime emits unstructured objects.

Appears in:

Field Description Default Validation
alert string MinLength: 1
expr string MinLength: 1
for string Optional: {}
labels object (keys:string, values:string) Optional: {}
annotations object (keys:string, values:string) Optional: {}

PrometheusRuleSpec

PrometheusRuleSpec controls emission of a default PrometheusRule with hermes-agent alerts (HighRestartRate, MetricsDown, etc.).

Appears in:

Field Description Default Validation
enabled boolean false Optional: {}
additionalRules PrometheusRule array AdditionalRules is a list of user-supplied rules merged onto the operator
default ruleset.		 Optional: {}

RBACSpec

RBACSpec controls per-instance ServiceAccount + Role + RoleBinding creation.

Appears in:

Field Description Default Validation
createServiceAccount boolean CreateServiceAccount: when true (the default), the operator creates and
owns a ServiceAccount named after the instance.		 true Optional: {}
serviceAccountName string ServiceAccountName: when CreateServiceAccount is false, the agent uses
this externally-managed ServiceAccount. Must exist in the same namespace.		 Optional: {}
annotations object (keys:string, values:string) Annotations are applied to the operator-created ServiceAccount. Use this
for IRSA (eks.amazonaws.com/role-arn), GKE Workload Identity
(iam.gke.io/gcp-service-account), Azure Workload Identity, etc.		 Optional: {}

RawConfig

RawConfig wraps runtime.RawExtension so deepcopy is generated cleanly.

Appears in:

RegistryDefaults

RegistryDefaults groups image-pull secret hints.

Appears in:

Field Description Default Validation
pullSecretName string PullSecretName, if non-empty, is added to every instance's
pod.spec.imagePullSecrets when the instance doesn't override.		 Optional: {}

ResourcesSpec

ResourcesSpec sets CPU/memory requests + limits on the agent container. Defaults intentionally omitted: the defaulting webhook fills from HermesClusterDefaults if available, otherwise the field is left empty (meaning the agent inherits whatever Pod-level defaults the namespace's LimitRange applies).

Appears in:

RipgrepSpec

RipgrepSpec controls the ripgrep dependency check.

Appears in:

Field Description Default Validation
enabled boolean true Optional: {}

RuntimeSpec

RuntimeSpec controlled Python/uv runtime concerns for the old hand-rolled agent image's init-container build.

Deprecated: ignored since the upstream-image runtime (v0.1.19); the upstream agent image is self-contained. Scheduled for removal no earlier than v0.3.0 and 2027-01-01. See docs/deprecations.md.

Appears in:

Field Description Default Validation
python string Python is informational only: the agent image's Python version is fixed
at build time. Setting this does NOT pull a different interpreter; it
exists so downstream tooling can assert the runtime it expects.		 3.11 Optional: {}
uv UVSpec UV controls the initial uv sync against the lockfile bundled in the
agent image. Enabled by default.		 Optional: {}
ffmpeg FFmpegSpec FFmpeg toggles the FFmpeg dependency check. The agent image always ships
FFmpeg; disabling here only skips the readiness assertion.		 Optional: {}
ripgrep RipgrepSpec Ripgrep toggles the ripgrep dependency check. See FFmpeg. Optional: {}
extraAptPackages string array ExtraAptPackages adds additional Debian packages installed by a
root-privileged init container BEFORE the main agent container starts.
Use sparingly: the init container runs as root and breaks the otherwise
hardened security posture for one container only.		 Optional: {}
extraPipPackages string array ExtraPipPackages adds additional Python packages installed via
uv pip install into a persistent venv on the data PVC.		 Optional: {}

SchedulingSpec

SchedulingSpec targets the agent pod at specific nodes.

Appears in:

Field Description Default Validation
nodeSelector object (keys:string, values:string) Optional: {}
tolerations Toleration array Optional: {}
affinity Affinity Optional: {}
priorityClassName string Optional: {}

SecurityDefaults

SecurityDefaults mirrors the defaultable subset of SecuritySpec.

Appears in:

Field Description Default Validation
serviceAccount ServiceAccountDefaults Optional: {}
networkPolicy NetworkPolicyDefaults Optional: {}
caBundle CABundleSpec Optional: {}

SecuritySpec

SecuritySpec bundles pod/container security, per-instance RBAC, NetworkPolicy, and the optional CA-bundle mount.

Appears in:

Field Description Default Validation
podSecurityContext PodSecurityContext PodSecurityContext overrides the operator's default hardened pod context.
Operator default is enforced when nil: runAsNonRoot=true, runAsUser=1000,
fsGroup=1000, seccompProfile=RuntimeDefault.		 Optional: {}
containerSecurityContext SecurityContext ContainerSecurityContext overrides the operator's default hardened container
context. Operator default: readOnlyRootFilesystem=true, allowPrivilegeEscalation=false,
drop ALL capabilities.		 Optional: {}
rbac RBACSpec RBAC controls per-instance ServiceAccount + Role + RoleBinding creation. Optional: {}
networkPolicy NetworkPolicySpec NetworkPolicy controls per-instance NetworkPolicy creation (default-deny baseline). Optional: {}
caBundle CABundleSpec CABundle optionally mounts a ConfigMap- or Secret-sourced CA bundle into
/etc/ssl/certs/hermes-ca-bundle.crt and sets SSL_CERT_FILE in the agent env.		 Optional: {}

SelfConfigAction

Underlying type: string

SelfConfigAction names a category of mutation. Used by HermesInstance.spec.selfConfigure.allowedActions to gate what the agent may request via HermesSelfConfig.

Validation:

  • Enum: [skills config envVars workspaceFiles profiles]

Appears in:

Field Description
skills
config
envVars
workspaceFiles
profiles

SelfConfigEnvVar

SelfConfigEnvVar is an environment variable entry.

Appears in:

Field Description Default Validation
name string Name of the environment variable. Must be a C_IDENTIFIER. MinLength: 1
Pattern: ^[A-Za-z_][A-Za-z0-9_]*$
value string Value is the literal value. Mutually exclusive with ValueFrom. Optional: {}
valueFrom SelfConfigEnvVarSource ValueFrom selects a value from a Secret or ConfigMap key. Optional: {}

SelfConfigEnvVarSource

SelfConfigEnvVarSource selects a Secret or ConfigMap key. Exactly one ref must be set.

Appears in:

Field Description Default Validation
secretKeyRef SelfConfigKeySelector Optional: {}
configMapKeyRef SelfConfigKeySelector Optional: {}

SelfConfigKeySelector

SelfConfigKeySelector selects a key from a Secret or ConfigMap.

Appears in:

Field Description Default Validation
name string MinLength: 1
key string MinLength: 1

SelfConfigProfileSnapshot

SelfConfigProfileSnapshot writes one Honcho profile snapshot via a Job.

Appears in:

Field Description Default Validation
profileID string MaxLength: 253
MinLength: 1
data string Data is the opaque snapshot payload. MinLength: 1

SelfConfigSkill

SelfConfigSkill names one skill to install.

Appears in:

Field Description Default Validation
source string Source is a uv-compatible package specifier. Required. MaxLength: 512
MinLength: 1
version string Version optionally pins a version. Optional: {}

SelfConfigWorkspaceFile

SelfConfigWorkspaceFile is a single file to materialise into the workspace.

Appears in:

Field Description Default Validation
path string Path is the relative path under ~/.hermes/workspace/. MaxLength: 512
MinLength: 1
Pattern: ^[A-Za-z0-9._/-]+$
content string Content is the literal file body. Optional: {}
contentFrom SelfConfigKeySelector ContentFrom reads the file body from a Secret key. Optional: {}

SelfConfigureSpec

SelfConfigureSpec is the allowlist policy for HermesSelfConfig mutations. Plan 4 wires the controller; the field exists here so Plan 4 doesn't need a CRD change. The validator rejects Enabled=true with ProtectedKeys empty.

Appears in:

Field Description Default Validation
enabled boolean Enabled: explicit *bool so the defaulter can distinguish "user said false"
from "user did not set it" (Plan 4 relies on this).		 Optional: {}
allowedActions SelfConfigAction array AllowedActions is the set of permitted action categories Plan 4 will
enforce: skills, config, envVars, workspaceFiles, profiles.		 Enum: [skills config envVars workspaceFiles profiles]
Optional: {}
protectedKeys string array ProtectedKeys is the list of glob expressions over JSON paths that may
not be mutated by HermesSelfConfig. Required (non-empty) when Enabled=true.		 Optional: {}

ServiceAccountDefaults

ServiceAccountDefaults defaults the per-instance SA annotations (IRSA / WI).

Appears in:

Field Description Default Validation
annotations object (keys:string, values:string) Optional: {}

ServiceDefaults

ServiceDefaults defaults the Service kind cluster-wide.

Appears in:

Field Description Default Validation
type ServiceType Enum: [ClusterIP NodePort LoadBalancer]
Optional: {}

ServiceMonitorSpec

ServiceMonitorSpec controls Prometheus-Operator ServiceMonitor emission. When Enabled is true, the operator emits an unstructured ServiceMonitor; it does not require the Prometheus-Operator CRDs to be installed at compile time.

Appears in:

Field Description Default Validation
enabled boolean false Optional: {}
labels object (keys:string, values:string) Labels are extra labels applied onto the ServiceMonitor for Prometheus
label-selector matching (e.g. release: kube-prometheus-stack).		 Optional: {}
interval string Interval: default "30s". 30s Pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Optional: {}
scrapeTimeout string ScrapeTimeout: default "10s". 10s Pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Optional: {}

ServiceSpec

ServiceSpec controls the agent's Service.

Appears in:

Field Description Default Validation
type ServiceType Type is the Service kind. Default ClusterIP (headed): Plan 1 emitted a
headless Service; v1 keeps ClusterIP as the default and lets users opt
into Headless via Type=ClusterIP with ClusterIP="None" through the spec.		 ClusterIP Enum: [ClusterIP NodePort LoadBalancer]
Optional: {}
clusterIP string ClusterIP: set to "None" for a headless Service. Default empty (api-server allocates). Optional: {}
ports NamedServicePort array Ports is the list of Service ports. If empty, the operator emits a default
"gateway" port on 8443 (matches the StatefulSet's container port).		 Optional: {}
annotations object (keys:string, values:string) Annotations are applied verbatim onto the Service (LoadBalancer hints, etc.). Optional: {}
loadBalancerClass string LoadBalancerClass is propagated when Type=LoadBalancer. Optional: {}
externalTrafficPolicy ServiceExternalTrafficPolicyType ExternalTrafficPolicy is propagated when Type=LoadBalancer or NodePort. Enum: [Cluster Local]
Optional: {}

SignalGatewaySpec

SignalGatewaySpec binds the agent to signal-cli-rest-api running as a sidecar or external service.

Appears in:

Field Description Default Validation
enabled boolean false Optional: {}
phoneNumberSecretRef SecretKeySelector Optional: {}
authTokenSecretRef SecretKeySelector Optional: {}

SlackGatewaySpec

SlackGatewaySpec binds the agent to a Slack workspace via the bolt SDK.

Appears in:

Field Description Default Validation
enabled boolean false Optional: {}
botTokenSecretRef SecretKeySelector Optional: {}
appTokenSecretRef SecretKeySelector Optional: {}
signingSecretRef SecretKeySelector Optional: {}

StorageSpec

StorageSpec controls the PVC backing the agent's data directory.

Appears in:

Field Description Default Validation
persistence PersistenceSpec

TailscaleAuthKey

TailscaleAuthKey points at the Secret key holding the Tailscale auth key.

Appears in:

Field Description Default Validation
secretRef SecretKeySelector Optional: {}

TailscaleImageSpec

TailscaleImageSpec pins the tailscale sidecar image.

Appears in:

Field Description Default Validation
repository string tailscale/tailscale Optional: {}
tag string v1.86.2 Optional: {}
pullPolicy string IfNotPresent Enum: [Always IfNotPresent Never]
Optional: {}

TailscaleSpec

TailscaleSpec configures exposing the hermes gateway over a Tailscale tailnet.

Appears in:

Field Description Default Validation
enabled boolean Enabled turns on the operator-managed Tailscale sidecar. false Optional: {}
mode string Mode selects how the gateway is exposed over the tailnet. Only "serve"
is implemented today (private tailnet exposure with a Tailscale TLS cert).		 serve Enum: [serve]
Optional: {}
authKey TailscaleAuthKey AuthKey references the Secret holding a reusable, ephemeral Tailscale auth
key, exposed to the sidecar as TS_AUTHKEY. Required when Enabled is true.		 Optional: {}
hostname string Hostname overrides the tailnet/MagicDNS hostname. Defaults to metadata.name. MaxLength: 63
Pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$
Optional: {}
image TailscaleImageSpec Image overrides the tailscale sidecar image. Optional: {}
resources ResourceRequirements Resources sets the sidecar resource requirements. Optional: {}

TelegramGatewaySpec

TelegramGatewaySpec binds the agent to a Telegram Bot API token.

Appears in:

Field Description Default Validation
enabled boolean false Optional: {}
botTokenSecretRef SecretKeySelector BotTokenSecretRef points at the Secret holding the Bot API token.
Required when Enabled.		 Optional: {}
allowedUserIDs integer array AllowedUserIDs is an optional allow-list of Telegram user IDs. Optional: {}
webhookURL string WebhookURL is the public HTTPS URL to register with Telegram. When empty
the agent runs in long-poll mode.		 Optional: {}

UVCacheVolumeSpec

UVCacheVolumeSpec mirrors a stripped-down VolumeSource union. Exactly one of EmptyDir or PersistentVolumeClaim may be set; the defaulter fills EmptyDir when both are nil.

Appears in:

Field Description Default Validation
emptyDir EmptyDirVolumeSource Optional: {}
persistentVolumeClaim PersistentVolumeClaimVolumeSource Optional: {}

UVSpec

UVSpec controls the uv sync init container.

Appears in:

Field Description Default Validation
enabled boolean true Optional: {}
extraIndexURL string ExtraIndexURL is appended to uv's index list. Useful for private PyPI
mirrors. Empty by default.		 Optional: {}
cacheVolume UVCacheVolumeSpec CacheVolume controls the volume mounted at /home/hermes/.cache/uv.
Defaults to an emptyDir with a 1Gi sizeLimit: fast and ephemeral.		 Optional: {}

WhatsAppGatewaySpec

WhatsAppGatewaySpec binds the agent to a WhatsApp provider (Twilio, Meta Cloud API, etc.).

Appears in:

Field Description Default Validation
enabled boolean false Optional: {}
providerSecretRef SecretKeySelector Optional: {}

WorkspaceBootstrap

WorkspaceBootstrap toggles the first-start bootstrap script.

Appears in:

Field Description Default Validation
enabled boolean Enabled: default false. Plan 3 wires the actual init-container. false Optional: {}

WorkspaceFile

WorkspaceFile is a single seeded file. Nested paths are allowed; the workspace ConfigMap encodes them with "__" separators (decoded by runtime-init).

Appears in:

Field Description Default Validation
path string Path is the relative path under ~/.hermes (e.g. "notes/finance/2026.md"). MaxLength: 4096
MinLength: 1
Pattern: ^[^/].*[^/]$|^[^/]$
content string Content is the UTF-8 body. Binary content must be base64-encoded by the
caller and decoded by the bootstrap step (out of scope of v1 schema).		 MaxLength: 1048576

WorkspaceSpec

WorkspaceSpec seeds initial files and directories into ~/.hermes on first start. Path values support arbitrary nested directories ("a/b/c.md" is fine); the workspace ConfigMap encodes nested paths using "__" as the separator so a single-level ConfigMap data map can express them: Plan 3's runtime-init container decodes the keys back to filesystem paths before invoking the agent.

Lesson from openclaw #482: do not constrain Path to a single segment; that caused users to flatten their notes into hash-separated filenames.

Appears in:

Field Description Default Validation
initialFiles WorkspaceFile array InitialFiles is the list of files to seed.
SSA list-map key is "path" so HermesSelfConfig (Plan 4) can patch entries
in place without replacing the whole slice.		 Optional: {}
initialDirs string array InitialDirs is the list of directories to mkdir -p on first start. Optional: {}
configMapRef LocalObjectReference ConfigMapRef references a user-owned ConfigMap whose entries are merged
onto InitialFiles (operator-managed entries win on conflict).		 Optional: {}
bootstrap WorkspaceBootstrap Bootstrap controls the optional one-shot bootstrap script that hermes-agent
runs on first start (e.g. hermes onboard). Default disabled.		 Optional: {}