Skip to content
kube-agents

What is kube-agents

kube-agents is a small collection of first-party components you install into a Kubernetes cluster (GKE today) plus a persona-and-skills workspace that tells the resulting agent how to behave.

The components

Section titled “The components”

1. Kubernetes operator (k8s-operator/)

Section titled “1. Kubernetes operator (k8s-operator/)”

A Go controller built with Kubebuilder that defines the PlatformAgent custom resource and reconciles it into a running Platform Agent Deployment, Service, ServiceAccount, RBAC bindings, and a ConfigMap for the persona and skills. Source: k8s-operator/.

2. The agent Deployment (Planning Agent + Platform Agent + Cluster Agents)

Section titled “2. The agent Deployment (Planning Agent + Platform Agent + Cluster Agents)”

The PlatformAgent CR reconciles into a Deployment running the Hermes runtime. The default image is ghcr.io/gke-labs/kube-agents/platform-agent, built on top of nousresearch/hermes-agent. One gateway process hosts the co-located Hermes profiles:

The Planning Agent (agents/chat/, the default profile) — the conversational front door and the only profile that receives chat ingress. Its agent_roster plugin injects the current specialists into every turn, so picking one to delegate to costs no tool call; the router MCP server (agents/chat/scripts/router_server.py) exposes the same list as list_agents for an on-demand refresh. Both render from agents/chat/scripts/agent_roster.py. It delegates work to the specialists as kanban cards and holds no infrastructure tools of its own.

The Platform Agent (agents/platform/, the platform profile) — the privileged specialist, scaffolded at pod startup from the workspace template by profile_scaffold.py. Inside it:

  • Persona (SOUL.md) — the system prompt. Describes the Platform Agent’s role, safety rails, kanban worker protocol, autonomous recovery ladder, and reporting style.
  • Routing description (CAPABILITIES.md) — the one-liner that describes this profile on the Planning Agent’s roster, so it knows what to route here.
  • Skills (agents/platform/skills/*/SKILL.md) — Claude-style skill bundles the agent loads on demand.
  • Governance SOPs (agents/platform/governance/*.md) — standard operating procedures the cron watchdogs invoke.
  • Cron watchdogs (agents/platform/cron/jobs.json) — scheduled autonomous jobs, each pointing at a governance SOP. Ticking is a property of the Planning Agent’s gateway, the only running one, so a job on its roster advances this profile’s schedule once a minute.
  • MCP servers — declared in agents/platform/config.yaml. Shipping today: platform_control (an in-pod Python MCP server for session and agent-internal tooling) and gke (the remote GKE MCP server via mcp-remote).
  • Toolsets — cli and api_server variants aggregate the MCP servers into what the Hermes CLI and REST API surface, plus a kanban toolset for creating and routing delegation cards.

The Cluster Agents (agents/cluster/, per-cluster cluster-* profiles) — read-only single-cluster SREs, scaffolded at runtime from the baked template by cluster_agent_profile.py, one per managed GKE cluster. Each is pinned to its cluster (scoped KUBECONFIG, a cluster_identity block in its config), carries only the read-only gke and developer_knowledge MCP servers plus six runtime-debugging skills (agents/cluster/skills/), and returns diagnoses over the kanban board — it never mutates cluster state or opens PRs. See Cluster Agents.

3. Inference gateway

Section titled “3. Inference gateway”

The Platform Agent talks to an LLM through a Completions API proxy so provider choice is a config toggle:

4. GitHub Token Minter (Minty)

Section titled “4. GitHub Token Minter (Minty)”

Short-lived GitHub App installation tokens signed via GCP KMS and delivered through Workload Identity. This lets the submit-suggestion skill (and the github-issue-resolver watchdog) open pull requests against your GitOps repo without a long-lived PAT. Source: k8s-operator/config/integrations/github/.

What actually runs after ./install.sh

Section titled “What actually runs after ./install.sh”

Once the installer finishes, you have:

  • A GKE cluster with Workload Identity.
  • The operator controller manager Deployment.
  • One PlatformAgent custom resource and the reconciled Platform Agent Deployment, running Hermes.
  • A LiteLLM Deployment (or vLLM if you opted in).
  • A Minty Deployment plus a GCP KMS keyring and key.
  • A Google Chat Pub/Sub topic + subscription and a Kubernetes Secret holding your model provider API key.
  • Optionally: Slack tokens in the credentials Secret (only if Slack was enabled at install).

What is not included

Section titled “What is not included”
  • No local Kind path — there is no kind workflow in the repo; the installer and the Terraform composition it drives both target GKE. You need a real GKE cluster. (For versioned Helm/Terraform installs on GKE, see Helm and Kind.)
  • No web UI or CLI beyond kubectl port-forward + the Hermes API — chat is the primary user interface.
  • No cross-cloud abstractions — the shipping MCP toolset, IAM assumptions, and install path all target GKE. The runtime and persona are cluster-agnostic; the skill catalog is not.

Where to go next

Section titled “Where to go next”