AgentHarness
kagent.dev / v1alpha2
apiVersion: kagent.dev/v1alpha2
kind: AgentHarness
metadata:
name: example
apiVersion
string
APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
kind
string
Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
metadata
object
spec object
AgentHarnessSpec describes a generic remote execution environment that agents
(or human operators) can attach to via exec or SSH.
An AgentHarness is distinct from a SandboxAgent: it has no agent runtime baked
in. The backend is responsible for provisioning an environment that stays
ready to accept incoming commands.
backend
string required
Backend selects the control plane to use. Required.
enum:
openclaw, nemoclaw, hermeschannels []object
Channels configures Telegram and Slack integrations for OpenClaw inside the harness VM.
maxItems:
1024
name
string required
Name is a stable id for this binding (OpenClaw channels.*.accounts key).
minLength:
1slack object
Slack configures Slack when type is Slack.
appToken object required
AgentHarnessChannelCredential supplies a token from an inline value or a Secret/ConfigMap key.
value
string
maxLength:
8192valueFrom object
ValueSource defines a source for configuration values from a Secret or ConfigMap
key
string required
The key of the ConfigMap or Secret.
maxLength:
253
name
string required
The name of the ConfigMap or Secret.
maxLength:
253
type
string required
enum:
ConfigMap, SecretbotToken object required
AgentHarnessChannelCredential supplies a token from an inline value or a Secret/ConfigMap key.
value
string
maxLength:
8192valueFrom object
ValueSource defines a source for configuration values from a Secret or ConfigMap
key
string required
The key of the ConfigMap or Secret.
maxLength:
253
name
string required
The name of the ConfigMap or Secret.
maxLength:
253
type
string required
enum:
ConfigMap, Secrethermes object
Hermes configures Hermes-specific Slack settings.
allowedUserIDs
[]string
AllowedUserIDs restricts which Slack member IDs may interact with the bot (SLACK_ALLOWED_USERS).
maxItems:
1024allowedUserIDsFrom object
ValueSource defines a source for configuration values from a Secret or ConfigMap
key
string required
The key of the ConfigMap or Secret.
maxLength:
253
name
string required
The name of the ConfigMap or Secret.
maxLength:
253
type
string required
enum:
ConfigMap, Secret
homeChannel
string
HomeChannel is the default Slack channel ID for cron/scheduled messages (SLACK_HOME_CHANNEL).
homeChannelName
string
HomeChannelName is a human-readable label for HomeChannel (SLACK_HOME_CHANNEL_NAME).
openclaw object
OpenClaw configures OpenClaw/NemoClaw-specific Slack routing.
allowlistChannels
[]string
AllowlistChannels is required when channelAccess is allowlist.
maxItems:
1024
channelAccess
string
AgentHarnessChannelAccess controls whether the bot listens broadly or only on an allowlist.
enum:
allowlist, open, disabled
interactiveReplies
boolean
telegram object
AgentHarnessTelegramChannelSpec configures Telegram when AgentHarnessChannel.type is Telegram.
allowedUserIDs
[]string
maxItems:
1024allowedUserIDsFrom object
ValueSource defines a source for configuration values from a Secret or ConfigMap
key
string required
The key of the ConfigMap or Secret.
maxLength:
253
name
string required
The name of the ConfigMap or Secret.
maxLength:
253
type
string required
enum:
ConfigMap, SecretbotToken object required
AgentHarnessChannelCredential supplies a token from an inline value or a Secret/ConfigMap key.
value
string
maxLength:
8192valueFrom object
ValueSource defines a source for configuration values from a Secret or ConfigMap
key
string required
The key of the ConfigMap or Secret.
maxLength:
253
name
string required
The name of the ConfigMap or Secret.
maxLength:
253
type
string required
enum:
ConfigMap, Secret
type
string required
AgentHarnessChannelType selects a messenger integration for OpenClaw harness VMs.
enum:
telegram, slack
description
string
Description is a short human-readable summary shown in the UI (e.g. agents list).
env []object
Env is a list of environment variables injected into the harness workload.
Values use the Kubernetes EnvVar shape; ValueFrom references are
resolved server-side where supported.
name
string required
Name of the environment variable.
May consist of any printable ASCII characters except '='.
value
string
Variable references $(VAR_NAME) are expanded
using the previously defined environment variables in the container and
any service environment variables. If a variable cannot be resolved,
the reference in the input string will be unchanged. Double $$ are reduced
to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e.
"$$(VAR_NAME)" will produce the string literal "$(VAR_NAME)".
Escaped references will never be expanded, regardless of whether the variable
exists or not.
Defaults to "".
valueFrom object
Source for the environment variable's value. Cannot be used if value is not empty.
configMapKeyRef object
Selects a key of a ConfigMap.
key
string required
The key to select.
name
string
Name of the referent.
This field is effectively required, but due to backwards compatibility is
allowed to be empty. Instances of this type with an empty value here are
almost certainly wrong.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
optional
boolean
Specify whether the ConfigMap or its key must be defined
fieldRef object
Selects a field of the pod: supports metadata.name, metadata.namespace, `metadata.labels['<KEY>']`, `metadata.annotations['<KEY>']`,
spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs.
apiVersion
string
Version of the schema the FieldPath is written in terms of, defaults to "v1".
fieldPath
string required
Path of the field to select in the specified API version.
fileKeyRef object
FileKeyRef selects a key of the env file.
Requires the EnvFiles feature gate to be enabled.
key
string required
The key within the env file. An invalid key will prevent the pod from starting.
The keys defined within a source may consist of any printable ASCII characters except '='.
During Alpha stage of the EnvFiles feature gate, the key size is limited to 128 characters.
optional
boolean
Specify whether the file or its key must be defined. If the file or key
does not exist, then the env var is not published.
If optional is set to true and the specified key does not exist,
the environment variable will not be set in the Pod's containers.
If optional is set to false and the specified key does not exist,
an error will be returned during Pod creation.
path
string required
The path within the volume from which to select the file.
Must be relative and may not contain the '..' path or start with '..'.
volumeName
string required
The name of the volume mount containing the env file.
resourceFieldRef object
Selects a resource of the container: only resources limits and requests
(limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported.
containerName
string
Container name: required for volumes, optional for env vars
divisor
string | integer
Specifies the output format of the exposed resources, defaults to "1"
string pattern:
^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
resource
string required
Required: resource to select
secretKeyRef object
Selects a key of a secret in the pod's namespace
key
string required
The key of the secret to select from. Must be a valid secret key.
name
string
Name of the referent.
This field is effectively required, but due to backwards compatibility is
allowed to be empty. Instances of this type with an empty value here are
almost certainly wrong.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
optional
boolean
Specify whether the Secret or its key must be defined
image
string
Image is the container image to run in the harness VM, if the backend
supports per-resource images. Backends openclaw and nemoclaw pin the image
to the NemoClaw sandbox base when this field is empty; backend hermes pins
to the Hermes sandbox base image when empty.
modelConfigRef
string
ModelConfigRef is the reference to the ModelConfig used to configure the harness.
The controller registers the gateway provider and, after the harness is Ready,
writes OpenClaw config inside the VM (~/.openclaw/openclaw.json) and starts the gateway.
network object
Network controls outbound access from the harness. When unset,
backend defaults apply.
allowedDomains
[]string
AllowedDomains is a list of DNS names the harness may reach.
runtime
string
Runtime selects the harness provisioning stack. Defaults to openshell when unset.
enum:
openshell, substratesubstrate object
Substrate is required when runtime is substrate.
gatewayToken
string
GatewayToken is the OpenClaw gateway Bearer token for this harness.
Prefer gatewayTokenSecretRef for production secrets.
minLength:
1gatewayTokenSecretRef object
GatewayTokenSecretRef references a Secret key holding the OpenClaw gateway Bearer token.
The Secret must contain a "token" key.
apiGroup
string
kind
string
name
string required
snapshotsConfig object
SnapshotsConfig configures actor memory snapshots. Defaults to
gs://ate-snapshots/<namespace>/<agentharnessname> when unset.
location
string required
Location is the GCS URI prefix for golden and incremental snapshots.
Example: gs://ate-snapshots/kagent/my-namespace/my-harness/
pattern:
^gs://workerPoolRef object
WorkerPoolRef references an existing ate.dev WorkerPool in the harness namespace.
When unset, the controller uses its configured default WorkerPool.
apiGroup
string
kind
string
name
string required
workloadImage
string
WorkloadImage overrides the default nemoclaw/openclaw sandbox image in the ActorTemplate.
status object
AgentHarnessStatus is the observed state of an AgentHarness.
backendRef object
BackendRef points at the harness instance on the backend control
plane, once Ensure has succeeded at least once.
backend
string required
AgentHarnessBackendType selects which sandbox control plane provisions the
environment. Additional backends may be added in the future.
enum:
openclaw, nemoclaw, hermes
id
string required
conditions []object
lastTransitionTime
string required
lastTransitionTime is the last time the condition transitioned from one status to another.
This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.
format:
date-time
message
string required
message is a human readable message indicating details about the transition.
This may be an empty string.
maxLength:
32768
observedGeneration
integer
observedGeneration represents the .metadata.generation that the condition was set based upon.
For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date
with respect to the current state of the instance.
format:
int64minimum:
0
reason
string required
reason contains a programmatic identifier indicating the reason for the condition's last transition.
Producers of specific condition types may define expected values and meanings for this field,
and whether the values are considered a guaranteed API.
The value should be a CamelCase string.
This field may not be empty.
pattern:
^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$minLength:
1maxLength:
1024
status
string required
status of the condition, one of True, False, Unknown.
enum:
True, False, Unknown
type
string required
type of condition in CamelCase or in foo.example.com/CamelCase.
pattern:
^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$maxLength:
316connection object
Connection is populated by the controller when the harness is ready.
endpoint
string
Endpoint is the backend-specific address (gRPC target, SSH host:port,
...) clients should use to reach the harness.
observedGeneration
integer
format:
int64No matches. Try .spec.backend for an exact path