Reference on Kubemoot

Agent CRD

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The Agent CRD declares an LLM-powered agent as a thin, capability-only resource and deploys it as a Kubernetes-native service. The Agent spec carries no model name, no provider, and no GPU hint. Agents declare what they can do; the scheduler matches them to a (model, provider, endpoint) via CrewSchedulingPolicy rules over labeled Model CRs.

Agents orchestrate:

Models: LLM inference resolved by the scheduler from spec.capabilities + CrewSchedulingPolicy (see scheduler.md)
Knowledge: RAG retrieval via spec.ragSources
Tools: MCP tool execution via the MCPGateway, filtered by spec.enabledTools / spec.disabledTools
Collaboration: Multi-agent discussions via NATS JetStream, configured by spec.discussRole / spec.discussChannels / spec.discussKeywords
Prompts: System prompts composed from PromptModule CRs referenced by spec.promptRefs

Supported Types

Type	Description
`chat`	Conversational agent with HTTP API
`task`	Task-oriented agent (planned)
`workflow`	Multi-step workflow orchestration (planned)

Spec Fields

`spec.type`

Agent type. Default: chat. Only chat is implemented today.

Crew CRD

Mon, 01 Jan 0001 00:00:00 +0000

Overview

A Crew groups a set of Agents (joined by the kubemoot.ai/crew label) into one collaborating team, and configures crew-wide concerns: the discussion gateway and the crew’s working memory. Agents are the workers; the Crew is the team-level context they share.

apiVersion: kubemoot.ai/v1alpha1
kind: Crew
metadata:
 name: homelab-pilot
 namespace: crew-homelab-pilot
spec:
 description: "Homelab infrastructure crew"
 discussion:
 enabled: true
 memory:
 enabled: true
 maxFacts: 5000
 ttlDays: 365
 injectLimit: 8
 verifyOnAdd: true

The namespace separates names. The same crew name can run in many namespaces side by side: the discussion, request, artifact, and memory subjects and keys a crew uses carry its namespace and crew name after a fixed prefix (some operator subjects carry no namespace), so two crews named homelab-pilot in two different namespaces do not collide. This is naming separation, not a security boundary: NATS has no authentication in this release, and a client that can reach it can read any subject. See Security model and known limitations.

Models in Kubemoot

Mon, 01 Jan 0001 00:00:00 +0000

This document covers the model layer end to end: the CRDs (ModelProvider, Model, EmbeddingModel), how Agents reach a (model, provider) binding via the scheduler, the load-on-demand principle, the model catalog, and GPU compatibility for a reference deployment.

For the framework behind these choices - why tool-calling fidelity outranks coding benchmarks, how to budget VRAM, and how to match model size to discussion role - see Choosing a Model.

CRD Hierarchy

ModelProvider (where - a model server endpoint)
 │
 ├── Model (what - labeled inference model on a provider)
 │
 └── EmbeddingModel (what - embedding model for RAGSource indexing)

Agents declare capabilities; the scheduler matches them to a Model whose labels satisfy a CrewSchedulingPolicy’s require / prefer selectors. See Scheduler for the full algorithm.

RAGSource Guide

Mon, 01 Jan 0001 00:00:00 +0000

Overview

RAGSource is a Kubemoot CRD that manages the complete lifecycle of Retrieval-Augmented Generation knowledge sources. It automates: cloning source documents, chunking, embedding via Ollama, storing vectors in pgvector, deploying a query service, and continuously verifying data integrity.

The operator follows the Kubernetes reconciler contract: compare desired state (the RAGSource spec) against observed state (what’s actually in the vector store), and reconcile the difference.

Architecture

RAGSource CR
 │
 ├─── Indexer Job (Java/Spring Boot)
 │ ├── Clone git repo / fetch documents
 │ ├── Chunk documents (TokenTextSplitter)
 │ ├── Generate embeddings (Ollama nomic-embed)
 │ └── Store vectors in pgvector (Spring AI schema: data_{collection})
 │
 ├─── Query Service (Python/FastAPI)
 │ ├── Deployment + Service (auto-deployed)
 │ ├── POST /query - semantic search
 │ └── GET /info - collection stats (used by verification)
 │
 └─── Docling Serve Sidecar (for document source type)
 └── Converts PDF/DOCX/PPTX/HTML/images → markdown

Component Images

Component	Image	Language
Indexer	`registry.example.com/kubemoot/indexer`	Java (Spring Boot)
Query Service	`registry.example.com/kubemoot/query-service`	Python (FastAPI)
Docling Serve	`quay.io/docling-project/docling-serve-cpu`	Python

