Hermes Agent + Kubernetes: Use the k8s Skill Safely

Scope: operate Kubernetes, not host Hermes on it

There are two different questions hidden inside “Hermes Agent Kubernetes.” One is how to deploy the Hermes runtime into a Kubernetes cluster. The other is how to let a running Hermes agent inspect and operate Kubernetes. This guide covers the second workflow.

The upstream Hermes quickstart explicitly uses Kubernetes as a skills example. It does not, in that example, provide an official Hermes Helm chart. Keeping those two topics separate avoids inventing deployment support that the upstream project does not document.

Architecture

You → Hermes Agent → k8s skill → isolated terminal backend → kubectl → Kubernetes API
                                                     │
                                                     └─ dedicated kubeconfig + least-privilege RBAC

The skill gives Hermes task-specific instructions. The terminal backend runs the actual commands. kubectl authenticates with a dedicated cluster identity, and Kubernetes RBAC remains the final enforcement boundary.

Step 1: prepare a controlled execution environment

Do not begin by exposing your laptop's full shell or a control-plane node. Use one of Hermes's isolated terminal backends:

# Isolated local execution
hermes config set terminal.backend docker

# Or execute on a dedicated operations host
hermes config set terminal.backend ssh

A Docker backend is useful for an isolated tool environment. SSH is useful when an existing bastion or operations host already has audited network access to the cluster. In either case, install a pinned, cluster-compatible kubectl version in that environment.

Step 2: create a least-privilege Kubernetes identity

Give Hermes its own identity. Do not reuse an administrator's personal kubeconfig.

• Limit access to the namespaces Hermes actually needs.
• Start with read-only verbs such as get, list, and watch.
• Add mutation verbs only for a documented workflow.
• Exclude secrets unless reading them is essential and explicitly approved.
• Use short-lived credentials where your cluster supports them.
• Keep API-server audit logging enabled.

Step 3: verify kubectl before adding the skill

Test the identity directly in the same terminal backend Hermes will use:

kubectl auth can-i get pods -n staging
kubectl auth can-i create deployments -n staging
kubectl config current-context
kubectl get namespaces

The answers should match your intended policy. If the identity can access more than expected, fix RBAC before involving the agent.

Step 4: find and install the Kubernetes skill

The current Hermes quickstart documents this flow:

hermes skills browse
hermes skills search kubernetes
hermes skills install openai/skills/k8s

Hermes runs a security scan before installing the skill. Read the scan output and inspect the skill before approving it, especially if the source or version differs from the official quickstart example.

Step 5: start with read-only tasks

Invoke the skill explicitly and begin with inspection:

/k8s

Show the pods in the staging namespace.
Summarize any CrashLoopBackOff events.
Do not change the cluster.

Explicit constraints make the intent clear, but they do not replace RBAC. The cluster identity should still be technically unable to perform unauthorized mutations.

Step 6: add a reviewed deployment workflow

After read-only behavior is reliable, introduce one narrow mutation path. The official quickstart gives this example:

/k8s deploy the staging manifest

A safer production process separates planning from execution:

1. Ask Hermes to inspect the manifest and current cluster state.
2. Generate a diff or dry-run result.
3. Review the proposed objects, image tags, resources, and namespace.
4. Approve the exact apply or rollout command.
5. Verify rollout status, events, and health checks.
6. Keep a tested rollback command ready.

kubectl diff -f staging/
kubectl apply --server-side --dry-run=server -f staging/
kubectl rollout status deployment/example -n staging

Good Kubernetes tasks for Hermes

• Summarize pod health, events, and recent restarts
• Compare desired manifests with live resources
• Collect logs from a named workload and time range
• Check whether a rollout completed successfully
• Prepare a remediation plan for human review
• Run a narrow, pre-approved staging deployment workflow

Tasks that need stronger controls

• Deleting namespaces, persistent volumes, or custom resources
• Changing RBAC, admission policies, or network policies
• Reading or rotating Secrets
• Scaling production workloads to zero
• Executing commands inside privileged pods
• Changing cluster-wide operators or control-plane components

These should require an explicit human approval, narrow credentials, a recorded change request, and a rollback plan. Some environments should keep them permanently outside the agent's permissions.

Operational checklist

• Dedicated kubeconfig and service identity
• Namespace-scoped RBAC wherever possible
• Docker or dedicated SSH execution backend
• Pinned kubectl and reviewed skill source
• Read-only test before mutation permissions
• Dry run or diff before apply
• Human approval for production changes
• Cluster audit logs and Hermes session logs retained
• Known rollback procedure tested in staging

Official references

See the Hermes Agent quickstart for the documented skill commands and the Hermes tools documentation for current terminal backend behavior.

Hermes Agent + Kubernetes FAQ

Related operations guides

• Hermes Agent skills guide
• Hermes Agent with Docker
• Hermes Agent CLI reference
• Hermes Agent on a VPS