API Reference

Packages

• langop.io/v1alpha1

langop.io/v1alpha1

Package v1alpha1 contains API Schema definitions for the language v1alpha1 API group

Resource Types

• LanguageAgent
• LanguageAgentRuntime
• LanguageAgentSelfConfig
• LanguageCluster
• LanguageModel
• LanguagePersona
• LanguageTool

AgentMonitoringSpec

AgentMonitoringSpec defines Prometheus Operator integration for a LanguageAgent.

Appears in: - LanguageAgentSpec

Field	Description	Default	Validation
serviceMonitor AgentServiceMonitorSpec	ServiceMonitor configures a ServiceMonitor resource for this agent.		Optional: {}
rules PrometheusRuleGroup array	Rules defines PrometheusRule groups for this agent. When non-empty, the operator creates a PrometheusRule resource.		Optional: {}

AgentNetworkPolicies

AgentNetworkPolicies defines user-supplied ingress and egress rules for an agent workload. The shape mirrors the native Kubernetes NetworkPolicySpec so that rules can be copied verbatim from real NetworkPolicy manifests.

Appears in: - LanguageAgentSpec - LanguageClusterSpec - LanguageToolSpec

Field	Description	Default	Validation
ingress NetworkIngressRule array	Ingress rules — each entry allows traffic into the workload from the listed sources.		Optional: {}
egress NetworkEgressRule array	Egress rules — each entry allows traffic from the workload to the listed destinations.		Optional: {}

AgentPort

AgentPort describes a single network port that an agent container exposes.

Appears in: - LanguageAgentRuntimeSpec - LanguageAgentSpec

Field	Description	Default	Validation
name string	Name uniquely identifies this port within the agent (e.g., "web", "ws"). Used as the Service port name; must conform to Kubernetes port-name rules.		MaxLength: 15 Pattern: ^[a-z][a-z0-9-]*$ Required: {}
port integer	Port is the port number the container listens on.		Maximum: 65535 Minimum: 1 Required: {}
protocol Protocol	Protocol is the transport protocol. Defaults to TCP.	TCP	Enum: [TCP UDP SCTP] Optional: {}
expose boolean	Expose controls whether ingress/HTTPRoute routes to this port. At most one port should have expose: true; if none, the first port is used.	false	Optional: {}

AgentServiceMonitorSpec

AgentServiceMonitorSpec configures a Prometheus Operator ServiceMonitor for an agent.

Appears in: - AgentMonitoringSpec

Field	Description	Default	Validation
enabled boolean	Enabled controls whether a ServiceMonitor is created for this agent.
port string	Port is the name of the service port to scrape for metrics. Defaults to the name of the first port in spec.ports, or "http" if no ports are defined.		Optional: {}
path string	Path is the HTTP path to scrape for metrics. Defaults to /metrics.		Optional: {}
interval string	Interval is the scrape interval (e.g. "30s"). Uses the Prometheus default when omitted.		Optional: {}
scrapeTimeout string	ScrapeTimeout is the per-scrape timeout. Uses the Prometheus default when omitted.		Optional: {}
labels object (keys:string, values:string)	Labels are additional labels added to the ServiceMonitor metadata.		Optional: {}

AutoscalingSpec

AutoscalingSpec configures a HorizontalPodAutoscaler for the deployment.

Appears in: - DeploymentSpec

Field	Description	Default	Validation
minReplicas integer	MinReplicas is the lower bound for replicas the HPA can scale down to. Defaults to 1 if not specified.		Minimum: 1 Optional: {}
maxReplicas integer	MaxReplicas is the upper bound for replicas the HPA can scale up to.		Minimum: 1
metrics MetricSpec array	Metrics specifies which metrics to use for scaling. Defaults to 80% average CPU utilization if not specified.		Optional: {}

ClusterAuthSpec

ClusterAuthSpec configures OIDC authentication for a LanguageCluster.

Appears in: - LanguageClusterSpec

Field	Description	Default	Validation
enabled boolean	Enabled controls whether OIDC authentication is active for this cluster.		Optional: {}
oidc ClusterOIDCSpec	OIDC configures the OIDC provider (embedded Dex or external).		Optional: {}

ClusterCapacitySpec

ClusterCapacitySpec declares hard limits enforced via a ResourceQuota in the cluster's namespace.

Appears in: - LanguageClusterSpec

Field	Description	Default	Validation
maxAgents integer	MaxAgents is the maximum number of LanguageAgent objects allowed.		Optional: {}
maxModels integer	MaxModels is the maximum number of LanguageModel objects allowed.		Optional: {}
maxTools integer	MaxTools is the maximum number of LanguageTool objects allowed.		Optional: {}
maxPersonas integer	MaxPersonas is the maximum number of LanguagePersona objects allowed.		Optional: {}
maxCPU Quantity	MaxCPU is the aggregate CPU limit for all pods in the cluster namespace. Maps to limits.cpu in the namespace ResourceQuota. Example: "4", "2500m"		Optional: {}
maxMemory Quantity	MaxMemory is the aggregate memory limit for all pods in the cluster namespace. Maps to limits.memory in the namespace ResourceQuota. Example: "8Gi", "512Mi"		Optional: {}

ClusterCapacityStatus

ClusterCapacityStatus reports observed resource usage in the cluster's namespace.

Appears in: - LanguageClusterStatus

