Skip to main content
The HUD is a floating, dev-only overlay that streams your agent’s execution live — steps, tool calls, tokens, and cost — on top of your running app. It’s the same telemetry Foglamp already collects, surfaced locally as you develop, so you watch the tool cascade unfold (including a tool flashing red and recovering) without leaving your app.
The HUD reuses your existing instrumentation — it does not need an API key. With hud: true and no apiKey, traces stream to the overlay but aren’t sent to ingest. Already have a key? Both happen at once.

​
Requirements

  • A React app (the overlay is a React component). No other dependencies — the pill↔panel morph runs on a tiny vendored spring, so there’s nothing to install beyond foglamp.
  • A server on a Node runtime — the overlay connects to a localhost Server-Sent-Events broker that foglamp({ hud: true }) starts in-process. Not edge, not serverless (see Caveats).

​
1. Install

If you already use Foglamp, you have everything. Otherwise: 
npm i foglamp

​
2. Turn the HUD on (server)

Pass hud: true where you create the collector. This starts the in-process localhost broker. 
import { foglamp } from "foglamp";

const fog = foglamp({ hud: true });
That’s the first line. Everything else — fog.integration(...) on your generateText / streamText calls — is unchanged; the HUD rides the telemetry you already emit.

​
3. Drop in the overlay (client)

Render <FoglampHUD /> once near the root of your client app — e.g. your root layout or App. It mounts into a Shadow DOM (its styles can’t collide with yours) and is inert unless the local broker is running, so it’s safe to leave in. 
import { FoglampHUD } from "foglamp/hud";

export default function RootLayout({ children }) {
  return (
    <>
      {children}
      <FoglampHUD />
    </>
  );
}
That’s the second line. Run your app, trigger an AI flow, and watch it stream.

​
<FoglampHUD /> props

PropTypeDefaultDescription
portnumber8517Broker port. Must match foglamp({ hudPort }) if you changed it.
urlstring—Full SSE endpoint (absolute URL or same-origin path like /hud/events). Overrides port / the 127.0.0.1 default — for reaching the broker through a proxy on the page’s own origin (e.g. a hosted demo).
defaultOpenbooleanfalseStart expanded instead of as the collapsed pill.
theme"light" | "dark" | "system""system"Color theme. "system" follows your app’s .dark class / OS.
redactbooleanfalseMask prompt / response / tool payloads on screen. Turn on before recording or screen-sharing.

​
Server options

Two fields on foglamp(config) control the broker — see Configuration for the full table.
OptionTypeDefaultDescription
hudbooleanfalseStart the local HUD broker. Also enableable via FOGLAMP_HUD=1.
hudPortnumber8517Port for the in-process SSE broker. Also FOGLAMP_HUD_PORT.
The client port and the server hudPort must agree. If you run more than one HUD-enabled process locally (e.g. a dashboard plus a worker), give each its own port and point its <FoglampHUD port={…} /> at it.

​
Recording a demo

Set redact before you record or screen-share — it masks every prompt, completion, and tool payload while keeping the timing, token, and cost view intact. 
<FoglampHUD redact />

​
Caveats

The HUD is dev / localhost only. hud: true is ignored in production, on edge, and on serverless runtimes — the in-process broker needs a long-lived Node process. Your normal ingest path is unaffected; only the overlay is gated.
  • Node runtime, not edge. The broker is a localhost node:http SSE server. On Next.js, the route/handler that constructs foglamp({ hud: true }) must run on the Node runtime (the default) — not export const runtime = "edge".
  • No production cost. The HUD’s server code (broker + live pricing) is code-split and lazy-loaded; it never enters your edge/browser bundle. The core foglamp entry stays React-free and HTTP-free.
  • Safe to commit. <FoglampHUD /> does nothing unless a broker is running, so leaving both lines in is harmless — but gate hud: true to dev if you want to be explicit: 
    const fog = foglamp({ hud: process.env.NODE_ENV !== "production" });