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
• memory - MemoryStore recall and erasure
• memorystore - MemoryStore creation
• samples - Example deployment 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)
--memory-store		MemoryStore reference; enables remote memory
--memory-default-read-scope		Default read scope (requires --memory-store)
--memory-read-scopes		Comma-separated allowed read scopes (requires --memory-store)
--memory-tools		Memory tools to expose: read, write, or all (requires --memory-store)

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

# With scoped remote memory
kaos agent deploy my-agent -a my-api -m gpt-4o --memory-store support-memory --memory-default-read-scope user --memory-read-scopes session,agent,user,group --memory-tools read

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)
--namespace	-n	Namespace of the Agent
--port	-p	Local port (default: 9001)
--stream	-s	Stream response
--session		Conversation session ID, sent as X-Session-ID

Example:

kaos agent invoke my-agent -n my-namespace --session ticket-42 --message "Hello, how are you?"

User identity is not selectable with an invoke flag. On OIDC-enabled clusters it comes from the verified bearer token presented through the gateway.

kaos agent delete

Delete an Agent.

kaos agent delete NAME [OPTIONS]

kaos agent tools

Show the tool names and JSON schemas an Agent presents to its model. This includes the entitled level enum on search_memory.

kaos agent tools NAME [-n NAMESPACE] [--json]

kaos agent a2a send

Send a message to an Agent via A2A JSON-RPC protocol.

kaos agent a2a send NAME --message "Hello" [OPTIONS]

Option	Short	Description
NAME		Agent name (required)
--message	-m	Message to send (required)
--async		Execute as async task (returns task ID for polling)
--session-id	-s	Session/context ID
--namespace	-n	Namespace of the Agent
--port	-p	Local port for port-forwarding (default: 9004)
--json		Output raw JSON response

# Sync message (waits for response)
kaos agent a2a send my-agent --message "Check status"

# Async task (returns task ID immediately)
kaos agent a2a send my-agent --message "Analyze logs" --async --json

kaos agent a2a get

Get task status from an Agent via A2A GetTask.

kaos agent a2a get NAME --task-id TASK_ID [OPTIONS]

Option	Short	Description
NAME		Agent name (required)
--task-id	-t	Task ID to retrieve (required)
--namespace	-n	Namespace of the Agent
--port	-p	Local port for port-forwarding (default: 9004)
--json		Output raw JSON response

kaos agent a2a cancel

Cancel a task on an Agent via A2A CancelTask.

kaos agent a2a cancel NAME --task-id TASK_ID [OPTIONS]

Option	Short	Description
NAME		Agent name (required)
--task-id	-t	Task ID to cancel (required)
--namespace	-n	Namespace of the Agent
--port	-p	Local port for port-forwarding (default: 9004)
--json		Output raw JSON response

---

kaos memory

Inspect or erase a central MemoryStore through a temporary Kubernetes port-forward. --store can be omitted when the namespace contains exactly one MemoryStore.

kaos memory recall

Without a query the command lists the selected tiers. Add --long-term-query/-q for semantic long-term recall. --include is repeatable and comma-separated, defaults to all tiers, and accepts a|all|s|short-term|m|medium-term|l|long-term.

kaos memory recall --store support-memory --scope session --session SESSION_ID -q TEXT [OPTIONS]
kaos memory recall --store support-memory --scope store --include l [OPTIONS]

Option	Short	Description
--store		MemoryStore name; optional when exactly one exists
--scope		session, agent, user, or store (required)
--session		Session ID; required only for session scope
--agent		Agent name; required only for agent scope
--user		User principal; required only for user scope. A username with a cached kaos auth login session resolves to its verified subject; anything else passes through verbatim
--long-term-query	-q	Semantic query; without it the command uses the list endpoint
--include		Selected tiers; repeat or comma-separate aliases. Defaults to all
--top-k		Maximum semantic results (default: 10)
--namespace	-n	Kubernetes namespace
--json		Output JSON

Agent names are expanded to the stable kaos://agent/<namespace>/<name> identity before the service call.

kaos memory forget

Erase every long-term record and attributed conversational session at a scope. The command prints the resolved scope and prompts for confirmation unless --yes is passed.

kaos memory forget --store support-memory --scope user --user alice [-n NAMESPACE]
kaos memory forget --store support-memory --scope store --yes

---

kaos memorystore

MemoryStore creation commands.

kaos memorystore create

Create a local, Chroma-backed MemoryStore with a 1Gi persistent volume.

kaos memorystore create NAME --modelapi MODELAPI [OPTIONS]

Option	Short	Default	Description
NAME			MemoryStore name (required)
--modelapi			ModelAPI reference used by both models (required)
--summarization-model		gpt-4o-mini	Summarization model
--embedding-model		text-embedding-3-small	Embedding model
--short-term-token-budget			Token budget, rendered as KAOS_MEMORY_TOKEN_BUDGET on this CRD version
--medium-term-enabled		false	Enable rolling summaries through KAOS_MEMORY_ROLLING_SUMMARY
--max-read-scope			Store read-scope ceiling: session, agent, or user
--failure-mode			Default failure mode: soft or strict
--namespace	-n	current	Target namespace
--dry-run		false	Print YAML instead of creating

Example:

kaos memorystore create support-memory --modelapi support-modelapi --short-term-token-budget 64 --medium-term-enabled -n support-demo

---

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/.

Samples install into the current kubectl context namespace by default. Use -n to specify a target namespace. Namespace resources are never created or deleted — the namespace must already exist.

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	Target namespace (default: current kubectl context)
--wait		Wait for deployments to be available
--wait-timeout		Timeout in seconds (default: 120)
--dry-run		Print YAML instead of deploying
--modelapi		Use existing ModelAPI instead of sample's built-in one
--mode		Override ModelAPI mode (Proxy/Hosted)
--model	-m	Override model name
--api-secret		Override API secret (secretname:key)
--provider		Override LiteLLM provider (e.g., openai, nebius)

When --modelapi is used, the sample's ModelAPI resource is skipped (not deployed). Agents reference the specified existing ModelAPI instead.

Examples:

kaos samples deploy 1-simple-echo-agent -n my-ns
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 deploy 1-simple-echo-agent -n my-ns --modelapi my-existing-api
kaos samples deploy 7-memory-agent -n support-demo --model gpt-4o-mini

kaos samples delete

Delete a sample's resources. Does not delete namespaces.

kaos samples delete NAME [OPTIONS]

Option	Short	Description
--namespace	-n	Namespace override (must match namespace used during deploy)
--modelapi		Skip deleting ModelAPI (use when deployed with --modelapi)

---

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