Field	Description	Default	Validation
agentCount integer	AgentCount is the number of LanguageAgent objects in the cluster namespace.
modelCount integer	ModelCount is the number of LanguageModel objects in the cluster namespace.
toolCount integer	ToolCount is the number of LanguageTool objects in the cluster namespace.
personaCount integer	PersonaCount is the number of LanguagePersona objects in the cluster namespace.
totalCPULimits Quantity	TotalCPULimits is the sum of limits.cpu across all agent pod specs.		Optional: {}
totalMemoryLimits Quantity	TotalMemoryLimits is the sum of limits.memory across all agent pod specs.		Optional: {}

ClusterOIDCSpec

ClusterOIDCSpec configures the OIDC provider for the cluster.

Appears in: - ClusterAuthSpec

Field	Description	Default	Validation
dex DexSpec	Dex configures the embedded Dex OIDC provider. When set (and ExternalIssuerURL is not), the controller deploys Dex alongside the gateway.		Optional: {}
externalIssuerURL string	ExternalIssuerURL skips deploying Dex and uses this issuer URL for oauth2-proxy. Mutually exclusive with dex. Example: "https://accounts.google.com"		Optional: {}
clientID string	ClientID is the OAuth2 client ID when using an external OIDC provider. Ignored when dex is configured (the operator manages the client ID).		Optional: {}
clientSecretRef SecretReference	ClientSecretRef references a Secret containing the OAuth2 client secret. Ignored when dex is configured (the operator manages the client secret).		Optional: {}
emailDomain string	EmailDomain restricts login to users with this email domain. Set to "*" to allow all email domains (default).		Optional: {}

CredentialSpec

CredentialSpec declares an environment variable backed by a Secret value. The operator resolves it once and injects it into the agent container. Source priority: ValueFrom (existing Secret) > Value (inline) > auto-generate.

Appears in: - LanguageAgentRuntimeSpec - LanguageAgentSpec

Field	Description	Default	Validation
name string	Name is the environment variable name and the key within the operator-managed Secret (e.g. OPENCLAW_GATEWAY_TOKEN, OPENCODE_SERVER_PASSWORD).		Required: {}
value string	Value, when set, is stored verbatim in the managed Secret instead of generating a random credential. Mutually exclusive with ValueFrom.		Optional: {}
valueFrom RuntimeSecretRef	ValueFrom references an existing Secret whose keys are injected via envFrom. When set, the operator does not create or manage a Secret for this entry. Mutually exclusive with Value.		Optional: {}

DeploymentSpec

DeploymentSpec groups Kubernetes deployment configuration that is common across LanguageAgent, LanguageTool, and LanguageCluster gateway deployments. All fields are optional; controllers only read the fields relevant to their resource.

Appears in: - GatewaySpec - LanguageAgentRuntimeSpec - LanguageAgentSpec - LanguageToolSpec

Field	Description	Default	Validation
replicas integer	Replicas is the number of pod replicas to run.		Minimum: 0 Optional: {}
imagePullPolicy PullPolicy	ImagePullPolicy defines when to pull the container image.		Enum: [Always Never IfNotPresent] Optional: {}
imagePullSecrets LocalObjectReference array	ImagePullSecrets is a list of references to secrets for pulling images.		Optional: {}
env EnvVar array	Env contains environment variables for the container.		Optional: {}
envFrom EnvFromSource array	EnvFrom sources to populate environment variables.		Optional: {}
resources ResourceRequirements	Resources defines compute resource requirements.		Optional: {}
nodeSelector object (keys:string, values:string)	NodeSelector is a selector which must match a node's labels.		Optional: {}
affinity Affinity	Affinity defines pod affinity and anti-affinity rules.		Optional: {}
tolerations Toleration array	Tolerations allow pods to schedule onto nodes with matching taints.		Optional: {}
topologySpreadConstraints TopologySpreadConstraint array	TopologySpreadConstraints describes how pods should spread across topology domains.		Optional: {}
serviceAccountName string	ServiceAccountName is the name of the ServiceAccount to use.		Optional: {}
serviceAccountAnnotations object (keys:string, values:string)	ServiceAccountAnnotations are annotations to add to the operator-managed ServiceAccount. Use this to attach cloud workload identity bindings, e.g. AWS IRSA, GCP WI, AKS WI. Ignored when ServiceAccountName is set.		Optional: {}
roleRules PolicyRule array	RoleRules are additional RBAC policy rules appended to the operator-managed Role. Use this to grant the agent extra in-cluster permissions beyond the defaults (configmaps get/list, pods get/list/watch). Ignored when ServiceAccountName is set.		Optional: {}
securityContext PodSecurityContext	SecurityContext holds pod-level security attributes.		Optional: {}
volumeMounts VolumeMount array	VolumeMounts to mount into the container.		Optional: {}
volumes Volume array	Volumes to attach to the pod.		Optional: {}
podAnnotations object (keys:string, values:string)	PodAnnotations are annotations to add to the Pods.		Optional: {}
podLabels object (keys:string, values:string)	PodLabels are additional labels to add to the Pods.		Optional: {}
initContainers Container array	InitContainers are additional init containers injected before the main container starts.		Optional: {}
livenessProbe Probe	LivenessProbe defines the liveness probe for the container.		Optional: {}
readinessProbe Probe	ReadinessProbe defines the readiness probe for the container.		Optional: {}
startupProbe Probe	StartupProbe defines the startup probe for the container.		Optional: {}
command string array	Command overrides the container entrypoint.		Optional: {}
args string array	Args overrides the container command arguments.		Optional: {}
serviceType ServiceType	ServiceType specifies the type of Service to create (ClusterIP, NodePort, LoadBalancer).		Enum: [ClusterIP NodePort LoadBalancer] Optional: {}
serviceAnnotations object (keys:string, values:string)	ServiceAnnotations are annotations to add to the Service.		Optional: {}
autoscaling AutoscalingSpec	Autoscaling enables and configures a HorizontalPodAutoscaler for this deployment. When set, the HPA manages the replica count; spec.deployment.replicas is used as the initial desired count only and is no longer written on each reconcile.		Optional: {}

