Installation

This guide covers installing Kubently in various environments, from local development to production clusters.

Prerequisites

• Kubernetes cluster (1.28+) or Kind for local testing
• kubectl configured
• Helm 3.x installed (required for Helm deployment)
• At least one LLM API key (Google, Anthropic, OpenAI, or any LLMFactory-supported provider)
• Node.js 18+ (if installing CLI from source)

Installation Methods

Method 1: kubently install (Recommended)

The CLI automates the entire flow below — namespace, secrets, Helm install from the published chart repo, executor registration, and CLI configuration — and drops you into a debug chat:

npm install -g @kubently/cli
kubently install

See the Quick Start Guide for flags and details. The methods below are for when you want manual control (production values, GitOps, custom secrets management).

Method 2: Helm Chart (Manual)

1. Create Namespace and Secrets

First, create the namespace and necessary secrets for LLM API keys and Redis authentication.

# Create namespace
kubectl create namespace kubently

# 1. Create LLM API keys secret (name must be kubently-llm-secrets)
# Supports any LLMFactory-compatible provider. Set at least one.
kubectl create secret generic kubently-llm-secrets \
  --from-literal=ANTHROPIC_API_KEY=your-anthropic-key \
  --namespace kubently

# 2. Create client API keys secret (authenticates CLI/agents to the API;
#    the `keys` field holds newline-separated keys)
kubectl create secret generic kubently-api-keys \
  --from-literal=keys="$(openssl rand -hex 24)" \
  --namespace kubently

# 3. Create Redis password secret (Recommended)
kubectl create secret generic kubently-redis-password \
  --from-literal=password="$(openssl rand -base64 32)" \
  --namespace kubently

2. Configure Helm Values

Create a values.yaml file to configure your deployment. Here is a minimal example:

# values.yaml
api:
  # Configure your preferred LLM provider
  env:
    LLM_PROVIDER: "anthropic-claude" # or "openai", "google-gemini"
    LOG_LEVEL: "INFO"

  # Reference the secret created above
  existingSecret: "kubently-api-keys"

redis:
  enabled: true
  auth:
    enabled: true
    existingSecret: "kubently-redis-password"

executor:
  enabled: true
  # REQUIRED: Unique identifier for this cluster
  clusterId: "my-cluster"
  # REQUIRED: URL where executor sends command results
  # Use internal service name for same-cluster deployment
  apiUrl: "http://kubently-api:8080"
  # REQUIRED: Authentication token (set via --set or existingSecret)
  # Generate with: openssl rand -hex 32
  token: ""  # Set via --set executor.token=<token>
  security:
    mode: "readOnly" # Options: readOnly, extendedReadOnly, fullAccess

3. Install with Helm

Deploy Kubently from the published chart repository:

# Add the Kubently chart repo
helm repo add kubently https://kubently.github.io/kubently
helm repo update

# Generate executor token
export EXECUTOR_TOKEN=$(openssl rand -hex 32)

# Install the chart
helm install kubently kubently/kubently \
  --namespace kubently \
  --values values.yaml \
  --set executor.token="${EXECUTOR_TOKEN}"

Method 3: Kubernetes Manifests (Generated)

If you prefer using raw Kubernetes manifests (YAML files) instead of Helm, you can generate them from the Helm chart.

# Clone the repository (for chart source), or use `--repo https://kubently.github.io/kubently kubently`
git clone https://github.com/kubently/kubently.git
cd kubently

# Generate manifests
helm template kubently ./deployment/helm/kubently \
  --namespace kubently \
  --values values.yaml \
  > kubently-manifests.yaml

# Apply to cluster
kubectl create namespace kubently
kubectl apply -f kubently-manifests.yaml

Method 4: Kind Cluster (Local Testing)

For local development and testing, use Kind (Kubernetes in Docker). The easiest path is the installer — it works on Kind out of the box:

kind create cluster --name kubently
kubently install

Or manually, following Method 2 with --set executor.clusterId=kind-local.

Method 5: Docker Compose (Development)

