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 server, and no GPU hint. Agents declare what they can do; the scheduler matches them to a (model, server, 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.

Kubemoot Architecture - Distributed Consensus vs Single-Model Orchestration

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

“Kubemoot composes capability horizontally - many small specialists, because no single model is big enough to do it all; intelligence is emergent from a committee. A single-model agent is the opposite: capability concentrated in one large reasoner that drives tools and, when needed, spawns copies of itself.”

a single-model coding agent, contrasting itself with Kubemoot

Purpose

There are two broad shapes an agentic system can take. Kubemoot is one of them; most well-known agent systems are the other. The fastest way to understand why Kubemoot is built the way it is - many small models, a coordinator, consensus signals over a message bus - is to hold it next to its opposite and see what each shape buys and costs.

Kubemoot Crew Fitness Functions

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

Kubemoot implements architectural fitness functions as first-class Kubernetes resources. The CrewFitness CRD allows operators and crew designers to define, execute, and observe fitness tests against deployed agent crews - declaratively, headlessly, and with automatic cleanup.

This document describes how Kubemoot adapts the fitness function concept from Architecture as Code (Richards, Ford, and Johnson) to the domain of AI agent crew orchestration.

From ADL to Kubernetes

An architectural fitness function is “any mechanism that provides an objective integrity check on some architectural characteristic,” as defined in Building Evolutionary Architectures (Ford, Parsons, and Kua); Architecture as Code (Richards, Ford, and Johnson) builds on the idea. In Kubemoot, the architectural characteristic under test is the crew’s discussion behavior - does the crew answer questions correctly, does it stand aside on irrelevant input, does the coordinator synthesize Tooler and Analyst contributions?

Onboarding Guide

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

Overview

When no agent in a crew can answer a question, the coordinator signals a capability gap. An agent running in onboarding mode reacts to that signal: it proposes an MCP server that could fill the gap. On the user’s consent it replies with a proposed MCPServer manifest in the discussion thread. Applying that manifest, and creating the Tooler Agent that uses it, are manual steps today.

This page describes what ships today, how to enable it, and what is not automated yet. For the consensus signals that produce a gap, see Agentic Consensus.

Agentic Consensus

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

Kubemoot answers a question by convening the agents whose expertise fits it, letting them investigate and deliberate, and settling on a synthesis once the crew has spoken. This page is the architecture behind that: how the coordinator selects who takes part, what a consensus signal means to the protocol, and why a discussion settles by state rather than by a clock. For the concept-level model (roles, phases, signal vocabulary) see Crews & Agents, The Moot, and Signals & Protocol - this page assumes them and goes one level deeper into the coordinator’s mechanics.

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.

Gherkin, ADL, and Fitness Functions

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

Purpose

Kubemoot uses two structured languages: ADL (the Architecture Definition Language, applied to agents) to compose agent prompts, and a fitness-function format to specify executable acceptance checks for a crew. A natural question - especially for anyone arriving from a Behavior-Driven Development (BDD) background - is: why not use Gherkin (Cucumber’s Given/When/Then) for either of these?

This document answers that. It is a general compare-and-contrast, not a proposal. It explains where Gherkin overlaps with what Kubemoot already does, where it diverges, and why Kubemoot settled on ADL plus a purpose-built fitness format. Gherkin remains a credible alternative substrate for one of the two surfaces; the reasoning below makes clear which, and why.

Kubemoot Dashboard

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

Overview

The Kubemoot Dashboard is a web UI for looking at a running Kubemoot installation. It lists Kubemoot resources across namespaces, shows GPU node and model state, and streams agent discussions and NATS messages as they happen. It is a SvelteKit application that reads the Kubernetes API and the NATS bus from the server side; the browser never connects to either directly.

Metrics, logs, and traces are not part of the dashboard. For those, see Observability.

Kubemoot Observability

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

How to observe what a Kubemoot crew is doing: the data it exposes, the surfaces that render it, and the external observability stack it depends on. For the dashboard UI itself see dashboard.md; for the consensus protocol that produces most of this data see agentic-consensus.md.

What you can observe

Domain	Signals	Where it comes from
Discussions / consensus	Thread lifecycle, per-agent signals (`triaging`, `evaluating`, `waiting`, `agree`, `concern`, `stand_aside`, `failure`, `block`, `advisory`, `synthesis`), settle decisions, synthesis text	Coordinator + agents publish to NATS `kubemoot.discuss.<namespace>.<crew>.*`
Agent activity	Heartbeats while GPU-queued, triage vs evaluation phases, per-call server attribution (which model/server/GPU served each call)	Agent runtime signals + metadata
GPU & scheduling	Loaded-model footprints, in-flight tickets, server readiness, total/used VRAM, scheduling decisions	Operator-published server state (NATS KV) + DCGM
Quality	MCP tool quality verdicts (hot/failing/out-of-norm)	MCP quality pipeline → `kubemoot.quality.*`
RAG indexing	Source indexing progress, chunk/embed status	RAGSource controller
Fitness	Per-scenario/iteration pass-rates, assertion results, durations, full conversation transcripts	`CrewFitness` / `CrewFitnessSuite` → XLSX in NATS Object Store

Surfaces

Kubemoot Dashboard: the primary real-time view (discussion threads & timeline, agent topology, NATS messages, fitness suites, accelerator and model activity). Updates push-style via NATS JetStream SSE and k8s watch→SSE. See dashboard.md.
NATS JetStream: the event substrate. Streams: KUBEMOOT_CHRONICLE, KUBEMOOT_QUALITY, KUBEMOOT_CHAT, KUBEMOOT_OPERATOR, KUBEMOOT_DISCUSS. Anything the dashboard shows is reconstructable from these.
Prometheus metrics and Grafana dashboards (optional): every Kubemoot component serves Prometheus metrics, and Kubemoot ships Grafana dashboards for them. See Metrics: Prometheus and Grafana.

The three pillars of observability

Kubemoot leans on the cluster’s existing observability stack rather than shipping its own. The three pillars (metrics, logs, spans) are at different stages.

Models in Kubemoot

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

This document covers the model layer end to end: the CRDs (ModelServer, Model, EmbeddingModel), how Agents reach a (model, server) 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

ModelServer (where - a model server endpoint)
 │
 ├── Model (what - labeled inference model on a server)
 │
 └── 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.

Tooler-Analyst Architecture

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

Two Roles That Serve Different Phases

Kubemoot organizes the data-gathering and reasoning work of a discussion into two complementary roles that mirror how real teams operate: Toolers who interact with live systems, and Analysts who reason over what the Toolers found.

	Toolers (MCP)	Analysts (RAG)
Phase	EVALUATING	REVIEW
Declared	Agents with MCP tools	Agents with embedded domain docs
Self-discovered	Onboarding agent deploys new MCP servers	RTFM agent indexes new documentation
Carries	MCP tools, no live tools in reasoning	RAG sources, no MCP tools
Thinking	OFF (deterministic tool selection)	ON (reasoning over gathered data)
Analogy	The person with their hands on the keyboard	The person with the manual open, weighing the evidence
GPU profile	Heavier (tool-calling inference)	Lighter (reasoning-focused, no tool overhead)

Why Separate Them

LLMs have a practical limit on how much context they can process while still reliably selecting tools and interpreting results. When a single agent carries both MCP tool schemas and RAG documentation in its system prompt, the prompt bloats and tool selection degrades. Separating concerns gives each agent a smaller, focused prompt: Toolers are better at picking the right tool, Analysts are better at weighing the evidence from those tools.

GPU Worker Nodes

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

Kubemoot schedules models onto GPUs, but it does not create GPU nodes. This page covers the general path for making an NVIDIA GPU usable by Kubernetes workloads, whether the worker node is a bare-metal machine or a virtual machine, and ends with how a Kubemoot ModelServer then uses the node. A short worked example closes the page.

The end state is one check: the node reports nvidia.com/gpu capacity.

Choose a path

Your worker node is	GPU access	Start at
A bare-metal machine with the GPU installed	Direct	Install the driver and container toolkit
A VM on a hypervisor (Proxmox, KVM, ESXi, and similar)	PCI passthrough of the whole card	Pass the GPU through to the VM
A VM on a cloud provider	The provider’s GPU instance types	The provider’s documentation, then Install the driver and container toolkit

Passthrough hands the entire physical GPU to one VM. The host loses access to it while the VM runs, and no second VM can share it. Plan one GPU per GPU worker VM. A cluster scales by adding such nodes.

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 through a model server, 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 (model server, /v1/embeddings)
 │ └── 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.

Scheduling - reminders, follow-ups, recurring

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

One sentence: a crew’s scheduler-advisor Tooler agent calls the scheduling-mcp server’s tools to write ScheduleRecords into the NATS KV bucket kubemoot_scheduled; the operator’s scheduler poller fires due records - either inline in the originating thread or as a new thread, depending on kind x whether a sourceThreadId was attached.

Why this exists

Some discussions are inherently temporally driven:

Reminder - “Remind me in 30 minutes to check the backup job status.”
Follow-up - “Re-check disk usage in an hour” / “Run the weekly health summary every Monday.”
Recurring - daily/weekly admin checks, configured by a cluster admin rather than via chat.

All three reduce to: publish a discussion message at a future time, in the right place. This module provides the primitive.

Kubemoot Scheduler

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

Audience: operator and agent-runtime developers; developers of the ecosystem tools (CrewForge, kmctl); open-source consumers.

One-Paragraph Summary

Kubemoot is an LLM orchestrator. Like kube-scheduler matches Pods to Nodes based on resource requests, the Kubemoot scheduler matches agents to (Model, ModelServer) bindings based on capability requirements. Agents declare what they can do (capabilities), Models declare what they are (family, params, capabilities) as labels, ModelServers declare what they have (VRAM, parallelism), and a CrewSchedulingPolicy CRD expresses require/prefer rules using Kubernetes-style label selectors. The match is computed in the agent reconciler via filter → score → bind; the resolved (model, server, endpoint) is applied to the agent’s Deployment.

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.

The Starter Crew

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

kmctl create scaffolds a small, complete crew you can install on a fresh Kubemoot cluster and talk to within minutes. It is the Kubemoot equivalent of the nginx chart helm create produces: a working example you change into your own crew.

The starter crew is a read-only guide to the Kubernetes namespace it is installed into. Ask it what is running, what is wrong, and why. It reads the namespace with real tools and answers from what it found. It never changes anything.

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:

The Moot Mesh

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

Audience: crew authors who bring their own harness; operator and sidecar developers; anyone deciding how much to trust a harness at the table.

The Moot Mesh is the layer that lets any agent harness sit at the table without knowing how the table works. It follows the shape of a service mesh:

Service mesh	Moot Mesh
Control plane	The Kubemoot operator. It writes each agent’s contract, binds its models, creates its bus consumer, and builds its pod.
Data plane proxy (Envoy)	The Moot Mesh sidecar, one per agent pod.
The application	The harness: the program that does the agent’s reasoning.
The mesh’s shared services	The bus (NATS JetStream), observability, and identity.

A harness does not connect to NATS, does not choose a model server, and does not reach the tool gateway. It talks to three loopback addresses and its sidecar does the rest. That is what makes a harness replaceable: the agent-runtime that ships with Kubemoot, a command-line agent behind a thin shim, and a framework you wrote yourself all join the table the same way.

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:

The Harness Seam and the Shim

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

Audience: crew authors who choose a harness; developers who add one; anyone comparing harnesses on the same crew.

The seam

Every agent at the table is a harness behind the same seam. The harness does the reasoning: it builds the prompt, runs the tool loop, and decides what to say. The Moot Mesh sidecar does everything else: the bus, the signals, the placement of each model call on an accelerator, and the tool allow-list.

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 servers, 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.

Build a Crew

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

This guide builds a crew from its parts. A crew is a set of Kubernetes resources, so “building” one means declaring those resources - usually packaged together as a Helm chart so they version and deploy as a unit.

To see a complete small crew before writing your own, scaffold the starter crew with kmctl create.

What a crew is made of

Resource	Role in the crew
`Crew`	The team - groups agents by the `kubemoot.ai/crew` label, enables the discussion gateway, configures working memory.
`Agent`	Each participant: one coordinator, plus Toolers (and optionally Analysts). Declares capabilities, tools, RAG, and prompt refs.
`PromptModule`	Each agent’s behavior, written in ADL and composed by reference.
`Model` / `ModelServer`	The models (by capability label) and the GPU-backed endpoints that serve them.
`MCPServer` / `MCPGateway`	The tools Toolers use, reached through the gateway.
`RAGSource`	Knowledge sources, indexed and made queryable.
`EmbeddingModel`	The embedding model a RAGSource indexes with. It names the model and its dimensions, never a server.

Steps

1. Define the crew

Declare a Crew with the discussion gateway enabled, and a label every agent will share. See the Crew CRD reference for the full spec including the working-memory policy.

Contributing

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

Contributions are welcome: bug reports, ideas, documentation fixes, tests, and code. This page is the process. The Development Guide covers the repository layout and how to build and test each component.

Report a bug or request a feature

Not sure it is a bug, or have a question? Open a Discussion.
Found a defect? Open an issue on the repo where you found it, using the bug report template. If the Quickstart itself failed, use the quickstart-failed template; it asks for what is needed to reproduce a fresh-cluster run.
Have an idea for a feature? Start in Discussions, so the shape of the idea can settle before anyone writes code. A maintainer turns it into an issue when the work is clear. The feature request template works too when you already know what you want.
Larger or cross-cutting change? Open an issue titled Proposal: <summary> describing the problem, the approach, the alternatives, and what it touches (CRDs, runtime, dashboard, crews). See Governance.

Open a pull request

Fork the repository you want to change, clone your fork, and branch off main.

Install and connect

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

CrewForge installs from the VS Code Marketplace and connects through the kubeconfig you already use. This page covers the prerequisites, the install, how CrewForge chooses a cluster, and what it tells you when it cannot reach one.

Prerequisites

You need	For
VS Code 1.95 or later	Running the extension.
A kubeconfig with access to a cluster that runs the Kubemoot operator	Everything. CrewForge lists the crews your account can read.
`kubectl` on your PATH	Deploying a bundle of plain manifests (`kubectl apply --server-side`).
`helm` on your PATH	Deploying a crew chart, and Lint. Without it, Lint says where to get it.
`kmctl` on your PATH, a current release (its `kmctl create` takes `--display-name`)	New Kubemoot Crew Here and Create Crew, which run `kmctl create --chart` to scaffold the starter crew. CrewForge checks kmctl before it asks you anything and names the minimum it needs.
`git` on your PATH (optional)	Recording the revision a crew was deployed from, and deploying an earlier commit.

Browsing crews and chatting need only the kubeconfig. Developing a crew needs the rest. Your account’s cluster permissions are listed in Settings and permissions.

Kubemoot - the Controller

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

Kubemoot is the controller - the Kubernetes operator, agent runtime, and MCP components that turn declared crews into running, deliberating systems. It is the project everything else in this ecosystem is built on. A crew, an authoring tool, or a CLI is only useful because the controller reconciles the resources they produce.

What it includes

The operator (Go, controller-runtime) - reconciles the Kubemoot CRDs (Crew, Agent, Model, ModelServer, MCPServer, MCPGateway, RAGSource, PromptModule, and the cluster-scoped KubemootConfig), and owns lifecycle: scheduling, finalizers, namespace and resource cleanup.
The agent runtime (Java/Quarkus + LangChain4j) - the process each agent runs as, which deliberates over the message bus, calls tools through the gateway, retrieves RAG knowledge, and emits consensus signals.
The MCP components - the gateway and the mcp-bridge sidecar that connect agents to tools.

What it does

The controller is the substrate; it carries no domain knowledge of its own. It provides the machinery - reconciliation, GPU-aware scheduling, the tool gateway, consensus orchestration, working memory, and observability - and the domain comes entirely from the crews that run on it. That separation is what lets one controller serve infrastructure ops, Kafka operations, research, or security work without change.

The Crew Liaison

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

A crew is a committee. From inside the cluster you can watch it work: agents convening, findings arriving, signals settling. From outside, a client should not have to. The crew liaison is the operator’s door for other agents: one MCP endpoint that fronts every crew in the cluster, takes a question, and hands back the crew’s synthesized answer.

What the client sees

Three tools, and nothing about the discussion’s substance.

The Moot - Consensus Model

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

Kubemoot’s defining idea is that an answer is reached by deliberation among agents, not asserted by a single model. This page explains the goal, the signal vocabulary, the discussion phases, and, importantly, that how a crew organizes its deliberation is configurable. For the units of interaction the deliberation sits inside - conversations, turns, and the thread each discussion runs on - see Conversations, Turns & Threads.

The goal

Settle a question through structured deliberation rather than by one authority. A crew of agents each contributes what it knows; the result is composed from the crew, so a single model being confidently wrong does not, by itself, become the answer.

Why Kubemoot

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

Kubemoot runs agentic AI as a committee of small, specialized models that deliberate to consensus - on your own Kubernetes cluster, declared as Kubernetes resources, and measured by executable fitness functions. This page is about where that fits, what it solves, and how it differs.

Where it started, and where it can go

Kubemoot began as a small agent system to help with observability, security, and administration on one homelab cluster, and grew into a general way to run crews of agents on Kubernetes. Today it works well on local clusters with a couple of accelerators or more, running open models you serve yourself.

Skill CRD

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

Overview

A Skill is a packaged procedure that belongs to a crew. It has a description that says when it applies and a content body, written in ADL, that says what to do. The body stays out of every agent’s prompt until a discussion needs it. The coordinator reads each skill’s description when it chooses who joins a discussion, and it selects the skills that fit the question. Only the selected bodies reach the agents for that discussion.

Compose a Crew

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

A crew is only as useful as its design. This guide covers the decisions that determine whether a crew’s coordinator routes questions intelligently and whether its Toolers and Analysts can answer them: which agents to include, how to write resumes the coordinator can reason over, how to ground the coordinator with broad knowledge and a well-crafted advisory brief, and how to give each Tooler the narrowly-scoped tools it needs and each Analyst the focused RAG knowledge it reasons over.

Conversations, Turns & Threads

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

When you ask a crew a question, four words describe what happens, and they nest. The docs and the dashboard use them with specific meanings, so this page defines each one and how it relates to the others.

The layers

 Conversation durable session with a crew (conversationId)
 |
 +-- Turn one question and the answer settled on it
 | |
 | +-- Thread where that turn's discussion runs (threadId)
 | |
 | +-- Discussion the deliberation on the thread (phases + signals)
 |
 +-- Turn ... later questions, each on its own thread

A conversation holds many turns; each turn runs on its own thread; the discussion is what happens on that thread. The two innermost words name the same layer from different angles, which is explained below.

Development Guide

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

This guide covers the repository layout and how to build and test each component. The process for issues, ideas, and pull requests is on the Contributing page; the conventions a change is expected to follow are summarized at the end of this one.

Repositories

Repository	What it holds
kubemoot	The operator, agent runtime, dashboard, MCP components, and the component docs
crews	Packaged crews as Helm charts
kmctl	The command-line tool
vscode-crewforge	CrewForge for VS Code
kubemoot-docs	This site: the Hugo and Docsy shell and the cross-cutting chapters

Layout of the kubemoot repository

Component	Path	Language / stack
Operator	`operator/`	Go, controller-runtime, kubebuilder CRDs
Agent runtime	`agent-runtime/`	Java / Quarkus + LangChain4j (GraalVM Community native)
Dashboard	`dashboard/`	SvelteKit
MCP bridge, scheduling and tool servers	`mcp-bridge/`, `scheduling-mcp/`, `accelerator-mcp/`, `artifact-access/`, `code-sandbox/`	Go
MCP gateway	`mcp-gateway/`	Java
Discussion gateway, crew liaison, fitness runner	`discussion-gateway/`, `crew-liaison/`, `fitness-runner/`	Go
Indexer	`indexer/`	Java
Query service	`query-service/`	Python
Quickstart	`quickstart/`	Shell
Integration tests	`k8s/tests/`	Shell

Prerequisites

Go 1.27+ (operator, Go components)
Java 25+ with Gradle (agent runtime, indexer, MCP gateway)
Node.js 26+ (dashboard)
kubectl and helm (v3.8+, for OCI charts)
Access to a Kubernetes cluster; kind works for the quickstart

Build and test

Every change ships with tests. Run the suite for the component you touched.

Claude Code

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

Claude Code speaks MCP over HTTP natively, so connecting it to the crew liaison is one command. See The Crew Liaison for what the tools do and why the answer comes by ticket.

Try it against any cluster you can reach

Port-forward the liaison’s Service and add it as a local server:

kubectl -n kubemoot port-forward svc/kubemoot-operator-liaison 18080:80
claude mcp add --transport http kubemoot http://localhost:18080/mcp

Start a new Claude Code session and ask in plain language:

Crews

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

If the controller is the substrate, crews are what runs on it. The crews repository is a home for many crews - both the ones Kubemoot needs to operate and example crews that show how to build your own.

Internal and example crews

Internal crews are part of how Kubemoot works. The fitness judge crew, for instance, scores other crews’ fitness runs. These ship with the project.
Example crews demonstrate patterns you can copy - the clearest being Homelab Pilot, an infrastructure-operations crew that doubles as the reference implementation.

A growing catalog

The intent is an ecosystem of crews, not a fixed set. A crew is a portable Helm chart - agents, prompts, tools, and knowledge bundled together - so crews are meant to be shared and reused across clusters. As the catalog grows, crews are expected to be published to a registry such as ArtifactHub.io, the same way Helm charts and other cloud-native artifacts are distributed.

Crews & Agents

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

A crew is a team of agents that deliberate together; an agent is one participant in that team. Both are Kubernetes resources you declare and version like any other workload.

Crew

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 (the HTTP entry point external clients talk to) and the crew’s working memory. Agents are the workers; the crew is the team-level context they share.

Develop a crew in VS Code

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

This guide walks the whole loop on one small example: a helpdesk crew scaffolded from the starter crew, a read-only guide to its own Kubernetes namespace. You create it, change it, deploy it to a namespace, ask it something, and redeploy after an edit. Everything happens in the editor, without GitOps: CrewForge deploys with Helm straight to a namespace, and never commits or pushes. Flux rollouts stay the outer loop.

Governance

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

Kubemoot is an independent open-source project. Its governance is small and deliberately simple, and this page states how it works today.

Maintainers

Maintainer	Role
Jonathan Johnson	Maintainer

Write access to the repositories in the kubemoot organization is limited to the maintainers. Everyone else contributes through forks and pull requests.

How decisions are made

The maintainer decides. Day-to-day changes are decided in the pull request or issue where they come up. Changes that affect the API (the CRDs), the consensus protocol, or how components fit together are discussed in the open first, so the reasoning is on record:

Overview

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

Kubemoot is a Kubernetes operator and runtime for multi-agent AI consensus. A question is answered not by one model but by a crew of small, specialized agents that deliberate over a message bus and settle by signal. Everything - the crew, its agents, their prompts, and the models they use - is a Kubernetes resource you declare and version like any other.

The mental model

A moot is an assembly that reaches a decision by deliberation. In Kubemoot:

Write Agents & ADL

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

An agent’s behavior is its prompt, and in Kubemoot every prompt is written in ADL (the Architecture Definition Language) and stored in PromptModule CRs - never as inline prose in an Agent spec. This guide covers how to write ADL and how modules compose.

Why ADL

ADL expresses behavior as structured rules instead of free-flowing prose. The benefits are practical: a rule-based prompt is scannable (you can read what an agent will and won’t do at a glance), versionable (kubectl diff shows exactly what changed), and deployable without recompilation (a kubectl apply changes how an agent reasons). Prose prompts drift and hide their intent; ADL keeps it explicit.

The Table and the Harnesses

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

A harness is everything around a model: the guides that steer an agent before it acts and the sensors that let it correct itself afterwards, in the sense of Martin Fowler’s Harness Engineering.

A crew is a harness made of harnesses. Each agent has its own loop: its prompt, its tools, its retries, its memory. The moot is the harness one level up, and its guides and sensors act between agents:

ADL, the Architecture Definition Language, for agents

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

Kubemoot defines what an agent does in ADL, a small, structured language of behavioral rules. Every agent prompt is ADL stored in a PromptModule resource, never free prose in an Agent spec, and the same language expresses a crew’s executable fitness checks. ADL is the surface where a crew’s behavior is authored, reviewed, and versioned.

What ADL is, and where it comes from

ADL is the Architecture Definition Language, a pseudo-code introduced by Mark Richards for describing and governing the structure of a software system, and paired with the fitness-function idea from Richards and Neal Ford’s evolutionary-architecture work (see Architecture as Code by Mark Richards, Neal Ford, and Jonathan Johnson, and Richards’ ADL reference at developertoarchitect.com). In its original form ADL defines a system’s parts (DEFINE SYSTEM, DEFINE DOMAIN, DEFINE COMPONENT) and asserts the rules between them (ASSERT, FOREACH ... CONTAINED WITHIN), making architecture a machine-readable artifact and enforcing it with executable checks that fail when an implementation drifts from its intended design. Kubemoot applies that same language, unchanged in form, to a different subject: instead of governing how a system’s components may depend on each other, its rules govern how an agent behaves. This is a partnership with ADL’s authors and their notation, not a fork or a renaming.

Claude Desktop

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

Claude Desktop connects to remote MCP servers through its connector settings, with OAuth or no authentication, and cannot add custom headers. The crew liaison is usually behind a bearer token or an access gateway, so Desktop reaches it through mcp-remote, a small bridge that runs locally, speaks stdio to Desktop, and forwards to the liaison with whatever headers it needs.

Configuration

Add the liaison to claude_desktop_config.json (Settings, Developer, Edit Config):

Code of Conduct

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

Kubemoot follows the Contributor Covenant, version 2.1. It applies in every project space: GitHub issues, pull requests, and Discussions, and any other place where someone represents the project in public.

The full text lives in one place, the CODE_OF_CONDUCT.md file in the organization’s .github repository. GitHub shows it on every repository in the organization, so it is not copied into each one.

The short version

Be respectful of differing opinions, viewpoints, and experience.
Give and accept constructive feedback gracefully.
Take responsibility for mistakes and learn from them.
Focus on what is best for the community, not only for you.

Harassment, trolling, insulting comments, and publishing others’ private information are not acceptable.

Define Fitness Functions

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

A crew’s behavior is only as trustworthy as your ability to check it. Kubemoot implements architectural fitness functions as Kubernetes resources: you write a short scenario that asks the crew a real question and states what a good answer must satisfy, apply it, and the operator runs the crew live and scores each assertion pass or fail.

The shape of a scenario

A fitness scenario is ADL pseudo-code - a question plus assertions:

Pilot - a Reference Crew

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

Homelab Pilot is one reference crew - an example of what a Kubemoot crew looks like when it’s fully built out. It is not the product; the product is the controller. Pilot exists to demonstrate the controller with a complete, real crew you can read and learn from.

What it demonstrates

Pilot is an infrastructure-operations crew: its Toolers carry MCP tools for Kubernetes, Helm, Proxmox, and Prometheus, and its Analysts carry domain knowledge from Kubernetes, Proxmox, and Talos documentation. Ask it an operational question and the coordinator convenes the relevant Toolers, they investigate with their tools, Analysts reason over the findings in the REVIEW phase, and the crew settles on an answer.

Signals & Protocol

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

Agents in a crew never call each other directly. They publish to a message bus (NATS JetStream), and every contribution carries a signal that says how it relates to the emerging answer. The signals plus a phase model are the whole protocol - there is no central controller issuing commands.

Consensus signals

Signal	Meaning
`agree`	This contribution supports the emerging answer.
`concern`	A reservation that should be weighed before the crew settles.
`stand_aside`	No relevant contribution; abstain without blocking. With `metadata.reason` set to `gpu-busy`, `model-too-large`, or `prompt-too-large`, the agent was willing but could not get a GPU (see below).
`block`	A strong objection that should stop the answer as it stands.
`failure`	The agent tried and could not complete - surfaced as a first-class signal, not hidden behind silence.

Treating failure as signal is deliberate. An agent that fails a tool call or cannot reach a source says so, so the coordinator can route around it, rather than standing aside silently and letting the crew mistake “no answer” for “no objection.”

The Orchestration Gap

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

A prototype agent is easy to build and hard to operate. The distance between “it works on my machine” and “it runs as dependable infrastructure” is where most agentic AI projects stall. This page describes that distance, and why neither the frameworks above it nor Kubernetes below it closes it.

From prototype to production

Building an agent is a good experience today. You wire up a framework (LangChain, LlamaIndex, an SDK), point it at a model, add a retriever and a few tools, and it works on your laptop against test data. Then it has to run for real, and a different set of questions starts:

Views and dashboards

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

This page is the reference. For a guided tour, see Develop a crew in VS Code.

What CrewForge changes

CrewForge applies only Kubemoot custom resources and Helm releases of them. It never deletes a namespace or any other kind of object; the operator owns cleanup through finalizers and owner references. Add … and Remove from Source… change only files of a source. Anything that deletes files, such as Delete Source…, moves them to your trash. Actions that only read are marked “nothing” in the action reference below.

Discussion Artifact Store

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

When a tooler fetches data from a live system, the result can be large: a full namespace inventory, a Prometheus time-series dump, a JSON response carrying hundreds of rows. The NATS discussion bus and the LLM context window were not designed to carry datasets. Dumping bulk data onto the bus truncates it, floods downstream agents’ context, and degrades the quality of reasoning that follows.

Kubemoot passes large outputs by reference. The data lands in an object store; the discussion message carries only a small reference and a preview. Agents that need the data fetch a targeted slice; most can answer from the preview alone.

How the Pieces Fit Together

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

Before you install anything, it helps to know where each piece runs and how they find each other. There are three ideas, and each builds on the one before.

The picture

Fitness from the editor

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

Fitness functions measure whether a crew does its job. CrewForge runs them, shows their results, and lets you hold or end a run, all against the same Kubemoot resources kubectl and kmctl use. Writing the scenarios themselves is covered in Define Fitness Functions.

Your scenarios

A crew source keeps its fitness definitions in a fitness/ folder, inside a chart or beside a bundle. Expand Fitness Scenarios under a source to list them: the scripts of each CrewFitnessSuite, each CrewFitness, and loose .adl (ADL) and .md (prose) scripts.

Models & Scheduling

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

Kubemoot composes capability from many small models rather than one large one, and it binds an agent to a model as late as possible. Two ideas make that work: loose model coupling and just-in-time scheduling.

Loose model coupling

An Agent spec names no model. It declares abstract capabilities - tool-calling, reasoning, kubernetes, and so on. Concrete models are separate resources: a Model (an LLM, by capability labels, not a hardcoded name) served by a ModelServer (an inference server on an accelerator, such as vLLM, the currently preferred engine, or Ollama).

Onboard MCP Tools

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

A crew gains new abilities by gaining new tools, and tools come from MCP servers. You can declare them directly, or let Kubemoot’s autonomic onboarding acquire them when the crew hits a capability gap. This guide covers both.

Declare a tool server directly

When you already know the MCP server you want, declare an MCPServer and let an MCPGateway discover it. The operator handles the deployment, health probes, and - for stdio servers - the auto-injected mcp-bridge sidecar.

Quickstart

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

This is a laptop trial: one script takes an empty Kubernetes cluster to a real crew answering a real question, on CPU, with no accelerator required. It runs the same protocol as a production deployment - a coordinator convening a Tooler, signals exchanged over NATS, an answer synthesized - just smaller and slower, because it runs on CPU with a 1-3B model instead of an accelerator with a reasoning-sized one. The trial uses Ollama, which is familiar and runs anywhere; an installation defaults to vLLM. See Installation for the accelerator-backed deployment this trial is a preview of, and the profile table below for exactly what’s smaller and slower.

Security

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

Reporting a vulnerability

Report a vulnerability privately, by either of these:

GitHub private vulnerability reporting. Open a private report on the kubemoot repository, or use Report a vulnerability on the Security tab of the affected repository (kubemoot, kmctl, vscode-crewforge, crews, or kubemoot-docs). The report is sent over HTTPS and only you and the maintainers can see it.
Email security@kubemoot.org. The project publishes no OpenPGP key, so email is not encrypted end to end; when the details must stay confidential in transit, use GitHub’s private reporting.

The security address is only for vulnerability reports; send every other question to moot@kubemoot.org or GitHub Discussions. Do not open a public issue, Discussion, or pull request for a security report.

Choosing a Model

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

Kubemoot runs on the GPUs you have. A crew is typically twenty or more agents sharing a small number of cards, so choosing a model is a capacity decision as much as a quality one. This page is the decision framework. For the CRD fields, the current model catalog, and the per-GPU fit matrix, see Models in Kubemoot.

Because an Agent names no model, changing your mind is cheap. Adopting a different model is a Model CR and a label, not an edit to every agent in the crew. That makes model choice a thing you measure and revise, not a thing you get right up front.

How Kubemoot Is Built and Secured

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

This page describes how the project builds, releases, and protects its software, and where you can see each practice for yourself. It follows the OpenSSF Best Practices criteria for open-source projects. The per-criterion answers live on the project’s Best Practices entry; this page explains the practices in plain words and links to the files, workflows, and pages that show them.

How changes are made

Pull requests from forks. Contributors fork a repository, branch off main, and open a pull request using the template. A maintainer review and approval is required to merge. See Contributing and Governance.
Maintainers use pull requests too. Every change to a public repository reaches main through a pull request that merges only after its required checks pass: the DCO sign-off, CodeQL, and a gate that waits for every other check, including the tests.
Conventional Commits. Every commit message carries a prefix such as fix: or feat:, and the prefix decides the version bump. See Contributing.
Developer Certificate of Origin. Every commit is signed off, and a pull request check named “DCO” verifies it (workflow). There is no contributor license agreement. See Contributing.
Tests ship with the change. A new feature comes with tests, and a bug fix comes with a test that fails without the fix. The pull request template has a checklist item for it (template). See Contributing.
AI-assisted work is visible. Agent-authored commits use the Klaude identity and name the model in a Co-Authored-By: trailer, and they pass the same gates as every other change. See Contributing.
License. Every repository is Apache License 2.0, for example the LICENSE of kubemoot.

How versions and releases work

Versions live only in git tags. Files in git hold 0.0.0; every build computes its version from the tags and stamps it into what it publishes, and CI never commits a version back. See The version rule.
Every merge to main builds a release candidate. Candidates are tagged X.Y.Z-rc.N and are not published publicly. See From merge to release.
A maintainer publishes a candidate. The Publish Release workflow starts as a dry run that publishes nothing, then runs again with approval. It copies the exact tested images by digest rather than rebuilding them (workflow).
Releases are immutable. A published version is never rewritten; a fix ships as the next version.
Release notes list what users see. Breaking changes, new features, fixes, and speedups, with a link to every commit. See Release notes and the releases of kubemoot.
One shared pipeline. Every repository uses the same pinned actions from kubemoot/release-actions, so the logic is not copied from repository to repository.
No stored registry tokens for CrewForge. The extension is published to the VS Code Marketplace and Open VSX only from the Publish Release workflow, in a protected environment that waits for maintainer approval, using federated sign-in instead of a stored token. See CrewForge.

How the supply chain is protected

Dependencies are pinned by digest. Container base images and GitHub Actions reference an immutable digest or commit, not a movable tag. The default workflow token is read-only, and a job that needs more asks for it.
How images are built. Every image is built inside the project’s own cluster, in a short-lived pod with no Docker daemon and no privileged container. The Java, GraalVM native, and Go images, and the image of this documentation site, are built with Cloud Native Buildpacks and the Paketo buildpacks, as a non-root user, and carry a software bill of materials. The images that keep a Dockerfile (the dashboard, the RAG query service, the code sandbox, and the test runner) are built by Buildah in a pod with its own user namespace, so the build is root only inside that namespace. The builder images are pinned by digest. Images go to the project’s own registry first, and Publish Release copies the tested image to GHCR by digest, never rebuilding it (see the roadmap).
Dependabot proposes updates to dependencies and Actions in every repository (configuration).
Signatures and provenance. kmctl and CrewForge releases carry a keyless Sigstore signature and SLSA build provenance. Every container image and Helm chart published to GHCR carries both, and the Kubemoot and crew GitHub Releases attach the provenance file. No signing key is stored; the certificate is issued to the release workflow’s identity. You can check any of them yourself with the commands in Verify images and charts.
Secret scanning with push protection is on for every public repository and blocks a push that contains a known credential format.

How the code is checked

Tests run in CI on every pull request and every push to main, and the quickstart runs against each release’s published chart. The Development Guide lists the command for each component.
Linters run in CI for every language and block a merge on any finding: golangci-lint for each Go module, Checkstyle for the Java services, ESLint and svelte-check for the dashboard and CrewForge, ruff for Python, and ShellCheck for scripts, with a cyclomatic complexity limit of 10. A false positive is suppressed on its line with the reason. See Linters and warnings.
CodeQL scans every repository on every pull request, every push to main, and weekly. Every alert it has raised was fixed.
SonarQube applies a quality gate on every push to main in the code repositories (workflow).
Fuzz tests. Every Go native fuzz target in the operator runs on each operator change (workflow). Fuzzing has found real parser bugs, and each failing input is kept as a regression seed beside its fix.
OpenSSF Scorecard runs on every push to main and weekly, and the results are public (workflow).

The same checks are summarized on Security.

Install the Operator

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

This page installs the Kubemoot operator: what a cluster needs before it runs, and how to install it on your own cluster - the accelerator-backed deployment Kubemoot is built for. If you want to try the protocol first without an accelerator, the Quickstart runs a smaller CPU-only trial with its own script and its own limits, described below.

The operator is one part of the ecosystem. The others install separately, each from its own page:

kmctl - the CLI

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

kmctl (“kubemoot control”) is the command-line tool for working with crews and Kubemoot. It is the scriptable, terminal-native way to scaffold, apply, and exercise crews; CrewForge is the VS Code extension for developing crews and talking to them from the editor.

Status

kmctl is early and actively developed. It is installable from GitHub releases and ships a working command set covering cluster inspection, crew scaffolding, resource management, live conversation, fitness suite execution, and shell completion. Check your installed version with kmctl version, and see the GitHub Releases page for the latest. A small set of subcommands is still planned and marked as such in the reference page.

kmctl User Guide

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

kmctl is the command-line tool for Kubemoot. This guide covers installation, a runnable quickstart that walks through the core workflow, and shell-completion setup.

For the complete command reference, see kmctl Reference. For an overview of kmctl’s role in the ecosystem, see kmctl - the CLI.

Command structure

kmctl uses a hybrid noun-verb layout, chosen deliberately as the best fit for a domain CLI with deeply-nested resources and actions that have no clean kubectl equivalent.

MCP Tools

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

An agent’s knowledge comes from its model and its RAG sources; its abilities - to read a cluster, query a database, search the web - come from tools. Kubemoot exposes tools through the Model Context Protocol (MCP), so any MCP server becomes a capability a crew can use.

Servers, gateway, agents

Three resources form the tool chain, and agents never connect to a tool server directly:

Agent → MCPGateway → MCPServer

An MCPServer deploys one MCP tool server (a container image) and manages its lifecycle: the deployment, health probes, and - for the many servers that only speak stdio - an auto-injected mcp-bridge sidecar that bridges HTTP/SSE to the server’s stdin/stdout.
An MCPGateway is the hub agents talk to. It discovers MCPServers by label selector, performs the MCP handshake with each, aggregates all their tools, and routes an agent’s tool call to the right server.
An Agent reaches the gateway through its runtime and sees the union of tools the gateway exposes, narrowed by the agent’s own enabledTools / disabledTools.

This indirection means you can add or remove a tool server, or scale the gateway, without touching agent specs - the gateway rediscovers servers and re-aggregates tools.

Releases and Versioning

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

Every merge to main builds a release candidate. A maintainer publishes a tested candidate as a public release. Users install final releases; main is in development.

The version rule

Versions live only in git tags. Files in git hold 0.0.0. Every build computes its version from the tags and stamps it into what it publishes, and CI never commits a version back to the repository. The source tree therefore never carries a release or candidate number, and the tag is the only record of what was released.

Settings and permissions

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

Settings

Open Settings in VS Code and search for crewforge.

Setting	Default	Meaning
`crewforge.kubeconfig`	empty	Path to a kubeconfig file. Empty uses `KUBECONFIG`, then `~/.kube/config`.
`crewforge.context`	empty	Kubernetes context to use. Empty uses the kubeconfig’s current context.
`crewforge.namespaces`	`[]`	Show crews only in these namespaces. Set it when your account may read only some namespaces. Empty shows every namespace you can read.
`crewforge.streamTimeoutSeconds`	`600`	Longest a single turn may stream before CrewForge gives up on it. The minimum is 60.
`crewforge.dashboardService`	empty	The Kubemoot dashboard’s Service as `namespace/name:port`. CrewForge reads it through the Kubernetes service proxy, read-only, for thread counts, discussion failures, fitness scores, and archived iterations. Empty finds the Service labelled `app.kubernetes.io/part-of=kubemoot` whose `app.kubernetes.io/name` is `dashboard` (the operator chart’s subchart) or `kubemoot-dashboard` (a standalone install). Add an optional base path, `namespace/name:port/base`, when the dashboard serves under a path such as `/dashboard`.
`crewforge.yamlFormat`	`yaml`	How Show Live YAML, Show Source YAML, and Compare with Live write an object. `yaml` is block YAML. `kyaml` is KYAML, the strict YAML subset `kubectl get -o kyaml` prints: every string quoted, maps in `{ }`, lists in `[ ]`. KYAML is still valid YAML.
`crewforge.dashboardUrl`	empty	The address of the Kubemoot dashboard for this cluster. Powered by Kubemoot in a chat opens it, and Open this turn in the Kubemoot dashboard appears under an answer only when this is set. Behind a `kubectl port-forward`, use the local address. Empty makes Powered by Kubemoot open this setting.

The Kubemoot dashboard is optional. Without it, the parts of the crew and fitness dashboards that come from it (discussion counts, agent failures, judge scores, and the results workbook download) say they are not available.

Secrets and tools

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

A tool that sends mail, queries a database, or calls an API needs a credential. Kubemoot keeps that credential away from the model. The principle:

The model never holds a secret; only the tool process does. An agent calls a tool and receives results. It never receives the token, password, or key behind the tool.

Why

A model reads prompts and writes text. Anything placed in a prompt, a ConfigMap an agent reads, or an agent’s environment can appear in a response, a log, a discussion artifact, or a retrieved document. A credential held only by the tool process cannot be leaked by what a model says, and a prompt-injected agent has nothing to hand over. The tool chain reinforces this boundary: agents reach tools only through the MCPGateway, and the credential lives in the MCPServer pod behind it.

Troubleshooting

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

Where the logs are

CrewForge writes to its own output channel. Open View > Output and choose CrewForge from the drop-down. It holds page errors, Lint failures, and the output of the helm and kubectl commands behind a deploy, redeploy, or undeploy. A failed deploy opens it for you. A failed kmctl create shows kmctl’s own message in a dialog.

For a bug report, run CrewForge: Show Connection Info and use its Copy button. It gives CrewForge’s version, the Kubemoot operator’s version, the Kubernetes server version, and the context and server address.

Questions

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

Short answers, each one a position you can hold us to, with the page that backs it.

Why not just use Claude Code with a frontier model?

Often you should. A frontier model wins open-ended, one-off work where data may leave your network and per-token cost is acceptable. Kubemoot is for the other situation: data that stays home, cost that is fixed by hardware rather than by usage, behaviour governed as code, and agents that run where your platform already runs, under its RBAC, quotas, and lifecycle. It is not either-or: Claude Code can use a crew as one agent through the crew liaison, the frontier model at the edge and the private crew on the domain work. We do not claim that a crew of small models out-reasons a frontier model; that is not what it is for. What a crew does give you is the choice of where the compute is spent: tokens billed by a server, or watts on hardware you run.

Related Projects

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

A common first question is “how is this different from X?” This page answers it for the projects people ask about most. Each entry says what the project is, where it overlaps with Kubemoot, and where the two differ. Several of these are the better choice for some jobs, and the entries say so. Descriptions of other projects are summaries of their own documentation; read their sites for the current picture.

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.

Roadmap

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

Kubemoot is young. If a capability you expect is missing, it is more likely on this page than rejected. This page lists the significant directions under consideration or in progress: the ones that change what a crew can be. Small features, conveniences, and fixes live on the project board, not here. Each item says what exists today, so nothing below is mistaken for something already shipped.

Ideas become work in the open: propose or argue for one in Discussions.

About the Name

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

In Anglo-Saxon England, a moot (or gemōt) was an assembly gathered to deliberate and reach a decision. From village moots to the great Witenagemot that advised kings, these assemblies embodied a principle: better decisions emerge when diverse perspectives contribute to a shared deliberation.

Readers of Tolkien know another one. In The Two Towers, the Ents hold an Entmoot to decide whether to march on Isengard: a gathering in a hidden dell, unhurried, where every Ent speaks and nothing is decided until all have. It takes three days. A Kubemoot crew takes minutes, which is still slower than one model asserting an answer, and for the same reason: the answer is not one voice’s.