DexConnector

DexConnector configures a Dex upstream identity provider connector.

Appears in: - DexSpec

Field	Description	Default	Validation
type string	Type is the connector type: "github", "google", "oidc", "ldap", "microsoft", "saml", etc. See https://dexidp.io/docs/connectors/ for the full list.		Required: {}
id string	ID is the connector's unique identifier.		Required: {}
name string	Name is the human-readable display name shown on the Dex login page.		Required: {}
config object (keys:string, values:string)	Config contains connector-specific configuration key/value pairs.		Optional: {}

DexSpec

DexSpec configures the embedded Dex OIDC provider.

Appears in: - ClusterOIDCSpec

Field	Description	Default	Validation
connectors DexConnector array	Connectors configures upstream identity providers (GitHub, Google, OIDC, etc.).		Optional: {}
enablePasswordDB boolean	EnablePasswordDB enables Dex's built-in local password store. When true, Dex presents a username/password login form backed by StaticPasswords. This is independent of connectors — both can be active simultaneously.		Optional: {}
staticPasswords DexStaticPassword array	StaticPasswords defines local user accounts for Dex's built-in password store. Only used when EnablePasswordDB is true.		Optional: {}
image string	Image overrides the Dex container image. Defaults to the operator Helm chart's config.auth.dex.image value.		Optional: {}

DexStaticPassword

DexStaticPassword defines a local user account in Dex's built-in password store.

Appears in: - DexSpec

Field	Description	Default	Validation
email string	Email is the user's login email address.		Required: {}
hash string	Hash is the bcrypt hash of the user's password. Generate with: htpasswd -nbBC 10 "" | tr -d ':\n' | sed 's/$2y/$2a/'		Required: {}
username string	Username is the display name shown after login.		Optional: {}
userID string	UserID is a stable unique identifier for this user.		Optional: {}

GatewaySpec

GatewaySpec configures the shared LiteLLM gateway deployed per LanguageCluster.

Appears in: - LanguageClusterSpec

Field	Description	Default	Validation
deployment DeploymentSpec	Deployment configures the Kubernetes deployment for the gateway pod.		Optional: {}

IngressConfig

IngressConfig defines ingress configuration

Appears in: - LanguageClusterSpec

Field	Description	Default	Validation
enabled boolean	Enabled controls whether an external Ingress is created for the shared gateway. Defaults to false — the gateway is reachable in-cluster via its Service. Set to true to expose it externally at gateway..		Optional: {}
tls IngressTLSConfig	TLS configuration for agent webhooks		Optional: {}
className string	ClassName specifies the IngressClass to use (maps to spec.ingressClassName on the Ingress object).		Optional: {}

IngressTLSConfig

IngressTLSConfig defines TLS configuration

Appears in: - IngressConfig

Field	Description	Default	Validation
enabled boolean	Enabled controls whether TLS is enabled for webhooks. Defaults to true; set to false to disable TLS.	true	Optional: {}
secretName string	SecretName is the name of an existing TLS secret (bring-your-own certificate). When set, cert-manager integration is skipped and this secret is used directly.		Optional: {}

LanguageAgent

LanguageAgent is the Schema for the languageagents API

Field	Description	Default	Validation
apiVersion string	langop.io/v1alpha1
kind string	LanguageAgent
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec LanguageAgentSpec
status LanguageAgentStatus

LanguageAgentRuntime

LanguageAgentRuntime is the Schema for the languageagentruntimes API. It defines a reusable preset for LanguageAgent deployments, analogous to an IngressClass. Admins create runtimes; users reference them via spec.runtime on a LanguageAgent.

Field	Description	Default	Validation
apiVersion string	langop.io/v1alpha1
kind string	LanguageAgentRuntime
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec LanguageAgentRuntimeSpec

LanguageAgentRuntimeSpec

LanguageAgentRuntimeSpec defines a preset configuration for LanguageAgent deployments. All fields are optional; unset fields leave the agent's own spec in effect. When a LanguageAgent references a runtime, the runtime's fields are merged as defaults: scalars fill in zeros/nils (agent wins if set), lists are runtime-first then agent-appended.

Appears in: - LanguageAgentRuntime

Field	Description	Default	Validation
image string	Image is the default container image for agents using this runtime. Agents may override this. When a runtime is referenced, spec.image on the agent is optional.		Optional: {}
ports AgentPort array	Ports defines default ports for agents using this runtime. Replace semantics: when the agent defines spec.ports, runtime ports are ignored entirely.		Optional: {}
deployment DeploymentSpec	Deployment provides default Kubernetes pod and container configuration. Scalars (args, command, resources, probes, etc.) are used when the agent has none set. Lists (initContainers, env, volumes, volumeMounts, envFrom) are runtime-first, agent-appended.		Optional: {}
credentials CredentialSpec array	Credentials declares environment variables backed by Secret values that the operator resolves and injects into agents using this runtime. Each entry is auto-generated, set inline, or sourced from an existing Secret. Merged into the agent's effective spec runtime-first; agent entries override by name.		Optional: {}
auth RuntimeAuthSpec	Auth gates whether agents using this runtime sit behind the cluster OIDC proxy. Effective only when the cluster has auth enabled (which provisions the OIDC infrastructure). The OIDC connection itself is configured cluster-wide.		Optional: {}

LanguageAgentSelfConfig

