AI Chat Assistant

The AI Chat Assistant provides an interactive interface for cluster configuration, troubleshooting, and learning. It understands KSail’s CLI and configuration schemas, can execute commands with your approval, and works with GitHub Copilot or an API provider you already use.

Prerequisites

Choose one provider path:

• GitHub Copilot (the backward-compatible default): authenticate with copilot auth login, KSAIL_COPILOT_TOKEN, or COPILOT_TOKEN. This path requires Copilot access.
• Hosted API provider: select OpenAI, Anthropic, Google Gemini, Azure OpenAI, or OpenRouter; set a model and the provider’s API-key environment variable. No Copilot subscription or login is used.
• Local/custom endpoint: select Ollama or openai-compatible, set a model, and provide a base URL for a custom endpoint. A key is optional for these two provider types.

KSail embeds the shared chat runtime. COPILOT_CLI_PATH is only an optional override for that runtime; API-provider users do not authenticate to GitHub Copilot.

Starting a Chat Session

ksail open chat

This opens an interactive TUI (Terminal User Interface) with markdown rendering, syntax highlighting, and conversation history.

Command Options

Flag	Description	Default
--provider	copilot, openai, anthropic, gemini, azure-openai, openrouter, ollama, or openai-compatible	copilot
-m, --model	Model or Azure deployment name; required for non-Copilot providers	Copilot default
--base-url	API endpoint override; required for Azure and custom OpenAI-compatible providers	Provider default
--api-key-env	Environment variable containing the provider key	KSAIL_AI_API_KEY, then provider default
--wire-api	OpenAI-compatible format: completions or responses	completions
--azure-api-version	Azure OpenAI API version override	Runtime default
-r, --reasoning-effort	Reasoning effort level for supported models (low, medium, high)	Model default
-s, --streaming	Enable streaming responses	true
-t, --timeout	Response timeout duration	5m0s
--tui	Use interactive TUI mode with markdown rendering	true

Examples:

# Use a specific model with high reasoning effort
ksail open chat --model gpt-5 --reasoning-effort high

# Use OpenAI's Responses API with your OpenAI key
OPENAI_API_KEY=... ksail open chat --provider openai --model gpt-5 --wire-api responses

# Use Anthropic directly, without a Copilot subscription
ANTHROPIC_API_KEY=... ksail open chat --provider anthropic --model claude-sonnet-4-6

# Use Gemini's OpenAI-compatible endpoint
GEMINI_API_KEY=... ksail open chat --provider gemini --model gemini-2.5-pro

# Use a keyless local Ollama model
ksail open chat --provider ollama --model qwen3:8b

# Use any other OpenAI-compatible endpoint and a custom key variable
TEAM_AI_KEY=... ksail open chat --provider openai-compatible --model team-model \
  --base-url https://ai.example.com/v1 --api-key-env TEAM_AI_KEY

# Let Copilot choose the model
ksail open chat --model auto --timeout 10m

Authentication

API providers (no Copilot subscription)

The same provider contract is available in ksail open chat, ksail open web, and the desktop app. The CLI reads flags and ksail.yaml; web and desktop read Settings → Editor & AI. API keys resolve in this order:

1. The variable named by apiKeyEnvVar / --api-key-env, when explicitly configured. If it is unset, KSail fails closed and does not fall back.
2. KSAIL_AI_API_KEY, including a key entered under Settings → Credentials → AI providers.
3. The provider’s conventional variable:

Provider	Default endpoint	Conventional key variable
OpenAI	https://api.openai.com/v1	OPENAI_API_KEY
Anthropic	https://api.anthropic.com	ANTHROPIC_API_KEY
Google Gemini	https://generativelanguage.googleapis.com/v1beta/openai	GEMINI_API_KEY, then GOOGLE_API_KEY
Azure OpenAI	User-supplied resource host	AZURE_OPENAI_API_KEY
OpenRouter	https://openrouter.ai/api/v1	OPENROUTER_API_KEY
Ollama	http://localhost:11434/v1	Optional
OpenAI-compatible	User-supplied	Optional

