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

> Watch your agent run live on top of your app with foglamp/hud.

The HUD is a floating overlay for development. It streams your agent's
execution live on top of your running app: steps, tool calls, tokens, and cost.
It uses the same telemetry Foglamp already collects, so you watch your tools
run (and fail, and recover) without leaving your app.

<Note>
  The HUD does not need an API key. With `hud: true` and no `apiKey`, traces
  stream to the overlay but aren't sent to the backend. If you have a key, both
  happen at once.
</Note>

## What you need

* A React app (the overlay is a React component). Nothing to install beyond
  `foglamp`.
* A server running on Node. The overlay connects to a small localhost event
  server that `foglamp({ hud: true })` starts inside your process. It does not
  work on edge or 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:

```ts theme={null}
import { foglamp } from "foglamp";

const fog = foglamp({ hud: true });
```

That's the first line. Everything else, like `fog.integration(...)` on your
calls, stays the same. The HUD uses the telemetry you already send.

## 3. Drop in the overlay (client)

Render `<FoglampHUD />` once near the root of your client app, for example in
your root layout. Its styles are isolated from yours, and it does nothing
unless the local event server 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`     | Event server port. Must match `foglamp({ hudPort })` if you changed it.                                                                       |
| `url`         | string                          | none       | Full event endpoint (absolute URL or same-origin path like `/hud/events`). Overrides `port`. Useful when reaching the server through a proxy. |
| `defaultOpen` | boolean                         | `false`    | Start expanded instead of as a collapsed pill.                                                                                                |
| `theme`       | `"light" \| "dark" \| "system"` | `"system"` | Color theme. `"system"` follows your app's `.dark` class or the OS.                                                                           |
| `redact`      | boolean                         | `false`    | Hide prompt, response, and tool payloads on screen. Turn on before recording or screen sharing.                                               |

## Server options

Two fields on `foglamp(config)` control the event server. See
[Configuration](/sdk/configuration) for the full table.

| Option    | Type    | Default | Description                                                             |
| --------- | ------- | ------- | ----------------------------------------------------------------------- |
| `hud`     | boolean | `false` | Start the local HUD event server. Can also be set with `FOGLAMP_HUD=1`. |
| `hudPort` | number  | `8517`  | Port for the event server. Also `FOGLAMP_HUD_PORT`.                     |

<Note>
  The client `port` and the server `hudPort` must match. If you run more than
  one HUD-enabled process locally, 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 hides every prompt,
response, and tool payload while keeping the timing, token, and cost view:

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

## Caveats

<Warning>
  The HUD is for local development only. `hud: true` is ignored in production
  and on edge or serverless runtimes, because the event server needs a
  long-lived Node process. Your normal telemetry is unaffected; only the
  overlay is turned off.
</Warning>

* **Node runtime, not edge.** On Next.js, the route or handler that creates
  `foglamp({ hud: true })` must run on the Node runtime (the default), not
  `export const runtime = "edge"`.
* **No production cost.** The HUD's server code is loaded lazily and never
  enters your edge or browser bundle. The core `foglamp` entry stays free of
  React and HTTP code.
* **Safe to commit.** `<FoglampHUD />` does nothing unless the event server is
  running, so leaving both lines in is harmless. To be explicit, gate it to
  dev:

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