LanguageAgentSelfConfig is submitted by an agent pod to request runtime modifications to its own LanguageAgent spec. The controller validates the request against the parent's spec.selfConfigure allowlist before patching.

Field	Description	Default	Validation
apiVersion string	langop.io/v1alpha1
kind string	LanguageAgentSelfConfig
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec LanguageAgentSelfConfigSpec
status LanguageAgentSelfConfigStatus

LanguageAgentSelfConfigSpec

LanguageAgentSelfConfigSpec defines the desired self-modification.

Appears in: - LanguageAgentSelfConfig

Field	Description	Default	Validation
instanceRef string	InstanceRef is the name of the LanguageAgent to modify. Must be in the same namespace.		MinLength: 1 Required: {}
addTools string array	AddTools lists LanguageTool names to append to spec.tools on the parent agent.		Optional: {}
removeTools string array	RemoveTools lists LanguageTool names to remove from spec.tools on the parent agent.		Optional: {}
addModels string array	AddModels lists LanguageModel names to append to spec.models on the parent agent.		Optional: {}
removeModels string array	RemoveModels lists LanguageModel names to remove from spec.models on the parent agent.		Optional: {}
addEnvVars SelfConfigEnvVar array	AddEnvVars lists plain-value environment variables to inject into the parent agent's spec.deployment.env. Existing vars with the same name are overwritten. SecretKeyRef and other value sources are not supported.		Optional: {}
updateInstructions string	UpdateInstructions, when non-empty, replaces spec.instructions on the parent agent.		Optional: {}
addRoleRules PolicyRule array	AddRoleRules lists RBAC policy rules to append to spec.deployment.roleRules on the parent agent. Duplicate rules (identical APIGroups+Resources+Verbs) are de-duplicated.		Optional: {}

LanguageAgentSelfConfigStatus

LanguageAgentSelfConfigStatus reflects the observed state of a self-config request.

Appears in: - LanguageAgentSelfConfig

Field	Description	Default	Validation
phase SelfConfigPhase	Phase is the current processing state.		Enum: [Pending Applied Failed Denied] Optional: {}
message string	Message provides a human-readable explanation of the current phase.		Optional: {}
completionTime Time	CompletionTime is set when the request reaches a terminal phase (Applied, Failed, Denied). The CR is automatically deleted 1 hour after this time.		Optional: {}

LanguageAgentSpec

LanguageAgentSpec defines the desired state of LanguageAgent

Appears in: - LanguageAgent

Field	Description	Default	Validation
runtime string	Runtime is the name of a LanguageAgentRuntime that provides preset configuration (image, port, init containers, env vars, probes, etc.). When set, spec.image is optional; the runtime provides a default.		Optional: {}
image string	Image is the container image to run for this agent. Required unless spec.runtime is set (the runtime provides a default image).		Pattern: ^([a-z0-9]+([._-][a-z0-9]+)*\/)*[a-z0-9]+([._-][a-z0-9]+)*(:[a-z0-9]+([._-][a-z0-9]+)*)?$ Optional: {}
models ModelReference array	Models is a list of LanguageModel references this agent can use		Optional: {}
tools ToolReference array	Tools is a list of LanguageTool references available to this agent		Optional: {}
persona string	Persona is the name of a LanguagePersona this agent uses		Optional: {}
instructions string	Instructions provides system instructions for the agent. Delivered as the top-level "instructions" field in /etc/agent/config.yaml.		Optional: {}
workspace WorkspaceSpec	Workspace defines persistent storage for the agent		Optional: {}
repository RepositorySpec	Repository declares a git repository to clone into the agent's workspace. When set, the operator ensures a workspace PVC is provisioned (defaulting it on if not explicitly configured) so the clone has somewhere to land.		Optional: {}
networkPolicies AgentNetworkPolicies	NetworkPolicies defines ingress and egress rules for this agent. Rules mirror the native Kubernetes NetworkPolicy shape.		Optional: {}
ports AgentPort array	Ports defines all network ports this agent exposes. At most one entry should have expose: true (the ingress target); if none are marked, the first port is used for ingress routing. Defaults to a single HTTP port on 8080 when not set.		Optional: {}
deployment DeploymentSpec	Deployment groups Kubernetes-specific pod and container configuration.		Optional: {}
credentials CredentialSpec array	Credentials declares environment variables backed by Secret values that the operator resolves and injects into the agent container. Typically supplied by the referenced LanguageAgentRuntime; agents may add or override entries by name.		Optional: {}
selfConfigure SelfConfigureSpec	SelfConfigure controls whether this agent may submit LanguageAgentSelfConfig requests to modify its own spec at runtime. When enabled, the operator grants the agent's ServiceAccount permission to create LanguageAgentSelfConfig resources.		Optional: {}
monitoring AgentMonitoringSpec	Monitoring configures Prometheus Operator integration for this agent. When set, the operator creates a ServiceMonitor and/or PrometheusRule resource. Requires prometheus-operator to be installed in the cluster; silently skipped otherwise.		Optional: {}

LanguageAgentStatus

LanguageAgentStatus defines the observed state of LanguageAgent

Appears in: - LanguageAgent

