devantler-tech/agent-plugins/ksail

ksail

KSail bundles common Kubernetes tooling (kubectl, helm, kind, k3d, vcluster, flux, argocd, …) into a single Go binary. Local clusters need only Docker; cloud providers also need that provider's credentials, and EKS additionally needs the eksctl CLI.

Full docs: <https://ksail.devantler.tech>. Treat the docs site and ksail <command> --help as the source of truth; do not paraphrase flag semantics — link users to the relevant page instead.

Prerequisites

• ksail on PATH (see <https://ksail.devantler.tech/installation/>)
• Docker daemon running (required for the local Docker provider)
• Cloud credentials only when using non-Docker providers (HCLOUD_TOKEN for Hetzner, OMNI_SERVICE_ACCOUNT_KEY for Omni, standard AWS SDK credentials such as aws configure or AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/AWS_REGION for AWS)
• eksctl on PATH for the EKS distribution (see <https://ksail.devantler.tech/distributions/eks/>)

When to use this skill

Invoke when the user asks to:

• Create, start, stop, update, or delete a local Kubernetes cluster
• Scaffold a KSail project (ksail.yaml, native distribution config, k8s/ kustomization)
• Bootstrap Flux or ArgoCD on a local cluster
• Back up or restore cluster resources
• Apply, generate, validate, or watch Kubernetes workloads
• Export/import container images for air-gapped clusters
• Manage SOPS-encrypted secrets via ksail workload cipher
• Work with the ksail MCP server or AI chat TUI

Command groups (source of truth: ksail --help)

• ksail cluster … — lifecycle: init, create, update, diff, delete, start, stop, info, list, connect, switch, backup, restore, oidc (OIDC authentication: get-token)
• ksail workload … — apply, create, edit, get, describe, explain, delete, logs, exec, expose, gen, validate, install, scale, rollout, scan, wait, images, export, import, watch, push, reconcile, and cipher (SOPS-based secret management: encrypt, decrypt, edit, import, rotate)
• ksail tenant … — multi-tenancy: create, delete
• ksail open … — interfaces: web (browser UI), desktop (native app), chat (AI chat TUI powered by GitHub Copilot), mcp (MCP server — already auto-registered by this plugin)

Flag-level docs live under <https://ksail.devantler.tech/cli-flags/>. Reference that page for any non-trivial flag question instead of answering from memory.

Typical flows

Scaffold + launch a local cluster:

ksail project init --name my-app            # writes ksail.yaml, native config, k8s/kustomization.yaml
ksail cluster create                        # creates + starts the cluster (Docker required)
ksail cluster connect                       # opens K9s against the cluster

Distribution is chosen via --distribution (Vanilla, K3s, Talos, VCluster, KWOK, EKS). Provider defaults to Docker for local distributions; Talos also supports Hetzner and Omni; EKS requires --provider AWS and ksail cluster create is not yet functional for EKS (cluster init only — see <https://ksail.devantler.tech/distributions/eks/>).

MCP server

This plugin registers the ksail MCP server via .mcp.json (command: ksail, args: [open, mcp]). The ksail cluster, ksail workload (including the nested ksail workload cipher SOPS operations), project and tenant commands are exposed as consolidated MCP tools (cluster_read, cluster_write, workload_read, workload_write, project_read, project_write, tenant_write). Prefer these tools for cluster/workload operations when running inside Copilot CLI.

Safety

• ksail cluster delete destroys clusters and (with --delete-storage) local volumes. Confirm intent before running non-interactively.
• ksail cluster update may recreate clusters when immutable fields change; use --dry-run first.
• ksail workload cipher encrypt/rotate mutate files in-place; ensure they are committed before rotation.