All image versions are managed centrally via the KubemootConfig singleton - never hardcode image tags.

KubemootConfig Guide

Mon, 01 Jan 0001 00:00:00 +0000

Overview

KubemootConfig is a cluster-scoped singleton CRD that centralizes default images and configuration for all Kubemoot components. It eliminates hardcoded image versions in the operator source code and enables GitOps-friendly version management.

Every Kubemoot controller reads from KubemootConfig via the ConfigCache - a thread-safe in-memory cache that the KubemootConfigReconciler populates on startup and updates on every change.

Why a singleton

Image references and operator defaults live in one cluster-scoped resource instead of the operator source, operator environment variables, or every custom resource. An image bump is a patch to one resource: no recompile, no operator restart, no Helm upgrade, and no chance of two namespaces running different runtime images. The scope is cluster-wide on purpose; a per-namespace config would bring the drift back. New cluster-wide defaults (scheduler strategy, retention windows) become new fields on the same resource rather than new CRDs. If default is missing, controllers fail their first reconcile until it exists, which is why the operator chart installs it.

MCPServer Guide

Mon, 01 Jan 0001 00:00:00 +0000

Overview

MCPServer is a Kubemoot CRD that deploys and manages Model Context Protocol servers in Kubernetes. Each MCPServer provides tools that agents can invoke through an MCPGateway.

The operator handles the complete lifecycle: deploying the container, injecting the mcp-bridge sidecar for stdio transport, configuring health probes, and registering with gateways.

Architecture

MCPServer CR
 │
 ├─── Deployment (operator-managed)
 │ ├── MCP Server Container (your image)
 │ └── MCP Bridge Sidecar (auto-injected for stdio)
 │
 ├─── Service (ClusterIP)
 │ └── Exposes the bridge HTTP/SSE endpoint
 │
 └─── Gateway Registration
 └── Registers tools with matching MCPGateways

Tool Chain

Agents never connect to MCPServers directly. The full chain is:

MCPGateway Guide

Mon, 01 Jan 0001 00:00:00 +0000

Overview

MCPGateway is a Kubemoot CRD that deploys an MCP gateway - the central hub that routes agent tool calls to MCPServers. Agents connect to the gateway (not individual MCPServers), and the gateway discovers and manages connections to all matching MCPServers.

Architecture

Agent Runtime
 │
 │ KUBEMOOT_GATEWAY_ENDPOINT
 ▼
MCPGateway (Deployment + Service)
 │
 ├── MCPServer: kubernetes-mcp (via label selector)
 ├── MCPServer: nats-mcp (via label selector)
 ├── MCPServer: github-mcp (via label selector)
 └── MCPServer: fetch-mcp (via label selector)

The gateway:

CrewFitnessSuite CRD

Mon, 01 Jan 0001 00:00:00 +0000

Overview

A CrewFitnessSuite runs a set of fitness scripts against a crew many times, collects the result of every iteration, and writes an XLSX report to the NATS Object Store bucket kubemoot_fitness_artifacts. The operator creates one CrewFitness per script and iteration, serially by default, and owns each one through an owner reference.

apiVersion: kubemoot.ai/v1alpha1
kind: CrewFitnessSuite
metadata:
 name: homelab-baseline
 namespace: crew-homelab-pilot
spec:
 crewRef: homelab-pilot
 description: "READ-query baseline across the homelab layers"
 iterations: 15
 concurrency: 1
 scripts:
 - testRef: gpu-utilization-live
 configMapRef: homelab-pilot-fitness-tests
 - testRef: node-count
 configMapRef: homelab-pilot-fitness-tests

Spec

Field	Type	Default	Description
`crewRef`	string	required	Crew in the same namespace that the suite runs against.
`description`	string		Purpose of the suite. Shown on the dashboard and in the XLSX Overview tab.
`iterations`	int	required, at least 1	How many times each script runs. The suite creates `len(scripts) x iterations` runs.
`scripts`	list	required, at least 1	The scripts to run, in order. Each entry has a `testRef` and exactly one of `testContent` (inline script) or `configMapRef` (ConfigMap holding `<testRef>.adl`).
`concurrency`	int	`1`	Maximum runs in flight at once. Keep it at 1 for baselines: parallel runs share the crew and its model providers, so they measure contention.
`perIterationTimeout`	duration	`10m`	Wall-clock cap for one iteration.
`artifactRetention`	duration	`168h`	Object Store TTL for the XLSX.
`purgeMemory`	bool	`true`	Clear the crew’s working memory once before the first iteration.
`suspend`	bool	`false`	Pause between iterations. See Pause, resume and stop.
`cancel`	bool	`false`	Stop the suite. See Pause, resume and stop.
`rejudge`	object		Set at creation, immutable. Judge an earlier run’s saved answers against this suite’s scripts instead of running iterations. `suite` names the source `CrewFitnessSuite` in the same namespace and `runId` its run. See Re-judge an earlier run.