Field	Description	Default	Validation
phase string	Phase represents the current phase of the agent		Enum: [Pending Running Failed Updating Degraded] Optional: {}
conditions Condition array	Conditions represent the latest available observations of the agent's state		Optional: {}
activeReplicas integer	ActiveReplicas is the number of agent pods currently running		Optional: {}
readyReplicas integer	ReadyReplicas is the number of agent pods ready		Optional: {}
uuid string	UUID is a unique identifier for this agent instance Not used for webhook routing; webhooks are routed via agent name (e.g., .domain.com)		Optional: {}
webhookURLs string array	WebhookURLs contains the URLs where this agent can receive webhooks		Optional: {}
observedGeneration integer	ObservedGeneration is the most recent generation observed by the controller. It corresponds to the metadata.generation of the LanguageAgent at the time the controller last processed it. Watchers can use this to detect when the status reflects a stale version of the spec.		Optional: {}
workspacePVCName string	WorkspacePVCName is the name of the retained workspace PVC after agent deletion. Only set when spec.workspace.retain is true.		Optional: {}
managedResources ManagedResource array	ManagedResources is the inventory of Kubernetes resources created and owned by this controller on behalf of this LanguageAgent. The list is replaced atomically on every successful reconcile.		Optional: {}

LanguageCluster

LanguageCluster is the Schema for the languageclusters API

Field	Description	Default	Validation
apiVersion string	langop.io/v1alpha1
kind string	LanguageCluster
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec LanguageClusterSpec
status LanguageClusterStatus

LanguageClusterSpec

LanguageClusterSpec defines the desired state of LanguageCluster

Appears in: - LanguageCluster

Field	Description	Default	Validation
domain string	Domain is the base domain for the cluster and agent webhook routing. Agent webhooks will be accessible at .. Example: "ai.theryans.io" results in webhooks like "my-agent.ai.theryans.io"		Optional: {}
ingress IngressConfig	Ingress defines ingress configuration for the cluster		Optional: {}
networkPolicies AgentNetworkPolicies	NetworkPolicies defines ingress and egress rules for agents in this cluster. Rules mirror the native Kubernetes NetworkPolicy shape.		Optional: {}
gateway GatewaySpec	Gateway configures the shared LiteLLM gateway deployed per cluster		Optional: {}
capacity ClusterCapacitySpec	Capacity declares hard limits enforced via a ResourceQuota in the cluster's namespace. When set, the controller creates a ResourceQuota named "langop-quota". When unset, any existing "langop-quota" is deleted.		Optional: {}
auth ClusterAuthSpec	Auth configures OIDC authentication for agent ingress routes in this cluster. When enabled, a Dex OIDC provider is deployed alongside the gateway and each LanguageAgent with auth enabled gets an oauth2-proxy in front of its ingress.		Optional: {}

LanguageClusterStatus

LanguageClusterStatus defines the observed state

Appears in: - LanguageCluster

Field	Description	Default	Validation
phase string	Phase of the cluster		Enum: [Pending Ready Failed]
conditions Condition array			Optional: {}
gatewayEndpoint string	GatewayEndpoint is the in-cluster URL for the shared LiteLLM gateway		Optional: {}
gatewayReady boolean	GatewayReady indicates whether the shared gateway Deployment is available. Pointer distinguishes "not yet reconciled" (nil) from "known not ready" (false).		Optional: {}
capacity ClusterCapacityStatus	Capacity reports observed resource usage in this cluster's namespace.		Optional: {}
observedGeneration integer	ObservedGeneration is the most recent generation observed by the controller. It corresponds to the metadata.generation of the LanguageCluster at the time the controller last processed it. Watchers can use this to detect when the status reflects a stale version of the spec.		Optional: {}
managedResources ManagedResource array	ManagedResources is the inventory of Kubernetes resources created and owned by this controller on behalf of this LanguageCluster. The list is replaced atomically on every successful reconcile.		Optional: {}

LanguageModel

LanguageModel is the Schema for the languagemodels API

Field	Description	Default	Validation
apiVersion string	langop.io/v1alpha1
kind string	LanguageModel
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec LanguageModelSpec
status LanguageModelStatus

LanguageModelSpec

LanguageModelSpec defines the desired state of LanguageModel

Appears in: - LanguageModel

Field	Description	Default	Validation
provider string	Provider specifies the LLM provider type		Enum: [openai anthropic openai-compatible azure bedrock vertex custom] Required: {}
modelName string	ModelName is the specific model identifier (e.g., "gpt-4", "claude-3-opus")		MinLength: 1 Required: {}
endpoint string	Endpoint is the API endpoint URL (required for openai-compatible, azure, custom)		Optional: {}
apiKeySecretRef SecretReference	APIKeySecretRef references a secret containing the API key		Optional: {}
rateLimits RateLimitSpec	RateLimits defines rate limiting configuration		Optional: {}
timeout string	Timeout specifies request timeout duration (e.g., "5m", "30s")	5m	Pattern: ^[0-9]+(ns\|us\|µs\|ms\|s\|m\|h)$ Optional: {}

LanguageModelStatus

LanguageModelStatus defines the observed state of LanguageModel

Appears in: - LanguageModel

Field	Description	Default	Validation
observedGeneration integer	ObservedGeneration reflects the generation of the most recently observed LanguageModel		Optional: {}
phase string	Phase represents the current phase of the model (Pending, Ready, Failed)		Enum: [Pending Ready Failed] Optional: {}
conditions Condition array	Conditions represent the latest available observations of the model's state		Optional: {}
message string	Message provides human-readable details about the current state		Optional: {}

LanguagePersona

LanguagePersona is the Schema for the languagepersonas API

Field	Description	Default	Validation
apiVersion string	langop.io/v1alpha1
kind string	LanguagePersona
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec LanguagePersonaSpec
status LanguagePersonaStatus

LanguagePersonaSpec

LanguagePersonaSpec defines the desired state of LanguagePersona

Appears in: - LanguagePersona