The key itself never belongs in ksail.yaml. The local Settings UI stores it in the operating system’s secure store when available and returns only its presence over the Settings API.

Anthropic uses the runtime’s native Anthropic wire format. Gemini, OpenRouter, Ollama, and custom endpoints use their OpenAI-compatible surfaces; that custom option also covers compatible services such as AWS Bedrock, xAI, Groq, Mistral, and DeepSeek when supplied with their endpoint and key-variable name. Provider-specific features outside the common chat/tool-calling surface may not be available.

GitHub Copilot

Copilot remains the default for compatibility. Authenticate once with:

copilot auth login

KSail reuses that session for chat, so no token configuration is needed in an interactive terminal.

Token authentication (headless environments)

In non-interactive environments (CI, remote servers, containers), authenticate with a token instead:

• KSAIL_COPILOT_TOKEN - KSail-specific Copilot token (preferred)
• COPILOT_TOKEN - General Copilot token

Note: GITHUB_TOKEN, GH_TOKEN, and COPILOT_GITHUB_TOKEN are intentionally filtered from the runtime. BYOK mode additionally disables logged-in-user discovery and removes Copilot token variables from the child environment, so a provider session cannot silently depend on a Copilot account.

Slash Commands

Type / in the input box to open the command picker — a floating autocomplete popup with arrow-key navigation, Enter to fire (or fill if the command takes an argument), and Tab to fill without firing.

Command	Arguments	Description
/mode	interactive|plan|autopilot	Switch chat mode
/model	model-id (optional)	Switch LLM model — opens the model picker if no ID is given
/new	—	Start a new chat session
/sessions	—	Open session history picker
/help	—	Show keyboard shortcuts and commands
/clear	—	Clear the chat viewport

Commands that accept arguments show an option picker after selection (e.g., /mode lists interactive, plan, autopilot with descriptions).

Copilot supplies a discoverable model catalog for the picker. API providers do not share one common catalog, so use /model <provider-model-id> to switch a BYOK session directly.

Chat Modes

Press Tab to cycle between three modes, or use /mode <interactive|plan|autopilot> to switch directly:

Mode	Icon	Read Tools	Write Tools	Makes Changes	Best For
Interactive	</>	✅ Auto	✅ With approval	Yes (approved)	Cluster operations, deploying workloads, configuration changes
Plan	≡	❌ None	❌ None	No	Learning workflows, reviewing changes
Autopilot	⚡	✅ Auto	✅ Auto (no prompts)	Yes (unattended)	Trusted or repetitive workflows

Advanced Features

Reasoning Effort

Control analysis depth with --reasoning-effort (low, medium, high) or press Ctrl+E in the TUI. Higher effort provides more thorough reasoning for complex problems but takes longer.

Auto Model Selection

On the Copilot provider, use --model auto to let Copilot choose the best available model. API providers require an explicit model.

Quota Tracking

With the Copilot provider, the TUI footer can display premium request quota details. BYOK providers bill through their own accounts and do not show a Copilot quota.

MCP Tool Elicitation

When an MCP tool needs additional input during execution, an inline 📋 Input Requested modal appears (and may include a source suffix) with one or more form fields. Fill in the fields and press Enter to accept, or Esc to decline. Use Tab / Shift+Tab to navigate between fields in multi-field forms.

In non-TUI mode (plain terminal), the same 📋 Input Requested elicitation request is presented as stdin prompts instead of a modal.

Infinite Sessions

Chat sessions support unlimited conversation length through automatic background compaction when the context window nears capacity.

Keyboard Shortcuts

Navigation

• Enter — Send message
• Alt + Enter — New line in input
• ↑/↓ — Navigate command history (when input is empty) or scroll viewport
• PgUp/PgDn — Scroll conversation viewport

Modes & Settings