Status

Field	Description
`phase`	`Pending`, `Running`, `Paused`, `Completed`, `Cancelled`, `Failed`, or `Error`.
`runId`	Identifies this execution. Used in iteration names and in the artifact key.
`startedAt`	When scheduling began.
`completedAt`	When the last iteration finished, or when the suite was cancelled.
`iterationsTotal`	`len(scripts) x iterations`. It keeps the planned total after a cancel, so `iterationsCompleted < iterationsTotal` marks a partial run.
`iterationsCompleted`	Iterations that reached a terminal phase, whatever the outcome.
`passed`, `failed`, `errored`	`iterationsCompleted` broken down by outcome.
`artifactRef`	Bucket, object key (`<namespace>/<suite>/<runId>.xlsx`), and size of the XLSX, set once it is written.
`error`	Why the suite itself failed to execute (phase `Error`).
`rejudge`	On a re-judge suite: the `source` run, how many `transcripts` were copied, and `notInSource`, the scenarios of this suite the source run has no answer for.
`scenarios`	Per-scenario rollup of the finished iterations, in spec order. See Results in status.
`judge`	Progress and scores of the deferred judge pass. See Results in status.
`conditions`	On a re-judge suite, `RejudgeSourceReady` reports whether the source could be used. See Re-judge an earlier run.

Phases

Phase	Terminal	Meaning
`Pending`	no	Created, not yet started.
`Running`	no	Iterations are being scheduled or are in flight.
`Paused`	no	`spec.suspend` is true and no iteration is in flight. Nothing runs against the crew.
`Completed`	yes	Every iteration reached a terminal phase. Failed or errored iterations are outcomes in the counts, not a suite failure.
`Cancelled`	yes	`spec.cancel` stopped the suite. Completed iterations are kept and the XLSX is marked partial.
`Failed`, `Error`	yes	The suite itself could not execute, such as an invalid spec.

Results in status

The operator writes a run’s results to the suite’s status, so any client with read access to crewfitnesssuites gets them through the Kubernetes API: kubectl, kmctl, CrewForge, or a script. The status outlives the per-iteration CrewFitness objects, which the operator removes after the run, and the object store retention of the transcripts and judge checkpoint.

MootArchetype CRD

Mon, 01 Jan 0001 00:00:00 +0000

Overview

A MootArchetype declares the shape of a consensus archetype: the phases it passes through, the signals agents may emit, and the legal transitions between phases. The operator installs one, consent-3, and validates the resource and the scheduling policies that reference it.

Maturity. MootArchetype is a newer feature and is not fully vetted. The API is kubemoot.ai/v1alpha1: expect the fields to change. Read What it does today and What it does not do yet before building on it.

ADL Reference

Mon, 01 Jan 0001 00:00:00 +0000

ADL has two dialects that share a style. The prompt dialect composes an agent’s behavior; the fitness dialect specifies executable checks against a live crew. This page is the complete vocabulary for both; see ADL, the Architecture Definition Language, for agents for where the notation comes from and how Kubemoot applies it. For how to write and run it, see Write Agents & ADL and Kubemoot Crew Fitness Functions.

Prompt ADL

Prompt ADL is stored in the content of a PromptModule CR. Modules are concatenated by order to form an agent’s system prompt.

kmctl Reference

Mon, 01 Jan 0001 00:00:00 +0000

kmctl is the command-line tool for Kubemoot. It is a convenience layer over Kubemoot’s Kubernetes resources, consistent in flag and output style with kubectl, istioctl, and helm. The command layout (noun-first resource commands + global manifest verbs) is a deliberate design choice; see Command structure in the user guide.

This reference covers the shipped command surface. Commands marked planned are designed but not yet implemented; all others work today. Check your installed version with kmctl version. Every command has runnable --help examples, and get commands offer shell completion of resource names. Run kmctl <command> --help for the same information inline.