Field	Description	Default	Validation
tone string	Tone describes the agent's communication style e.g. "professional", "concise and direct", "warm and encouraging"		Optional: {}
personality string	Personality describes the agent's character and behavioural traits e.g. "curious and methodical, always explains reasoning step by step"		Optional: {}
expertise string	Expertise describes the agent's domain knowledge and skills e.g. "senior software engineer specialising in distributed systems and Go"		Optional: {}

LanguagePersonaStatus

LanguagePersonaStatus defines the observed state of LanguagePersona

Appears in: - LanguagePersona

Field	Description	Default	Validation
observedGeneration integer	ObservedGeneration reflects the generation of the most recently observed LanguagePersona		Optional: {}
phase string	Phase represents the current phase (Pending, Ready, Failed)		Enum: [Pending Ready Failed] Optional: {}
conditions Condition array	Conditions represent the latest available observations of the persona's state		Optional: {}

LanguageTool

LanguageTool is the Schema for the languagetools API

Field	Description	Default	Validation
apiVersion string	langop.io/v1alpha1
kind string	LanguageTool
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec LanguageToolSpec
status LanguageToolStatus

LanguageToolSpec

LanguageToolSpec defines the desired state of LanguageTool

Appears in: - LanguageTool

Field	Description	Default	Validation
image string	Image is the container image to run for this tool. For transport=stdio it is ignored — the operator injects the MCP bridge image instead — and may be omitted (the defaulting webhook fills it).		MinLength: 1 Required: {}
type string	Type specifies the tool protocol type. Only "mcp" is currently implemented.	mcp	Enum: [mcp]
transport string	Transport selects how the operator exposes this tool's MCP endpoint. - "streamable-http" (default): spec.image already serves Streamable HTTP at /mcp. - "sse": spec.image already serves the (legacy) MCP HTTP+SSE transport. - "stdio": the user supplies a stdio MCP command in spec.stdio; the operator injects a pinned, persistent stdio→Streamable-HTTP bridge that serves /mcp and /health on spec.port.	streamable-http	Enum: [streamable-http sse stdio] Optional: {}
stdio StdioServerSpec	Stdio configures the stdio MCP server when transport=stdio. Required for that transport, ignored otherwise.		Optional: {}
deploymentMode string	DeploymentMode specifies how this tool should be deployed - "service": Deployed as a standalone Deployment+Service (default, shared across agents) - "sidecar": Deployed as a sidecar container in each agent pod (dedicated, with workspace access)	service	Enum: [service sidecar] Optional: {}
port integer	Port is the port the tool listens on	8080	Maximum: 65535 Minimum: 1
deployment DeploymentSpec	Deployment groups Kubernetes-specific pod and container configuration.		Optional: {}
networkPolicies AgentNetworkPolicies	NetworkPolicies defines ingress and egress rules for this tool. Rules mirror the native Kubernetes NetworkPolicy shape.		Optional: {}

LanguageToolStatus

LanguageToolStatus defines the observed state of LanguageTool

Appears in: - LanguageTool

Field	Description	Default	Validation
observedGeneration integer	ObservedGeneration reflects the generation of the most recently observed LanguageTool		Optional: {}
phase string	Phase represents the current phase of the tool (Pending, Running, Failed, Updating, Degraded)		Enum: [Pending Running Failed Updating Degraded] Optional: {}
conditions Condition array	Conditions represent the latest available observations of the tool's state		Optional: {}
endpoint string	Endpoint is the service endpoint where the tool is accessible		Optional: {}
toolSchemas ToolSchema array	ToolSchemas contains the complete MCP tool schemas discovered from this service		Optional: {}
readyReplicas integer	ReadyReplicas is the number of pods ready and passing health checks		Optional: {}
availableReplicas integer	AvailableReplicas is the number of pods targeted by this LanguageTool with at least one available condition		Optional: {}
updatedReplicas integer	UpdatedReplicas is the number of pods targeted by this LanguageTool that have the desired spec		Optional: {}
unavailableReplicas integer	UnavailableReplicas is the number of pods targeted by this LanguageTool that are unavailable		Optional: {}

ManagedResource

ManagedResource describes a single Kubernetes resource created and owned by this operator on behalf of a LanguageAgent or LanguageCluster. The combination of Group+Kind+Namespace+Name uniquely identifies the resource.

Appears in: - LanguageAgentStatus - LanguageClusterStatus

Field	Description	Default	Validation
group string	Group is the API group of the resource. Empty string means the core API group (e.g. ConfigMap, Service, PersistentVolumeClaim).		Optional: {}
kind string	Kind is the Kubernetes resource kind (e.g. "Deployment", "ConfigMap").
name string	Name is the name of the resource.
namespace string	Namespace is the namespace of the resource. Empty for cluster-scoped resources (e.g. Namespace).		Optional: {}

ModelReference

ModelReference references a LanguageModel

Appears in: - LanguageAgentSpec

Field	Description	Default	Validation
name string	Name is the name of the LanguageModel		MaxLength: 63 Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$ Required: {}
role string	Role defines the purpose of this model — a hint for the agent runtime for model selection (e.g. prefer role=primary for general calls, role=reasoning for chain-of-thought). The operator does not enforce routing by role; it is surfaced in the agent config (agent.json).	primary	Enum: [primary fallback reasoning tool-calling summarization] Optional: {}
priority integer	Priority for model selection — a hint for the agent runtime (lower value = higher priority). The operator does not enforce priority; it is surfaced in the agent config (agent.json).		Optional: {}

NetworkEgressRule

NetworkEgressRule is one egress rule: zero or more destination peers, zero or more ports. Mirrors networkingv1.NetworkPolicyEgressRule.

Appears in: - AgentNetworkPolicies

