Installation

Prerequisites

System Requirements

KSail works on all major operating systems and modern CPU architectures:

| OS | Architecture | | -------------------- | --------------- | | 🐧 Linux | amd64 and arm64 | |  macOS | arm64 | | ⊞ Windows (native untested; WSL2 recommended) | amd64 and arm64 |

Docker (Required for the Docker Provider)

Docker is required to create local clusters using the Docker provider. Install Docker Desktop or Docker Engine and ensure docker ps works.

• Install Docker Desktop
• Install Docker Engine

After installation, verify Docker is running:

docker ps

Provider Support

The supported Kubernetes distributions (x-axis) run on different infrastructure providers (y-axis). You need to have access to at least one provider for your chosen distribution.

| Provider | Vanilla | K3s | Talos | VCluster | KWOK | | ---------- | --------- | -------- | ----- | ---------- | ------------ | | Docker | ✅ (Kind) | ✅ (K3d) | ✅ | ✅ (Vind) | ✅ (kwokctl) | | Kubernetes | ✅ | ✅ | ✅ | ✅ | ✅ | | Hetzner | — | — | ✅ | — | — | | Omni | — | — | ✅ | — | — |

Note

The Kubernetes provider runs nested clusters as pods inside an existing host cluster — no Docker required on the host. See Kubernetes Provider for setup details. Talos on Hetzner requires a Hetzner Cloud account and API token (HCLOUD_TOKEN). Talos on Omni requires a Sidero Omni account, a service account key provided via environment variable (defaults to OMNI_SERVICE_ACCOUNT_KEY, configurable via spec.provider.omni.serviceAccountKeyEnvVar), and an Omni API endpoint configured via spec.provider.omni.endpoint in ksail.yaml. See the Support Matrix for more details.

Installation Methods

Homebrew

Homebrew (macOS/Linux)

The easiest way to install KSail on macOS or Linux:

brew install --cask devantler-tech/tap/ksail

This installs the latest stable release and makes ksail available in your PATH.

Go Install

Go Install

If you have Go 1.26.1+ installed, you can build and install KSail via go install:

go install github.com/devantler-tech/ksail/v7@latest

This builds and installs the ksail binary to $GOPATH/bin (typically ~/go/bin). Ensure this directory is in your PATH.

Binary Download

Binary Download

Download pre-built binaries from the GitHub Releases page:

1. Navigate to the latest release
2. Download the appropriate binary for your OS and architecture
3. Extract the archive
4. Move the ksail binary to a directory in your PATH (e.g., /usr/local/bin)
5. Make it executable (Linux/macOS): chmod +x ksail

From Source

Build from Source

Clone the repository and build the binary:

git clone https://github.com/devantler-tech/ksail.git
cd ksail
go build -o ksail

The ksail binary will be created in the current directory. Move it to a directory in your PATH if desired.

Embedded Tools

KSail embeds common Kubernetes tools as Go libraries — including kubectl, helm, kind (Vanilla), k3d (K3s), vcluster/Vind (VCluster), flux, argocd, sops, and others — so no separate installation is needed. All tools are accessible through KSail's unified CLI.

Optional: GitHub Copilot CLI (for AI Chat)

Install the GitHub Copilot CLI and run copilot auth login. Set COPILOT_CLI_PATH if the CLI is not in your PATH.

Note

An active GitHub Copilot subscription is required. All other KSail features work without it.

VSCode Extension

For Visual Studio Code users, install the KSail extension to manage clusters directly from your editor.

Marketplace

Install from Marketplace

1. Open VSCode
2. Press Cmd+Shift+X (macOS) or Ctrl+Shift+X (Windows/Linux) to open Extensions view
3. Search for "KSail" — or type @mcp to filter MCP-compatible extensions and find KSail there
4. Click Install on the extension by devantler

Marketplace Link: KSail - Visual Studio Marketplace

VSIX File

Install from VSIX

1. Download the latest .vsix file from GitHub Releases
2. Open VSCode
3. Press Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux)
4. Type Extensions: Install from VSIX...
5. Select the downloaded .vsix file

Extension Prerequisites

• KSail CLI installed and available in PATH (see installation methods above)
• Docker running (for cluster operations)
• K9s (optional, for cluster connection via Connect to Cluster command)

See the VSCode Extension guide for detailed capabilities, commands, and settings.

Verification

ksail --version   # show version
ksail --help      # show all commands