Skip to content
KSail
KSail CLI showing ASCII art banner and help output KSail CLI showing ASCII art banner and help output

KSail Documentation

One CLI to spin up Kubernetes clusters and run them with GitOps — the same workflow from your laptop to production.
Get Started View on GitHub

Why KSail?

Section titled “Why KSail?”

Standing up Kubernetes the real way means juggling kind or k3d, helm, kubectl, a GitOps engine, SOPS, and a pile of glue scripts — and every distribution and environment does it a little differently.

KSail collapses all of that into one binary and one declarative config. The same workflow — init → create → push → reconcile — works across Vanilla, K3s, Talos, VCluster, KWOK, and EKS, and from your laptop to production. No tool sprawl, and no lock-in: KSail generates native kind.yaml, Talos patches, and friends that you can run with or without it.

See It in Action

Section titled “See It in Action”

From nothing to a running Kubernetes cluster, a deployed workload, and a clean teardown — all with ksail:

Key Features

Section titled “Key Features”

One Binary

Embeds cluster provisioning, GitOps engines, and deployment tooling. No tool sprawl.

Simple Clusters

Spin up Vanilla, K3s, Talos, VCluster, or KWOK clusters with one command — EKS scaffolding included. Same workflow across distributions.

Local to Production

The same ksail workflow drives every environment — a config per environment, selected with --config.

GitOps Native

Built-in Flux or ArgoCD. Compile your manifests to an OCI artifact with workload push, then reconcile.

Offline Validation

Validate and security-scan your whole GitOps repo — schema, Flux vars, and posture — with no cluster. An ideal CI gate.

No Lock-In

Uses native configs (kind.yaml, k3d.yaml, Talos patches, vcluster.yaml, kwok/). Run clusters with or without KSail.

Mirror Registries

Avoid rate limits, and store images once. Same mirrors used by different clusters.

Everything as Code

Cluster settings, distribution configs, and workloads in version-controlled files.

Multi-Tenancy

Generate RBAC isolation, GitOps sync resources, and scaffold tenant repositories with ksail tenant create and ksail tenant delete.

Customizable Stack

Select your CNI, CSI, policy engine, cert-manager, and mirror registries.

SOPS Built In

Encrypt, decrypt, and edit secrets with integrated cipher commands.

Backup & Restore

Export cluster resources to a compressed archive and restore to any cluster with provenance labels.

Built-In Diagnostics

Health-scored cluster diagnostics with remediation hints via ksail cluster diagnose.

Web UI & Desktop

Manage clusters visually with ksail open web in the browser or the native desktop app.

Kubernetes Operator

Reconcile Cluster custom resources in-cluster, with an optional OIDC-protected dashboard.

AI Assistant

Interactive chat powered by GitHub Copilot, plus an MCP server for Claude, Cursor, and more.

VS Code Extension

Manage clusters from VS Code via the Kubernetes extension (Cloud Explorer and Cluster Explorer), wizards, and command palette.

Quick Start

Section titled “Quick Start”

Scaffold a project, create a cluster, and deploy a workload — then follow the full Quickstart and Deliver with GitOps tutorials.

ksail cluster init scaffolds ksail.yaml and kind.yaml, cat shows the minimal declarative config, and re-running with --distribution K3s switches the distribution
Terminal window
# 1. Initialize a new project (pick any distribution)
ksail cluster init --name my-cluster --distribution Vanilla


# 2. Create and start the cluster
ksail cluster create


# 3. Add manifests under k8s/, then deploy
ksail workload apply -k ./k8s


# 4. Open K9s to explore
ksail cluster connect

Prerequisites: KSail runs on Linux, macOS, and Windows (WSL2). Local clusters need Docker; the Kubernetes (Nested) provider runs inside an existing cluster instead. See the Support Matrix for every distribution × provider combination.

How It Works

Section titled “How It Works”
flowchart TD
    Dev["🧑‍💻 Developer"]

    Dev -->|"edits"| Project
    Dev -->|"runs"| KSail

    subgraph Project ["📁 Project Repository"]
        Config["ksail.yaml"] ~~~ DistConfig["kind.yaml · k3d.yaml<br/>vcluster.yaml"] ~~~ Manifests["k8s/ manifests"]
    end

    KSail -->|"scaffolds & reads"| Project
    KSail -->|"provisions & operates"| Cluster

    subgraph KSail ["🛥️ KSail — One Binary"]
        CLI["CLI Commands"] ~~~ Tools["Kind · K3d · Talos · vCluster<br/>Flux · ArgoCD · SOPS<br/>Helm · Kustomize"]
    end

    subgraph Cluster ["☸️ Kubernetes Cluster"]
        Infra["CNI · CSI · Metrics<br/>Cert-Manager · Policy Engine"] ~~~ Workloads["Your Workloads ✅"]
    end

    Manifests -.->|"GitOps sync"| Workloads

    style Dev fill:#f59e0b,stroke:#d97706,color:#000
    style Project fill:#7c3aed22,stroke:#7c3aed
    style KSail fill:#10b98122,stroke:#10b981
    style Cluster fill:#3b82f622,stroke:#3b82f6
    style CLI fill:#10b981,stroke:#059669,color:#000
    style Tools fill:#065f46,stroke:#10b981,color:#fff
    style Infra fill:#1e40af,stroke:#3b82f6,color:#fff
    style Workloads fill:#166534,stroke:#22c55e,color:#fff
    style Config fill:#5b21b6,stroke:#7c3aed,color:#fff
    style DistConfig fill:#5b21b6,stroke:#7c3aed,color:#fff
    style Manifests fill:#5b21b6,stroke:#7c3aed,color:#fff

Where to next

Section titled “Where to next”

Quickstart

Zero to a running cluster with a workload in ~10 minutes. Start here →

Deliver with GitOps

The recommended workflow: package manifests as an OCI artifact and reconcile. Learn more →

Choose your setup

Pick the right distribution and provider for your goal. Compare →

Guides

Task-focused how-tos: registries, secrets, tenants, CI/CD, and more. Browse →

Concepts

How KSail works, the architecture, and the recommended project structure. Understand →

Configuration

The complete ksail.yaml reference and configuration precedence. Reference →