Field	Description	Default	Validation
to NetworkPeer array	To lists the destinations this workload is allowed to reach.		Optional: {}
ports NetworkPort array	Ports lists the destination ports to allow.		Optional: {}

NetworkIngressRule

NetworkIngressRule is one ingress rule: zero or more source peers, zero or more ports. Mirrors networkingv1.NetworkPolicyIngressRule.

Appears in: - AgentNetworkPolicies

Field	Description	Default	Validation
from NetworkPeer array	From lists the sources allowed to send traffic to this workload.		Optional: {}
ports NetworkPort array	Ports lists the ports on which to allow incoming traffic.		Optional: {}

NetworkPeer

NetworkPeer defines the source/destination of network traffic

Appears in: - NetworkEgressRule - NetworkIngressRule

Field	Description	Default	Validation
group string	Group selects pods with matching langop.io/group label Used to allow communication with specific labeled resources		Optional: {}
cidr string	CIDR block		Optional: {}
dns string array	DNS names (supports wildcards with ) Examples: "api.openai.com", ".googleapis.com"		Optional: {}
service ServiceReference	Kubernetes service reference		Optional: {}
namespaceSelector LabelSelector	Namespace selector (for cross-namespace rules)		Optional: {}
podSelector LabelSelector	Pod selector (within namespace)		Optional: {}

NetworkPort

NetworkPort defines a port and protocol

Appears in: - NetworkEgressRule - NetworkIngressRule

Field	Description	Default	Validation
protocol string	Protocol (TCP, UDP, SCTP)	TCP	Enum: [TCP UDP SCTP] Optional: {}
port integer	Port number		Maximum: 65535 Minimum: 1

PrometheusAlertingRule

PrometheusAlertingRule defines a single Prometheus alerting or recording rule.

Appears in: - PrometheusRuleGroup

Field	Description	Default	Validation
alert string	Alert is the alert name. Leave empty for recording rules.		Optional: {}
record string	Record is the output metric name for recording rules. Leave empty for alerting rules.		Optional: {}
expr string	Expr is the PromQL expression evaluated at each evaluation cycle.		Required: {}
for string	For is the duration the condition must be true before the alert fires. Only valid for alerting rules.		Optional: {}
labels object (keys:string, values:string)	Labels are labels attached to the alert or recording rule.		Optional: {}
annotations object (keys:string, values:string)	Annotations are annotations attached to the alert. Only valid for alerting rules.		Optional: {}

PrometheusRuleGroup

PrometheusRuleGroup defines a group of Prometheus alerting or recording rules.

Appears in: - AgentMonitoringSpec

Field	Description	Default	Validation
name string	Name is the name of the rule group.		Required: {}
interval string	Interval is the evaluation interval for this group. Uses the Prometheus default when omitted.		Optional: {}
rules PrometheusAlertingRule array	Rules is the list of alerting or recording rules in this group.		MinItems: 1

RateLimitSpec

RateLimitSpec defines rate limiting configuration

Appears in: - LanguageModelSpec

Field	Description	Default	Validation
requestsPerMinute integer	RequestsPerMinute limits requests per minute		Optional: {}
tokensPerMinute integer	TokensPerMinute limits tokens per minute		Optional: {}

RepositorySpec

RepositorySpec declares a git repository to clone into the agent's workspace. The clone is performed by the operator at pod startup; this type defines only the desired source. Follows the WorkspaceSpec/CredentialSpec conventions.

Appears in: - LanguageAgentSpec

