Architecture

Headlamp has three runtime layers that compose differently depending on deployment mode.

headlamp-server¶

Go

The central binary. Reads kubeconfigs, sets up per-cluster reverse proxies, serves the SPA, discovers and serves plugin bundles, handles WebSocket multiplexing, and (when --enable-helm is set) runs the Helm API and service proxy.

Frontend SPA¶

TypeScript / React

Served by the backend as static assets, runs entirely in the browser. MUI components, Redux state, React Router.

Loads plugin bundles at runtime and executes them in the same JS context.

Communicates with the cluster exclusively through the backend proxy.

Desktop App¶

Electron

Thin Electron shell that embeds headlamp-server as a child process and opens a BrowserWindow pointing to it.

• Entry point: app/electron/main.ts.

Enables plugin management from Artifact Hub directly from the desktop.

Request Lifecycle¶

Every user action in the UI travels the same path:

Browser / React →
  headlamp-server:4466 → 
    Cluster proxy → 
      kube-apiserver

For requests that target an in-cluster service (via /serviceproxy):

Browser →
  headlamp-server/serviceproxy →
    K8s Service →
      Helm repo / catalog

WebSocket Multiplexing¶

Browsers cap concurrent WebSocket connections at approximately 6.

Headlamp solves this with a multiplexer: a single WebSocket from the browser to headlamp-server, which then fans out to many Watch connections against the Kubernetes API servers. This is what enables real-time resource updates across dozens of resource types simultaneously without hitting the browser limit.

Plugin Loading¶

On startup, headlamp-server scans its plugins directory (default: ~/.config/Headlamp/plugins on Linux/Mac, or the path set by --plugins-dir).

Each subdirectory that contains a main.js is treated as a plugin and made available at /plugins/<name>/main.js. The frontend fetches each bundle, executes it, and the plugin registers its capabilities via the registry API.

There is no sandboxing: plugins run in the full app context.