CLI Command Reference

Complete reference for all KAOS CLI commands.

Command Structure

kaos <subcommand> <action> [OPTIONS]

Subcommands:

• system - Operator and cluster management
• mcp - MCPServer management
• agent - Agent management
• modelapi - ModelAPI management
• ui - Web UI

---

kaos system

Operator installation and cluster management.

kaos system install

Install the KAOS operator.

kaos system install [OPTIONS]

Option	Short	Default	Description
--namespace	-n	kaos-system	Installation namespace
--release-name		kaos	Helm release name
--version		latest	Chart version
--set			Helm values
--wait		false	Wait for ready
--monitoring-enabled			Install monitoring stack (signoz or jaeger)
--gateway-enabled		false	Install Gateway API (Envoy Gateway) and configure routing
--metallb-enabled		false	Install MetalLB for LoadBalancer support (KIND/bare-metal)
--chart-path			Path to local Helm chart directory (for development)

kaos system uninstall

Uninstall the KAOS operator.

kaos system uninstall [OPTIONS]

Option	Default	Description
--namespace	kaos-system	Namespace to uninstall from
--release-name	kaos	Helm release name
--monitoring-enabled		Also uninstall monitoring (signoz or jaeger)
--gateway-enabled	false	Also uninstall Gateway API (Envoy Gateway)
--metallb-enabled	false	Also uninstall MetalLB

kaos system status

Show cluster status.

kaos system status

Shows operator health, CRDs, resources, and gateway status.

kaos system runtimes

List registered MCP runtimes.

kaos system runtimes [OPTIONS]

Option	Short	Default	Description
--namespace	-n	kaos-system	Operator namespace

kaos system create-rbac

Generate RBAC YAML for MCPServer ServiceAccounts.

kaos system create-rbac [OPTIONS]

Option	Short	Description
--name	-n	ServiceAccount name (required)
--namespace	-ns	Namespace(s) to access
--read-only		Read-only permissions
--cluster-wide		ClusterRole instead of Role
--output	-o	Output file (default: stdout)

Example:

kaos system create-rbac --name k8s-mcp-sa --namespace my-ns > rbac.yaml
kubectl apply -f rbac.yaml

---

kaos mcp

MCPServer lifecycle management.

kaos mcp init

Scaffold a new FastMCP server project.

kaos mcp init [DIRECTORY] [OPTIONS]

Option	Description
--force	Overwrite existing files

Creates: server.py, requirements.txt, README.md

kaos mcp build

Build a Docker image from FastMCP server.

kaos mcp build [OPTIONS]

Option	Short	Default	Description
--name	-n	(required)	Image name
--tag	-t	latest	Image tag
--dir	-d	.	Source directory
--entry	-e	server.py	Entry point
--kind-load			Load to KIND cluster
--create-dockerfile			Generate Dockerfile
--platform			Docker platform

Example:

kaos mcp build --name my-mcp --tag v1 --kind-load

kaos mcp deploy

Deploy an MCPServer.

kaos mcp deploy [NAME] [OPTIONS]

Option	Short	Description
NAME		MCPServer name (auto-inferred from pyproject.toml)
--image	-i	Custom image
--runtime	-r	Registered runtime
--namespace	-n	Target namespace
--params	-p	Runtime parameters
--sa		ServiceAccount name

Examples:

# From custom image
kaos mcp deploy my-mcp --image my-image:v1

# From registered runtime
kaos mcp deploy slack-mcp --runtime slack

# Auto-infer from pyproject.toml
kaos mcp deploy

kaos mcp list

List MCPServers.

kaos mcp list [OPTIONS]

Option	Short	Default	Description
--namespace	-n	all	Filter by namespace
--output	-o	wide	Output format

kaos mcp get

Get MCPServer details.

kaos mcp get NAME [OPTIONS]

kaos mcp logs

View MCPServer logs.

kaos mcp logs NAME [OPTIONS]

Option	Short	Description
--follow	-f	Stream logs
--tail		Number of lines

kaos mcp invoke

Invoke an MCP tool.

kaos mcp invoke NAME [OPTIONS]

Option	Short	Description
--tool	-t	Tool name (required)
--args	-a	JSON arguments
--port	-p	Local port (default: 9000)

Example:

kaos mcp invoke echo-mcp --tool echo --args '{"message": "hello"}'

kaos mcp delete

Delete an MCPServer.

kaos mcp delete NAME [OPTIONS]

---

kaos agent

Agent lifecycle management.

kaos agent deploy

Deploy an Agent.

kaos agent deploy NAME --modelapi MODELAPI --model MODEL [OPTIONS]

Option	Short	Description
NAME		Agent name (required)
--modelapi	-a	ModelAPI reference (required)
--model	-m	Model name (required)
--namespace	-n	Target namespace
--instructions	-i	Agent instructions
--mcp		MCP server references (multiple)
--sub-agent		Sub-agent references (multiple)

