Web Dashboard¶

The Web Dashboard provides a modern browser-based interface for Kubernetes management with full AI integration.

Overview¶

The Web UI offers:

• Modern Interface: Responsive design with dark/light themes
• Real-time Updates: Stale-first dashboard refresh with background revalidation
• AI Assistant: Integrated chat interface
• GitHub Automation Receiver: Optional webhook endpoint for issue-driven dev/review jobs
• Multi-cluster: Switch between contexts
• Reports: Generate cluster analysis reports

Getting Started¶

Launch Web Mode¶

# Start web server on default port 8080
k13d --web

# Specify custom port
k13d --web --port 3000

# With local authentication
k13d --web --auth-mode local

Access the Dashboard¶

Open your browser to: http://localhost:8080

Interface Layout¶

┌─────────────────────────────────────────────────────────────────┐
│ k13d │ Context: prod │ Namespace: default │ [Settings] [Help]  │
├───────────┬─────────────────────────────────────────────────────┤
│           │                                                     │
│ Resources │  Resource Table                                     │
│ ─────────│                                                     │
│ Pods      │  NAME         READY  STATUS   AGE                  │
│ Services  │  nginx-abc    1/1    Running  2d                   │
│ Deploys   │  api-def      2/2    Running  5d                   │
│ ConfigMaps│                                                     │
│ Secrets   │                                                     │
│ ...       │                                                     │
│           │                                                     │
├───────────┴─────────────────────────────────────────────────────┤
│ AI Assistant                                                     │
│ ───────────────────────────────────────────────────────────────│
│ Ask me anything about your cluster...                           │
│ [Send]                                                           │
└─────────────────────────────────────────────────────────────────┘

Navigation¶

Sidebar¶

Resource Table¶

• Click row to view details
• Search bar for filtering
• Namespace dropdown for switching
• Refresh button for manual refresh
• Freshness badge when cached data is shown first and live data is still revalidating

Jobs and CronJobs¶

The Web UI now shows Job and CronJob timing in more operational detail:

• Jobs show status, start time, duration, source CronJob/manual trigger, and completion progress
• CronJobs show schedule, active/suspended state, next run, last run, and recent execution history
• Detail modal shows timestamps in your configured local/browser timezone
• Runs tab on CronJobs shows recent Jobs with started/finished time, duration, and pod outcome counts
• Security section on pod-backed workloads shows seccomp profile, runAsNonRoot, token mount, host namespace usage, and container privilege settings

When a CronJob does not set .spec.timeZone, k13d still estimates the next run, but it labels that estimate clearly because Kubernetes ultimately follows the controller-manager timezone.

Resource Actions¶

Right-Click Menu¶

Right-click on any resource to see available actions:

Quick Actions¶

AI Assistant¶

Chat Interface¶

1. Type your question in the input field
2. Click "Send" or press Enter
3. View streaming response
4. Approve/reject tool requests

Example Queries¶

"Why is my nginx pod crashing?"
"Scale the api deployment to 5 replicas"
"Show me all pods with high CPU usage"
"Explain this HPA configuration"

Tool Approval¶

When AI needs to execute a command:

┌──────────────────────────────────────┐
│ Tool Approval Required                │
│                                      │
│ kubectl get pods -n production       │
│                                      │
│ [Approve]  [Reject]                  │
└──────────────────────────────────────┘

By default, this modal appears for both read-only and write AI tool actions. You only skip it for read-only commands if you explicitly enable auto-approve in Settings.

Some requests never reach approval. k13d blocks unsupported interactive kubectl flows such as kubectl edit, kubectl port-forward, kubectl attach, kubectl exec -it, plus bash-wrapped kubectl or helm commands.

Features¶

Dark/Light Theme¶

Toggle theme in Settings or click the theme icon in the header.

Real-time Updates¶

Resources update automatically. The dashboard now follows a stale-while-revalidate pattern:

• recent data is reused immediately when you switch resources or reload the page
• live data is fetched in the background and the table updates in place
• the header shows a freshness badge when cached data is being refreshed