Field	Description	Default	Validation
url string	URL is the git repository to clone (https://... or git@... SSH).		Required: {}
ref string	Ref is the branch, tag, or commit SHA to check out. Defaults to the default branch.		Optional: {}
path string	Path is the subdirectory under the workspace mountPath to clone into. Defaults to the repository name derived from the URL. Must be a relative path (no leading "/", no ".." segments).		Optional: {}
depth integer	Depth, when > 0, performs a shallow clone with this history depth.		Minimum: 0 Optional: {}
secretRef LocalObjectReference	SecretRef references a Secret with git credentials for private repos. Recognized keys: token or username+password (HTTPS), ssh-privatekey (SSH).		Optional: {}

RuntimeAuthSpec

RuntimeAuthSpec gates OIDC authentication for agents using a runtime.

Appears in: - LanguageAgentRuntimeSpec

Field	Description	Default	Validation
enabled boolean	Enabled puts agents using this runtime behind the cluster OIDC proxy. Has no effect unless the cluster has auth enabled.		Optional: {}

RuntimeSecretRef

RuntimeSecretRef references a Secret in the same namespace. All keys in the Secret are injected as env vars via envFrom.

Appears in: - CredentialSpec

Field	Description	Default	Validation
name string	Name is the name of the Secret.		Required: {}

SecretReference

SecretReference references a Kubernetes Secret

Appears in: - ClusterOIDCSpec - LanguageModelSpec

Field	Description	Default	Validation
name string	Name is the name of the secret		Required: {}
key string	Key is the key within the secret containing the value	api-key	Optional: {}

SelfConfigAction

Underlying type: string

SelfConfigAction is a category of self-modification an agent may request.

Validation: - Enum: [tools models envVars instructions roleRules]

Appears in: - SelfConfigureSpec

Field	Description
tools	SelfConfigActionTools allows the agent to add or remove tool references.
models	SelfConfigActionModels allows the agent to add or remove model references.
envVars	SelfConfigActionEnvVars allows the agent to inject plain-value environment variables.
instructions	SelfConfigActionInstructions allows the agent to replace its system instructions.
roleRules	SelfConfigActionRoleRules allows the agent to append RBAC policy rules to its Role.

SelfConfigEnvVar

SelfConfigEnvVar is a plain-value environment variable injected by a self-config request. SecretKeyRef and other value sources are intentionally not supported.

Appears in: - LanguageAgentSelfConfigSpec

Field	Description	Default	Validation
name string	Name of the environment variable.		MinLength: 1 Required: {}
value string	Value is the literal string value of the variable.		Required: {}

SelfConfigPhase

Underlying type: string

SelfConfigPhase reflects the current processing state of a LanguageAgentSelfConfig.

Validation: - Enum: [Pending Applied Failed Denied]

Appears in: - LanguageAgentSelfConfigStatus

Field	Description
Pending	SelfConfigPhasePending means the request has not yet been processed.
Applied	SelfConfigPhaseApplied means the requested changes were patched onto the parent LanguageAgent.
Failed	SelfConfigPhaseFailed means the controller encountered an error while processing the request.
Denied	SelfConfigPhaseDenied means the request was rejected due to policy (not enabled, or action not allowed).

SelfConfigureSpec

SelfConfigureSpec controls whether a LanguageAgent may submit LanguageAgentSelfConfig requests to modify its own spec at runtime.

Appears in: - LanguageAgentSpec

Field	Description	Default	Validation
enabled boolean	Enabled gates all self-configuration. When false, any LanguageAgentSelfConfig targeting this agent is immediately Denied.	false	Optional: {}
allowedActions SelfConfigAction array	AllowedActions is the allowlist of self-config categories the agent may request. If empty while Enabled=true, all actions are denied.		Enum: [tools models envVars instructions roleRules] Optional: {}

ServiceReference

ServiceReference identifies a Kubernetes Service

Appears in: - NetworkPeer

Field	Description	Default	Validation
name string	Service name		Required: {}
namespace string	Service namespace (defaults to same namespace if omitted)		Optional: {}

StdioServerSpec

StdioServerSpec describes a stdio-based MCP server the operator wraps with a persistent stdio→Streamable-HTTP bridge.

Appears in: - LanguageToolSpec

Field	Description	Default	Validation
command string array	Command is the full argv of the stdio MCP server, e.g. ["npx","-y","@upstash/context7-mcp"] or ["uvx","mcp-server-git","--repository","/workspace"]. The operator passes it to the bridge as a single stdio command. Environment for the child comes from spec.deployment.env / spec.deployment.envFrom.		MinItems: 1 Required: {}

ToolProperty

ToolProperty defines an individual parameter or return field

Appears in: - ToolSchemaDefinition

Field	Description	Default	Validation
type string	Type is the JSON schema type (string, integer, boolean, etc.)
description string	Description explains what this property represents		Optional: {}
example string	Example provides an example value as a JSON string		Optional: {}

ToolReference

ToolReference references a LanguageTool

Appears in: - LanguageAgentSpec

Field	Description	Default	Validation
name string	Name is the name of the LanguageTool		MaxLength: 63 Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$ Required: {}
enabled boolean	Enabled indicates if this tool is available to the agent. Defaults to true. Set to false to explicitly disable the tool without removing it.	true	Optional: {}

ToolSchema

ToolSchema represents the complete schema of an MCP tool

Appears in: - LanguageToolStatus

Field	Description	Default	Validation
name string	Name is the tool identifier
description string	Description is a human-readable description of the tool		Optional: {}
inputSchema ToolSchemaDefinition	InputSchema defines the parameters this tool accepts		Optional: {}

ToolSchemaDefinition

ToolSchemaDefinition defines parameter or return value structure

Appears in: - ToolSchema

Field	Description	Default	Validation
type string	Type is the JSON schema type (object, array, string, etc.)		Optional: {}
properties object (keys:string, values:ToolProperty)	Properties defines object properties (for type: object)		Optional: {}
required string array	Required lists required property names (for type: object)		Optional: {}

WorkspaceSpec

WorkspaceSpec defines persistent workspace storage for an agent

Appears in: - LanguageAgentSpec

Field	Description	Default	Validation
enabled boolean	Enabled controls whether to create a workspace volume. Defaults to true. Set to false to explicitly disable without removing the workspace config.	true	Optional: {}
size string	Size is the requested storage size (e.g., "10Gi", "1.5Ti", "500Mi") Supports integer and decimal quantities with standard Kubernetes suffixes	10Gi	MinLength: 1 Pattern: ^([0-9]*\.?[0-9]+)(Ei\|Pi\|Ti\|Gi\|Mi\|Ki\|E\|P\|T\|G\|M\|K\|m)?$ Optional: {}
storageClassName string	StorageClassName specifies the StorageClass for the PVC If not specified, uses the cluster default		Optional: {}
accessMode string	AccessMode defines the volume access mode	ReadWriteOnce	Enum: [ReadWriteOnce ReadWriteMany] Optional: {}
mountPath string	MountPath is where the workspace is mounted in containers	/workspace	Optional: {}
retain boolean	Retain prevents the workspace PVC from being deleted when the agent is deleted. When true, the PVC's ownerReference is removed during cleanup so Kubernetes GC does not collect it. The orphaned PVC name is surfaced in status.workspacePVCName. Defaults to false.	false	Optional: {}
initialFiles object (keys:string, values:string)	InitialFiles are seeded into the workspace PVC on first boot only. Keys are filenames (must be valid ConfigMap keys: alphanumeric, '.', '-', '_'). Files are not overwritten if they already exist on the PVC.		Optional: {}
seedConfigMapRef LocalObjectReference	SeedConfigMapRef references an external ConfigMap whose keys are filenames and values are file contents. Merged with InitialFiles; InitialFiles wins on collision.		Optional: {}