> ## Documentation Index
> Fetch the complete documentation index at: https://docs.foglamp.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Live HUD

> Stream agent execution live onto your app in two lines — foglamp/hud.

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.

<Note>
  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.
</Note>

## 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](#caveats)).

## 1. Install

If you already use Foglamp, you have everything. Otherwise:

<CodeGroup>
  ```bash npm theme={null}
  npm i foglamp
  ```

  ```bash pnpm theme={null}
  pnpm add foglamp
  ```

  ```bash bun theme={null}
  bun add foglamp
  ```

  ```bash yarn theme={null}
  yarn add foglamp
  ```
</CodeGroup>

## 2. Turn the HUD on (server)

Pass `hud: true` where you create the collector. This starts the in-process
localhost broker.

```ts theme={null}
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.

```tsx theme={null}
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

| Prop          | Type                            | Default    | Description                                                                                                                                                                                                  |
| ------------- | ------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `port`        | number                          | `8517`     | Broker port. **Must match** `foglamp({ hudPort })` if you changed it.                                                                                                                                        |
| `url`         | string                          | —          | 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). |
| `defaultOpen` | boolean                         | `false`    | Start expanded instead of as the collapsed pill.                                                                                                                                                             |
| `theme`       | `"light" \| "dark" \| "system"` | `"system"` | Color theme. `"system"` follows your app's `.dark` class / OS.                                                                                                                                               |
| `redact`      | boolean                         | `false`    | Mask 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](/sdk/configuration) for the full table.

| Option    | Type    | Default | Description                                                          |
| --------- | ------- | ------- | -------------------------------------------------------------------- |
| `hud`     | boolean | `false` | Start the local HUD broker. Can also be enabled via `FOGLAMP_HUD=1`. |
| `hudPort` | number  | `8517`  | Port for the in-process SSE broker. Also `FOGLAMP_HUD_PORT`.         |

<Note>
  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.
</Note>

## 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.

```tsx theme={null}
<FoglampHUD redact />
```

## Caveats

<Warning>
  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.
</Warning>

* **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:

  ```ts theme={null}
  const fog = foglamp({ hud: process.env.NODE_ENV !== "production" });
  ```