Every context in your kubeconfig on one screen: health, pressure, and the restart counts that explain your 3 a.m.
kubectl tells you what is happening.
Kubernetes Dashboard tells you where it is.
Spotlight tells you why.
We were debugging a production incident at 2 a.m. The pod was crash-looping.
kubectl logsshowed 21,320 restarts. The Dashboard cheerfully reported the pod as "Running". Neither told us why — theOOMKilledline was buried at position 88 of a 200-line dump. That gap, dashboard without diagnosis, is what Spotlight closes.
No SaaS, no vendor lock. Your cluster, your data, your model.
- Multi-cluster, one UI — every context in your kubeconfig, switchable live. No restart.
- Real-time log stream — SSE, multi-pod select, ANSI color preserved, deduplicated, downloadable.
- AI explainer, any model — OpenAI · Anthropic · Bedrock · Gemini · Ollama · 100+ via LiteLLM.
- Keyboard-first —
⌘Kpalette,g d/p/n/e/f/apage jumps. Mouse optional. - Readable in the dark — a full dark theme (token-level, not inverted CSS), because 3 a.m. is the hour this thing gets opened.
- Dense when it needs to be — sortable pod table, three density tiers, a log pane that owns the viewport.
- Pluggable auth — bearer · session · Teleport
tsh· your own plugin, one file. - Type-safe end to end — Pydantic v2 → OpenAPI →
openapi-typescript. The UI cannot drift from the API.
Two processes: the FastAPI backend and the Vue dev server. Ports are never hardcoded — pick what is free on your machine and tell each side about it.
# 1 · backend — pick any free port
cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
python -m app.server --reload --port 8002# 2 · frontend — in a second terminal
cd frontend
pnpm install
pnpm devTell the frontend where the backend is. It proxies /api to VITE_API_PROXY, which defaults to
http://127.0.0.1:8000 — so if you started uvicorn on 8002 (or any other port), set it before
running pnpm dev, or the frontend will silently proxy to a dead port:
# frontend/.env
VITE_API_PROXY=http://127.0.0.1:8002Frontend port: leave VITE_PORT unset and Vite picks a free one, walking up if the default is
busy. It prints the URL it actually bound — open that, don't assume a fixed port.
On macOS, set no_proxy before you start the backend. The Kubernetes Python SDK seeds its
HTTP client from the system proxy settings, so a request to a local cluster at 127.0.0.1
goes through your proxy and comes back as a 500 with an SSL EOF on every call. A local apiserver
address is not in the system's exception list (and k3d writes 0.0.0.0 as the server, which is
not in it either), so the proxy has to be told to skip it:
# backend
no_proxy=127.0.0.1,localhost,0.0.0.0 python -m app.server --reload --port 8002The symptom is a 500 on /api/v1/pods while /api/v1/clusters still answers 200 — the cluster
list comes from the kubeconfig on disk, and everything else goes over the network.
Auth: Teleport, shared token, or direct kubeconfig
Pick one of three modes. All three are real and supported — Teleport is just the one that needs a bastion.
A · Direct kubeconfig (no bastion). Set nothing. Spotlight reads
$KUBECONFIG or ~/.kube/config on the server and talks to the apiserver
directly. The API starts open and logs a startup warning. This is the mode for
a laptop or a single-team internal tool, where everyone sharing the server's
cluster identity is fine.
B · Shared token. Set API_TOKEN (and optionally AUTH_PROVIDER=token).
Callers send Authorization: Bearer <token>; there is no login form to fill
in. The cluster credential is still the server's kubeconfig, so this changes
who may enter, not what they may see.
C · Teleport (real per-user isolation). Set TELEPORT_PROXY,
TELEPORT_AUTH and AUTH_PROVIDER=teleport. Each browser session gets its
own private tsh login state and its own kubeconfig — users see only what
their Teleport role allows. Set TELEPORT_CLUSTER when your proxy hostname is
not the cluster name.
Modes A and B share one Kubernetes identity. If you need "each engineer sees
only their own RBAC scope", that is mode C, or a new AuthPlugin.
Behind a reverse proxy, set TRUSTED_PROXY_IPS to your LB subnet and start
the server with python -m app.server (see Quick start). It is a uvicorn
setting, so the bare uvicorn app.main:app form ignores it — and without it
the login rate limiter sees only the proxy's IP and throttles every user as one
shared bucket.
Writing your own auth plugin? Implement AuthPlugin in
backend/app/infrastructure/auth/plugins/, register it in that package's
REGISTRY, and set AUTH_PROVIDER=<your-plugin-id>. The login form adapts
itself to the plugin's form_fields(). acquire() returns the kubeconfig to
write into the session's private directory; per-session isolation, client
pooling and cleanup are already handled for you.
kubectl |
Dashboard | Lens | Spotlight | |
|---|---|---|---|---|
| Live multi-cluster switch | via kubectx |
manual | yes | yes |
| Real-time multi-pod log stream | -f |
yes | yes | yes, deduplicated |
| AI log explainer | — | — | — | yes, any LLM |
| Pluggable auth | — | — | partial | yes, one file |
| Type-safe API → UI | — | — | — | yes, Pydantic → TS |
Spotlight does not replace
kubectl. It sits on top of it — and gives you the diagnosis.
Pull up to 200 lines from any pod, click Analyze, pick a model:
▸ AI · claude-3-5-sonnet · 1.42s · tokens 412 in / 286 out
Root cause
The pod is being OOMKilled. Container RSS hit the 512 MiB limit at
17:42:08; the kernel sent SIGKILL (exit 137); Kubernetes restarted
the container 21,320 times in the last 5 minutes.
Evidence
L17 "oom score adj = 950"
L23 "memory.peak = 512MiB / limit 512MiB"
L88 "loki-write: signal SIGKILL, exit code 137"
Suggested fix
• Raise memory.limit to 768 MiB in the Helm values, or
• Drop WAL retention from 24h → 6h in the ingester config, or
• Shard the tenant — split by labels across 3 replicas.
Providers live in SQLite (ai_providers) and are managed entirely from Settings → AI. There is no AI_PROVIDER env var — switching models is a UI action, no restart, no rebuild.
Hexagonal. The domain and application layers know nothing about Kubernetes, HTTP, or LLMs; the infrastructure adapters do.
flowchart TB
classDef ui fill:#1A1A24,stroke:#8EC5FF,stroke-width:1.5px,color:#FAFAFA
classDef api fill:#1A1A24,stroke:#EFADF7,stroke-width:1.5px,color:#FAFAFA
classDef app fill:#1A1A24,stroke:#FFD69B,stroke-width:1.5px,color:#FAFAFA
classDef port fill:#0F0E16,stroke:#EFADF7,stroke-width:1px,color:#FAFAFA
classDef dom fill:#0F0E16,stroke:#8EC5FF,stroke-width:1px,color:#FAFAFA
classDef infra fill:#11111A,stroke:#5A5A75,stroke-width:1px,color:#CFCFD8
classDef store fill:#0F0E16,stroke:#FFD69B,stroke-width:1px,color:#FFD69B
subgraph Browser["Browser · Vue 3"]
UI["shadcn-vue · Pinia · Router · Sonner"]:::ui
end
subgraph Edge["Interface · HTTP + SSE"]
API["FastAPI routers · deps · CORS"]:::api
SSE["SSE routes · log streaming"]:::api
end
subgraph App["Application · use cases"]
UC["commands · queries · handlers"]:::app
PK["port: K8s"]:::port
PL["port: LLM"]:::port
end
subgraph Dom["Domain · pure"]
ENT["entities · value objects · services"]:::dom
end
subgraph Infra["Infrastructure · adapters"]
K8S["multi-context k8s pool"]:::infra
LLM["LiteLLM — any provider"]:::infra
DB[("SQLite")]:::store
end
UI <-->|"axios + OpenAPI · type-safe"| API
UI <-->|SSE| SSE
API --> UC
SSE --> UC
UC --> ENT
UC --> PK & PL
PK -. implemented by .-> K8S
PL -. implemented by .-> LLM
K8S --> DB
LLM --> DB
The rule: domain/ and application/ never import kubernetes or litellm. Everything crosses a port declared in application/ports/. To add an auth provider, an LLM, or a log source — implement the matching adapter in infrastructure/ and register it. Nothing else moves.
Stack — backend: FastAPI · Pydantic v2 · kubernetes-python · LiteLLM · SQLAlchemy (async + aiosqlite) · structlog. Frontend: Vue 3 · Vite · Tailwind CSS · shadcn-vue · Pinia · axios. Tests: pytest · Vitest · Playwright · axe-core.
- v2.0 — multi-cluster kubeconfig, SSE log streaming, LiteLLM, UI v6, hexagonal backend
- v2.1 — Helm chart · single-binary mode · SQLite → Postgres
- v2.2 — multi-user session isolation (per-user cluster credentials via a new
AuthPlugin) · audit log UI - v3.0 — plugin SDK · authenticated public read-only share links
Open a Discussion if something matters to you — the roadmap follows what people actually use.
Is it production-ready?
Yes for everything except the AI explainer. v2.0 ships with hexagonal architecture, typed API contracts, SSE log streaming, and a test suite over the critical ports. The AI analyzer is the only feature that reaches an external LLM; the rest runs entirely offline.
How is it different from Lens or k9s?
Lens is a full Kubernetes IDE — excellent for exploring resources, no AI log analysis. k9s is a terminal UI — fast and minimal, no web dashboard. Spotlight is the web dashboard with AI diagnosis in the middle. See Compare.
Can I use my own endpoint?
Yes. Settings → AI → Add provider → custom, then paste the base URL of any OpenAI-compatible endpoint (Ollama, vLLM, LM Studio). The model name comes from the same form. Saved to SQLite, used on the next call — no restart.
Does it store my cluster credentials?
No. Spotlight reads your KUBECONFIG at runtime and never persists cluster credentials. API_TOKEN lives in backend/.env (gitignored). Teleport sessions are per-session and expire.
Is there a Docker image?
Not yet — Helm chart and single-binary mode are on the v2.1 roadmap. For now run the two processes directly, see Quick start.
Contributing
Any-size contribution is welcome — bugs, docs, code, provider adapters.
git clone https://github.com/mcgrapeng/Spotlight.git && cd Spotlight
cd backend && python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt && pytest -q
cd ../frontend && pnpm install
pnpm test # Vitest
pnpm test:e2e # PlaywrightType checking reads /openapi.json from a running backend:
cd frontend && pnpm types:checkPer-package guides: backend/README.md · frontend/README.md
Project layout
Spotlight/
├── backend/ FastAPI · hexagonal architecture
│ ├── app/
│ │ ├── application/ use cases + ports
│ │ ├── domain/ entities · value objects · services
│ │ ├── infrastructure/ adapters: ai, auth, cache, config, k8s, logging, persistence
│ │ ├── interface/ api/ (routers · DTOs) + sse/
│ │ └── main.py
│ ├── tests/ pytest — unit + integration
│ └── requirements.txt
├── frontend/ Vue 3 + Vite + Tailwind + shadcn-vue
│ ├── src/
│ │ ├── components/ ui/, layout/, common/, pod/, dashboard/, log/, ai/
│ │ ├── views/ 9 pages
│ │ ├── stores/ Pinia
│ │ ├── api/ axios + generated OpenAPI types
│ │ └── styles/ design tokens
│ └── package.json
├── assets/ logo lockup, README screenshots
├── LICENSE MIT
└── README.md · README.zh-CN.md
