Install docs

Get Spyglass running

Spyglass ships as a single container (or a single binary). Pick the way that fits you — all three end with the dashboard on http://localhost:8081. No prior Spyglass knowledge needed.

How it works

Spyglass is one process: a web UI baked into a small Go binary that talks to the Kubernetes API. It runs in one of two modes:

remotecluster — talks to a cluster using your local ~/.kube/config. Best for trying it on your laptop (the binary and Docker methods).
incluster — runs as a pod and uses its ServiceAccount. This is what the Helm chart deploys.

Viewing is always free, no key needed. A license key only unlocks changes (create/edit/delete). Grab a free Community key any time from your account — see Apply your key.

Prerequisites

A Kubernetes cluster you can reach. Anything works — a cloud cluster, or local kind/minikube/k3d.
kubectl configured for it. Check with kubectl get nodes — if that lists nodes, you're set.
For the Helm method: Helm 3.8+. For Docker: any recent Docker/Podman.
Optional: metrics-server for CPU/memory graphs. Spyglass degrades gracefully without it.

1 · Run the binary

The fastest way to look at a cluster. One file, no install, uses your kubeconfig.

Download the build for your OS and architecture from the downloads page. Or pull it from the command line (Linux x86-64 shown):

curl -sSLO https://github.com/unishsys/spyglass/releases/download/v0.2.0/spyglass-linux-amd64
curl -sSLO https://github.com/unishsys/spyglass/releases/download/v0.2.0/SHA256SUMS

Verify and make it executable. The checksum step is optional but recommended.

shasum -a 256 -c SHA256SUMS --ignore-missing   # optional integrity check
chmod +x spyglass-linux-amd64

macOS may quarantine the download — clear it with xattr -d com.apple.quarantine spyglass-darwin-*.

Run it against your current kubeconfig context, then open the dashboard.

./spyglass-linux-amd64 remotecluster
# now open http://localhost:8081

In remotecluster mode auth defaults to off (it's bound to localhost). Set AUTH_MODE=token AUTH_TOKEN=… if you expose it.

2 · Run with Docker

Same as the binary, but containerized — mount your kubeconfig read-only and Spyglass uses it.

Run the signed image with your kubeconfig mounted at the location the nonroot user expects:

docker run --rm -p 8081:8081 \
  -v "$HOME/.kube/config:/home/nonroot/.kube/config:ro" \
  ghcr.io/unishsys/spyglass:0.2.0 remotecluster
# open http://localhost:8081

Cluster reachable from the container? If your kubeconfig points at 127.0.0.1 (common with kind/minikube), add --network host (Linux) or use the host gateway so the container can reach the API server.

Verify the image (optional). Images are cosign-signed with GitHub OIDC — no keys to manage:

cosign verify ghcr.io/unishsys/spyglass:0.2.0 \
  --certificate-identity-regexp 'https://github.com/unishsys/.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

3 · Install with Helm

The production path: deploys Spyglass inside the cluster with RBAC and a generated auth token. The chart is an OCI artifact on GHCR.

Install the chart into a spyglass namespace. upgrade --install is idempotent — the same command installs the first time and upgrades after:

helm upgrade --install spyglass oci://ghcr.io/unishsys/charts/spyglass \
  --namespace spyglass --create-namespace \
  --version 0.2.0

Already have a key? Apply it in the same step by adding --set license.key='<YOUR_KEY>' (see Apply your key). --version pins a reproducible install; omit it to take the latest stable.

Read the auth token the chart generated (token auth is the secure default):

kubectl -n spyglass get secret spyglass-secrets \
  -o jsonpath='{.data.AUTH_TOKEN}' | base64 -d ; echo

Open it via a port-forward (or set up an Ingress — see below):

kubectl -n spyglass port-forward svc/spyglass 8081:8081
# open http://localhost:8081 and paste the token

Apply your license key

Spyglass is free to view. To make changes, add a license key: a free Community key (up to 10 nodes) or an Enterprise key (unlimited nodes). Get yours from your account dashboard — it's verified offline, so it works in air-gapped clusters.

Helm

helm upgrade --install spyglass oci://ghcr.io/unishsys/charts/spyglass --reuse-values \
  --namespace spyglass \
  --set license.key='<YOUR_KEY>'

Binary or Docker

Set it as an environment variable:

LICENSE_KEY='<YOUR_KEY>' ./spyglass-linux-amd64 remotecluster
# Docker: add  -e LICENSE_KEY='<YOUR_KEY>'  to the docker run command

Logged-in users get copy-paste commands with the key already filled in on the in-app guide.

Verify it works

Open the dashboard — the license banner should show your tier and node cap, and Create/Edit actions are enabled once a key is applied. From the command line:

curl -s http://localhost:8081/api/v1/license \
  -H "Authorization: Bearer <AUTH_TOKEN>"
# token only needed when AUTH_MODE=token (the Helm default)

Expose it on a hostname (optional)

For a Helm install, turn on the Ingress and TLS instead of port-forwarding:

helm upgrade --install spyglass oci://ghcr.io/unishsys/charts/spyglass --reuse-values \
  --namespace spyglass \
  --set ingress.enabled=true \
  --set ingress.className=nginx \
  --set ingress.host=spyglass.your-domain.com \
  --set ingress.tls.enabled=true \
  --set ingress.tls.secretName=spyglass-tls

Spyglass has cluster-wide access — treat dashboard access as cluster access. Never run AUTH_MODE=none on a shared or exposed cluster, and always serve it over HTTPS.

Troubleshooting

"Binary exits immediately." It needs a mode: run remotecluster (laptop) or incluster (pod).
CPU/memory graphs are blank. Your cluster has no metrics-server. Everything else still works.
Gateways / certificates show "not installed." Those CRDs (Gateway API, cert-manager) aren't present — expected, Spyglass degrades gracefully.
401 from the API. AUTH_MODE=token is on but no token was sent. Read it from the spyglass-secrets Secret (Helm step 2).
Docker can't reach the cluster. Your kubeconfig points at 127.0.0.1; add --network host or use the host gateway.

Need more than the Community node cap? See Enterprise. Prefer to grab a build first? Download Spyglass.