Configure refresh interval:

Settings → General → Refresh Interval

Keyboard Shortcuts¶

Settings¶

LLM Configuration¶

Settings → AI → LLM Configuration

The Web UI saves active LLM settings back to config.yaml immediately and can also manage named profiles through Add Model Profile, Use, and Delete.

For agentic AI, k13d is kubectl-first by default. bash and external MCP tools are opt-in via config.yaml:

llm:
  enable_bash_tool: false
  enable_mcp_tools: false

For the full storage model, including how llm, models[], and active_model change, see Model Settings & Storage.

AI Input History¶

The AI input box supports shell-like history recall:

• Up loads the previous submitted prompt
• Down moves forward again
• on a single-line draft, history works even when the cursor is at the end of the line
• in a multi-line draft, history only takes over from the first line on Up and the last line on Down, so normal caret movement still works inside the textarea

The recent prompt history is stored in browser localStorage under k13d_query_history, so it survives reloads in the same browser profile.

MCP Servers¶

Settings → AI → MCP Servers

Manage external MCP servers for extended AI capabilities.

GitHub Issue Automation¶

The Web server can also act as a GitHub webhook receiver for issue-driven automation. This is useful if you want a newly labeled issue to trigger:

• an isolated git worktree
• a development-agent command
• an optional review-agent command
• auto-commit / auto-push
• draft PR creation and issue comment reporting
• GitHub check-run waiting before review/deploy
• branch preview routing through the same Web UI domain

Webhook Endpoint¶

POST /api/github/automation/webhook

Typical public URL:

https://your-domain.example/api/github/automation/webhook

If you already expose k13d directly on 443, GitHub can reach this endpoint without another relay service.

Status Endpoints¶

There is not yet a dedicated GUI page for automation jobs. Today, the operational view is API-based:

Trigger Rules¶

• GitHub issues webhooks start automation jobs, and issue_comment webhooks handle review/merge commands
• Default label gate: codex:auto
• The Codex 개발 요청 GitHub Issue Form collects goal, context, desired behavior, acceptance criteria, validation, and safety confirmation
• Issue authors must be members of the repository owner organization when require_author_org_member is enabled
• Trusted issues can mention organization members when mention_org_members is enabled
• Trusted issues are assigned to the issue author
• Generated PRs request organization members as reviewers
• One issue uses one stable branch, such as codex/issue-123, and reuses the existing open PR on later runs
• If review_command is configured, organization members can comment k13d 코드리뷰 해줘 on the issue to re-run Codex review and post a PR Review
• If allow_issue_merge is enabled, organization members can comment k13d merge 해줘 on the issue to merge the linked PR and close the issue as completed
• GitHub token env vars are stripped from automation command environments and redacted from captured output
• Built-in issue comments and PR review wrappers use Korean by default through review_language: ko
• Supported issue actions: opened, reopened, labeled
• Webhook signatures are verified with X-Hub-Signature-256
• Repositories can be allow-listed in config.yaml

Practical Setup Pattern¶

1. Run k13d Web UI on a reachable HTTPS endpoint.
2. Configure github_automation in config.yaml.
3. Add a GitHub webhook for Issues and Issue comments.
4. Set the same webhook secret in GitHub and in config.yaml.
5. Create a Codex 개발 요청 issue, review it, then label it with codex:auto.

When the job finishes, k13d can comment back on the issue and create a draft PR if a GitHub token is configured.

For author requirements and a recommended issue template, see the GitHub Issue Automation Guide.

Branch Preview URLs¶

If k13d is the only service exposed on your public 443 endpoint, use path-based previews:

https://fingerscore.net/previews/<branch-slug>/

The preview deploy command can start each branch on a different local port and print:

K13D_PREVIEW_TARGET=http://127.0.0.1:18123

k13d stores that target on the automation job and reverse-proxies /previews/<branch-slug>/... to it. The browser app also rewrites its own /api/... calls under the preview path, so the preview talks to the branch instance rather than the main server. After CI and preview deployment succeed, the issue completion comment includes the preview URL as a human verification link.

