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 Local Clusters)

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
Docker	✅ (Kind)	✅ (K3d)	✅	✅ (Vind)
Hetzner	—	—	✅	—
Omni	—	—	✅	—

Note

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.cluster.omni.serviceAccountKeyEnvVar), and an Omni API endpoint configured via spec.cluster.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.0+ installed, you can install KSail directly from source:

go install github.com/devantler-tech/ksail/v5@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, so you don’t need to install them separately:

• kubectl — Kubernetes command-line tool
• helm — Kubernetes package manager
• kind — Kubernetes in Docker (for Vanilla distribution)
• k3d — K3s in Docker (for K3s distribution)
• flux — GitOps toolkit (optional)
• argocd — Declarative GitOps (optional)
• sops — Secret encryption (optional)

All these tools are available through KSail’s unified CLI interface.

Optional: GitHub Copilot CLI (for AI Chat)

To use the ksail chat AI assistant feature, you need the GitHub Copilot CLI:

1. Install Copilot CLI: Follow the Copilot CLI installation guide
2. Authenticate: Run copilot auth login to authenticate with your GitHub account
3. Set path (if needed): Set COPILOT_CLI_PATH environment variable if the CLI is not in your PATH

Note

GitHub Copilot requires an active subscription. The ksail chat command is optional and 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”
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)

Extension Features

The extension provides:

• Cluster sidebar with status indicators and context menus
• Interactive wizards for cluster init and create
• Command palette integration for all cluster operations
• Keyboard shortcuts for common actions
• MCP server integration for AI assistants

See the Features - VSCode Extension section for detailed capabilities.

Extension Settings

Configure the extension in VSCode settings (Cmd+, / Ctrl+,):

Setting	Description	Default
ksail.binaryPath	Path to ksail binary	ksail

Verification

After installation, verify that KSail is installed correctly:

ksail --version

You should see version information displayed. To see all available commands:

ksail --help

Next Steps

• Read the Features overview to understand what KSail can do
• Follow the Configuration guide to set up your first cluster
• Explore Use Cases for common workflows
• Check the Support Matrix for detailed platform compatibility