Skip to content

Installation

k13d can be installed in multiple ways depending on your environment and requirements.

Prerequisites

  • Go 1.25+ (for building from source)
  • Kubernetes 1.29+ cluster with a valid kubeconfig
  • kubectl installed and configured

Binary Installation

Build from Source

The recommended way to install k13d is to build from source:

# Clone the repository
git clone https://github.com/cloudbro-kube-ai/k13d.git
cd k13d

# Build the binary
make build

# Or build with Go directly
go build -o k13d ./cmd/kube-ai-dashboard-cli/main.go

# Verify installation
./k13d --version

Cross-Platform Builds

Build binaries for multiple platforms:

# Build for all platforms
make build-all

# Build for specific platforms
make build-linux    # Linux (amd64, arm64, arm)
make build-darwin   # macOS (Intel, Apple Silicon)
make build-windows  # Windows (amd64)

Install to PATH

# Move binary to a directory in your PATH
sudo mv k13d /usr/local/bin/

# Or add to your PATH in ~/.bashrc or ~/.zshrc
export PATH="$PATH:/path/to/k13d"

Docker

Quick Start

docker run -d -p 8080:8080 \
  -v ~/.kube/config:/home/k13d/.kube/config:ro \
  -e K13D_USERNAME=admin \
  -e K13D_PASSWORD=changeme \
  cloudbro-kube-ai/k13d:latest

Docker Compose

For more complex setups, use Docker Compose:

docker-compose.yaml
version: '3.8'
services:
  k13d:
    image: cloudbro-kube-ai/k13d:latest
    ports:
      - "8080:8080"
    volumes:
      - ~/.kube/config:/home/k13d/.kube/config:ro
    environment:
      - K13D_USERNAME=admin
      - K13D_PASSWORD=changeme
      - K13D_LLM_PROVIDER=openai
      - K13D_LLM_API_KEY=${OPENAI_API_KEY}

docker-compose up -d

Kubernetes

Basic Deployment

# Deploy to Kubernetes
kubectl apply -f deploy/kubernetes/deployment.yaml

# Port forward to access locally
kubectl port-forward -n k13d svc/k13d 8080:80

# Open in browser
open http://localhost:8080

Helm Chart

# Add Helm repository
helm repo add k13d https://cloudbro-kube-ai.github.io/k13d

# Install with defaults
helm install k13d k13d/k13d

# Install with custom values
helm install k13d k13d/k13d \
  --set auth.mode=ldap \
  --set llm.provider=ollama

Air-Gapped Installation

For Offline Environments

Use this method when the target environment has no internet access.

On Connected Machine

# Create offline bundle
make bundle-offline

# Transfer to air-gapped machine
scp dist/k13d-offline-bundle-*.tar.gz user@airgapped:~/

On Air-Gapped Machine

# Extract and build
tar -xzvf k13d-offline-bundle-*.tar.gz
cd offline-bundle
make build-offline

# Run with embedded LLM (no API keys needed)
./k13d --embedded-llm -web -port 8080

macOS Gatekeeper

macOS Security Warning

macOS may block the binary with "Apple could not verify k13d is free of malware".

Option 1: Remove Quarantine Attribute

# Remove quarantine and provenance attributes
xattr -d com.apple.quarantine ./k13d
xattr -d com.apple.provenance ./k13d

Option 2: Allow in System Settings

  1. Open System Settings → Privacy & Security
  2. Scroll down to find the blocked app message
  3. Click "Allow Anyway"
  4. Run the binary again and click "Open" when prompted

Verifying Installation

# Check version
./k13d --version

# Run TUI mode (requires valid kubeconfig)
./k13d

# Run web mode with local auth (recommended for desktop use)
./k13d -web -auth-mode local
# Open http://localhost:8080 — Default login: admin / admin

# Run web mode with K8s RBAC auth (for production)
./k13d -web -auth-mode token

# Check embedded LLM status
./k13d --embedded-llm-status

Authentication Modes

When running the web server (-web), choose an authentication mode:

Mode Flag Description
Local -auth-mode local Username/password auth stored in memory. Ideal for local development, desktop use, and standalone deployments. No external auth infrastructure needed.
Token -auth-mode token Kubernetes RBAC token validation via TokenReview API. Best for in-cluster deployments. This is the default.
LDAP -auth-mode ldap Authenticate against an LDAP directory (Active Directory, OpenLDAP).
OIDC -auth-mode oidc SSO via OpenID Connect providers (Google, Okta, Azure AD).
No Auth --no-auth Disables authentication entirely. Not recommended — use only for local testing.

For local/desktop usage, -auth-mode local is the simplest option:

# With default credentials (admin / admin)
./k13d -web -auth-mode local

# With custom credentials
./k13d -web -auth-mode local -admin-user myadmin -admin-password mysecurepassword

# Or via environment variables
export K13D_USERNAME=myadmin
export K13D_PASSWORD=mysecurepassword
./k13d -web -auth-mode local

Next Steps