• Tab — Cycle chat mode (Interactive → Plan → Autopilot → Interactive)
• / — Open command picker (autocomplete for slash commands)
• Ctrl+T — Expand/collapse tool execution details
• Ctrl+O — Change AI model (lazy-loaded picker)
• Ctrl+E — Change reasoning effort level
• Ctrl+H — View session history
• Ctrl+N — Start new chat session

Elicitation Modal

When an MCP tool requests additional input:

• Enter — Accept (submit form values)
• Esc — Decline
• Tab / Shift+Tab — Navigate between fields (multi-field forms)

Permission Prompts

When an operation requires approval, an inline permission modal appears:

• y — Allow this operation once
• a — Allow always (switches to Autopilot mode; operations are auto-approved while Autopilot is enabled)
• n / Esc — Deny

Read and URL operations are auto-approved without a prompt.

Prompt Queue

• Ctrl+Q — Queue current input as a pending prompt (processed after the active response completes)
• Ctrl+X — Delete the most recently added pending prompt (including steering prompts added by pressing Enter while a response is streaming)

Output

• Ctrl+R — Copy latest assistant response to clipboard

Help & Exit

• F1 — Toggle help overlay
• Esc — Close modals or cancel current operation
• Ctrl+C — Force quit

Configuration

Set the provider, model, and reasoning effort in ksail.yaml (flags override these values):

spec:
  chat:
    provider: anthropic
    model: claude-sonnet-4-6
    reasoningEffort: medium

For a custom OpenAI-compatible endpoint:

spec:
  chat:
    provider: openai-compatible
    model: team-model
    baseUrl: https://ai.example.com/v1
    apiKeyEnvVar: TEAM_AI_KEY  # variable name only; never put the key here
    wireApi: responses

For an Azure OpenAI resource, give the resource host with no path, and set the API version:

spec:
  chat:
    provider: azure-openai
    model: my-deployment
    baseUrl: https://my-resource.openai.azure.com
    azureApiVersion: 2024-10-21
    apiKeyEnvVar: AZURE_OPENAI_API_KEY  # variable name only; never put the key here

The same fields are available under Settings → Editor & AI for the web and desktop interfaces.

Session Management

View Past Sessions

Press Ctrl+H to open session history. Navigate with ↑/↓, filter with /, rename with r, delete with d, or select with Enter. Sessions persist in ~/.ksail/chat/sessions/.

Start New Session

Press Ctrl+N to start a fresh conversation. Previous sessions are automatically saved.

Diagnosing a Misbehaving Cluster

Ask natural-language questions like “why is my cluster broken?” and the assistant calls cluster_read → diagnose, surfaces failing pods and NotReady nodes, then explains the root cause and suggests remediation.

You can also run the command directly:

ksail cluster diagnose          # human-readable
ksail cluster diagnose --output json   # machine-readable (healthScore and findings[])

The command works with Vanilla, K3s, Talos, and VCluster, and exits 0 even when failures are reported (non-zero means the Kubernetes API could not be queried — e.g., the cluster is unreachable or credentials lack sufficient permissions).

Troubleshooting

Chat won’t start: For API providers, verify the model, endpoint requirements, and API-key variable. For Copilot, authenticate with copilot auth login or a Copilot token.

Model not available: Copilot users can try auto-selection (--model auto). API-provider users must set --model <provider-model-id> to a model or Azure deployment that provider exposes.

Timeout errors: Increase timeout for complex operations (--timeout 15m).

Authentication errors: Check the selected provider’s key variable. Copilot users can authenticate interactively or set KSAIL_COPILOT_TOKEN / COPILOT_TOKEN; KSail retries transient Copilot authentication failures up to three times.

See Also

• MCP Server — Expose KSail to external AI assistants (Claude Desktop, Cursor, Windsurf, VS Code Copilot) via the Model Context Protocol
• Using KSail with AI Assistants — Step-by-step setup guide for connecting external AI clients