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

Each Kubernetes distribution runs on one or more infrastructure providers (Docker, Kubernetes, Hetzner, Omni, AWS), and you need access to at least one provider for your chosen distribution. See the Support Matrix for the full distribution × provider compatibility table and per-provider requirements.

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.

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.

Shell Installer

Shell Installer (Linux/macOS)

Install the latest release archive with checksum verification:

curl -fsSL https://github.com/devantler-tech/ksail/releases/latest/download/install.sh | sh

If Go is installed, the script uses $GOPATH/bin; otherwise it uses ~/.local/bin. Set KSAIL_INSTALL_DIR to choose another destination. To install a specific release, set KSAIL_VERSION to its v-prefixed tag (for example, v7.180.5).

Note

Versioned installation through go install is not supported. Go ignores the main-module dependency overrides that KSail currently needs for upstream compatibility and security fixes. To compile from source, use the From Source method below so those reviewed overrides remain active.

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 with its reviewed module graph:

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: AI provider credentials (for AI Chat)

The AI Chat Assistant works with OpenAI, Anthropic, Google Gemini, Azure OpenAI, OpenRouter, Ollama, any OpenAI-compatible endpoint, or GitHub Copilot. API-provider users set their own model and API key; no Copilot subscription is required.

Note

GitHub Copilot remains the default for compatibility and requires Copilot access. Choose another provider to use your existing API account or a local model instead.

For Copilot, run copilot auth login or configure token authentication. See AI Chat Assistant for every provider path.

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