Examples:

# Basic agent
kaos agent deploy my-agent --modelapi my-api --model gpt-4o

# With instructions and MCP tools
kaos agent deploy my-agent -a my-api -m gpt-4o -i "You are a helpful assistant" --mcp calculator

kaos agent list

List Agents.

kaos agent list [OPTIONS]

kaos agent get

Get Agent details.

kaos agent get NAME [OPTIONS]

kaos agent logs

View Agent logs.

kaos agent logs NAME [OPTIONS]

kaos agent invoke

Send a message to an Agent.

kaos agent invoke NAME [OPTIONS]

Option	Short	Description
--message	-m	Message (required)
--port	-p	Local port (default: 9001)
--stream	-s	Stream response

Example:

kaos agent invoke my-agent --message "Hello, how are you?"

kaos agent delete

Delete an Agent.

kaos agent delete NAME [OPTIONS]

---

kaos modelapi

ModelAPI lifecycle management.

kaos modelapi deploy

Deploy a ModelAPI.

kaos modelapi deploy NAME [OPTIONS]

Option	Short	Description
NAME		ModelAPI name (required)
--mode	-m	Mode: Proxy (LiteLLM) or Hosted (Ollama). Default: Proxy
--model		Model name (required for Hosted mode)
--namespace	-n	Target namespace

Examples:

# Deploy Proxy mode (LiteLLM)
kaos modelapi deploy my-api

# Deploy Hosted mode (Ollama)
kaos modelapi deploy my-api --mode Hosted --model smollm2:135m

kaos modelapi list

List ModelAPIs.

kaos modelapi list [OPTIONS]

kaos modelapi get

Get ModelAPI details.

kaos modelapi get NAME [OPTIONS]

kaos modelapi logs

View ModelAPI logs.

kaos modelapi logs NAME [OPTIONS]

kaos modelapi invoke

Send a chat completion request.

kaos modelapi invoke NAME [OPTIONS]

Option	Short	Description
--message	-m	Message (required)
--model		Model name (required)
--port	-p	Local port (default: 9002)

Example:

kaos modelapi invoke my-api --model gpt-4 --message "Hello"

kaos modelapi delete

Delete a ModelAPI.

kaos modelapi delete NAME [OPTIONS]

---

kaos ui

Start the KAOS web UI.

kaos ui [OPTIONS]

Option	Default	Description
--k8s-url	auto	Kubernetes API URL
--expose-port	8010	Local proxy port
--no-browser	false	Don't open browser
--monitoring-enabled		Enable monitoring UI (signoz or jaeger)
--system-namespace	kaos-system	Namespace where KAOS system and monitoring are installed

---

kaos samples

Deploy and manage example configurations from operator/config/samples/.

kaos samples list

List available sample configurations.

kaos samples list

kaos samples deploy

Deploy a sample configuration with optional overrides.

kaos samples deploy NAME [OPTIONS]

Option	Short	Description
--namespace	-n	Override namespace for all resources
--wait		Wait for deployments to be available
--wait-timeout		Timeout in seconds (default: 120)
--dry-run		Print YAML instead of deploying
--modelapi		Override ModelAPI name reference
--mode		Override ModelAPI mode (Proxy/Hosted)
--model	-m	Override model name
--api-secret		Override API secret (secretname:key)

Examples:

kaos samples deploy 1-simple-echo-agent
kaos samples deploy 3-hierarchical-agents --namespace my-ns
kaos samples deploy 1-simple-echo-agent --model "llama3:8b" --dry-run
kaos samples deploy 1-simple-echo-agent --api-secret nebius-secrets:api-key

kaos samples delete

Delete a sample's resources.

kaos samples delete NAME [OPTIONS]

Option	Default	Description
--namespace		Namespace override (must match namespace used during deploy)

---

Environment Variables

Variable	Description
KUBECONFIG	Path to kubeconfig
KUBERNETES_SERVICE_HOST	In-cluster API host

Exit Codes

Code	Meaning
0	Success
1	Error

Common Workflows

Create and deploy custom MCP server

# 1. Scaffold project
kaos mcp init my-tools
cd my-tools

# 2. Edit server.py with your tools

# 3. Build and load to KIND
kaos mcp build --name my-tools --tag v1 --kind-load

# 4. Deploy
kaos mcp deploy my-tools --image my-tools:v1

Deploy Kubernetes MCP with RBAC

# 1. Generate RBAC
kaos system create-rbac --name k8s-sa --namespace default > rbac.yaml
kubectl apply -f rbac.yaml

# 2. Deploy
kaos mcp deploy k8s-tools --runtime kubernetes --sa k8s-sa