User Management¶

Settings → Admin → Users

Reports¶

Generate comprehensive cluster reports with selectable sections:

1. Navigate to Reports section
2. Choose which sections to include:
3. Nodes - node readiness, cordon state, pressure warnings, taints, capacity and allocatable values
4. Namespaces - namespace inventory and workload counts
5. Workloads - pods, deployments, services, and images
6. Events - recent warning events
7. Security - built-in security summary
8. Security Full - extended scanner output when available
9. FinOps - heuristic compute-cost analysis and rightsizing guidance
10. Metrics - historical metrics when collection is enabled
11. Optionally include AI analysis
12. Preview inline or download as HTML, CSV, or JSON

The exported report now respects the section selection you make in the modal. FinOps output is request-based and prefers live pod metrics when available, and the node section includes operational checks such as pressure conditions and cordon status.

Custom Resource Detail¶

Click on any Custom Resource to view a rich detail modal:

• Overview tab with auto-detected status, metadata, key fields, spec/status summary, conditions table, labels, and annotations
• YAML tab with full manifest
• Events tab with related Kubernetes events

Pod Actions¶

View Logs¶

1. Click on a pod
2. Select container (if multiple)
3. View streaming logs
4. Options:
5. Previous logs
6. Follow
7. Timestamps
8. Download

Execute Shell¶

1. Click on a pod
2. Click "Exec" or 🖥️ icon
3. Select container
4. Enter commands in terminal

Port Forward¶

1. Click on a pod
2. Click "Port Forward"
3. Configure:
4. Local port
5. Container port
6. Click "Start"
7. Access at localhost:<port>

Deployment Actions¶

Scale¶

1. Select deployment
2. Click "Scale" or use slider
3. Enter replica count
4. Confirm

Restart¶

1. Select deployment
2. Click "Restart"
3. Confirm rollout restart

Rollback¶

1. Select deployment
2. Click "Rollback"
3. Select revision
4. Confirm

Node Actions¶

Cordon/Uncordon¶

1. Select node
2. Click "Cordon" to prevent scheduling
3. Click "Uncordon" to allow scheduling

Drain¶

1. Select node
2. Click "Drain"
3. Configure options:
4. Ignore DaemonSets
5. Delete local data
6. Force
7. Confirm

API Access¶

The Web UI exposes REST APIs:

# Get pods
curl http://localhost:8080/api/k8s/pods

# With authentication
curl -H "Authorization: Bearer $TOKEN" \
     http://localhost:8080/api/k8s/pods

# AI chat
curl -X POST http://localhost:8080/api/chat/agentic \
     -H "Content-Type: application/json" \
     -d '{"message": "list pods"}'

Mobile Support¶

The Web UI is responsive and works on mobile devices:

• Touch-friendly navigation
• Collapsible sidebar and AI panel
• Condensed panel header and filter bar on narrow screens
• Horizontal table scrolling with sticky pagination for resource-heavy views
• Optimized for smaller screens without dropping core dashboard actions

Security¶

Authentication¶

Run the Web UI with local authentication:

k13d --web --auth-mode local

For production, prefer token auth:

k13d --web --auth-mode token

Provider-specific LDAP/OIDC settings are startup-configured in the current build and are not persisted from the Web UI settings page.

HTTPS¶

For production, use a reverse proxy (nginx, traefik) with TLS.

Troubleshooting¶

WebSocket Connection Failed¶

• Check if port is accessible
• Verify no firewall blocking
• Try different browser

Slow Performance¶

• k13d now shows recent cached resource data first and refreshes in the background, so the first paint should feel faster after the initial load
• Reduce refresh interval
• Limit namespace scope
• Use filters to reduce data

AI Not Responding¶

• Check LLM configuration
• Verify API key
• Check network connectivity

Next Steps¶

• TUI Dashboard - Terminal interface
• Keyboard Shortcuts - All shortcuts
• Configuration - Full options