Ideal for purely local development without a full Kubernetes cluster.

# Clone and navigate to the project
git clone https://github.com/kubently/kubently.git
cd kubently

# Create a .env file with your API keys
echo "ANTHROPIC_API_KEY=your-key" > .env

# Start with Docker Compose
docker-compose -f deployment/docker-compose.yaml up -d

# Verify services are running
docker-compose -f deployment/docker-compose.yaml ps

CLI Installation

The Kubently CLI provides an interactive terminal interface for debugging.

Install from NPM (Recommended)

npm i -g @kubently/cli

Or using npx (no installation required):

npx @kubently/cli

Install from Source

If you want to contribute or use the latest development version:

# Clone the repository
git clone https://github.com/kubently/kubently.git
cd kubently/kubently-cli/nodejs

# Install dependencies and build
npm install
npm run build

# Link globally
npm link

Configuration

Environment Variables

These variables are configured in your values.yaml under api.env or passed to the container directly.

Executor Configuration

The Executor runs within the cluster to execute commands. Configure these in values.yaml under executor.

LLM Providers

Kubently supports multiple LLM providers via the cnoe_agent_utils LLMFactory.

You must provide at least one API key via Kubernetes Secrets.

Custom OpenAI-Compatible Endpoints

When using LLM_PROVIDER=openai, you can configure a custom OpenAI-compatible API endpoint. This allows you to use any provider that implements the OpenAI API specification (e.g., Azure OpenAI, local LLM servers, vLLM, Ollama with OpenAI compatibility, etc.).

Example: Using Azure OpenAI

api:
  env:
    LLM_PROVIDER: "openai"
    OPENAI_ENDPOINT: "https://your-instance.openai.azure.com/"
    OPENAI_MODEL_NAME: "gpt-4o"
# OPENAI_API_KEY goes in the kubently-llm-secrets secret (see step 1 above)

Example: Using a local LLM server (vLLM, Ollama OpenAI-compatible)

api:
  env:
    LLM_PROVIDER: "openai"
    OPENAI_ENDPOINT: "http://localhost:8000/v1"
    OPENAI_MODEL_NAME: "llama3"
    OPENAI_API_KEY: "not-needed"  # Some local servers don't require a key

Example: Using any OpenAI-spec compatible provider

api:
  env:
    LLM_PROVIDER: "openai"
    OPENAI_ENDPOINT: "https://api.your-provider.com/v1"
    OPENAI_MODEL_NAME: "your-model-name"
# OPENAI_API_KEY goes in the kubently-llm-secrets secret (see step 1 above)

Verification

Test the Installation

Using the CLI

# Initialize configuration
kubently init

# Start debugging
kubently debug

Health Checks

# Check API health (requires port-forward)
curl http://localhost:8080/health

# Check executor logs
kubectl logs -l app=kubently-executor -n kubently

# Check Redis connection
kubectl logs -l app=kubently-api -n kubently | grep -i redis

Troubleshooting

Common Issues

Executor Not Connecting

# Check executor logs
kubectl logs -l app=kubently-executor -n kubently

# Verify network connectivity
kubectl exec -it deploy/kubently-executor -n kubently -- \
  curl -v http://kubently-api:8080/health

Redis Connection Issues

# Check Redis status
kubectl get pods -l app=redis -n kubently

# Test Redis connectivity
kubectl exec -it deploy/kubently-api -n kubently -- \
  redis-cli -h redis ping

Security Considerations

1. API Keys: Use Kubernetes Secrets for all sensitive keys.
2. Executor Tokens: Managed via Secrets; rotate if compromised.
3. Network Security: Keep ingress internal or behind VPN/Authentication until OAuth is configured.
4. RBAC: The Helm chart allows defining custom executor.rbacRules.
5. Command Whitelisting: Use readOnly mode for lowest privilege.

Next Steps

• Quick Start Guide - Learn basic usage
• API Reference - Explore the full API
• Architecture - Understand the system design
• Security Guide - Security best practices