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

# Extending the Vulpy WebUI with iframes and pages

> Add admin surfaces to the Fox WebUI side panel via VULPY_WEBUI_IFRAMES and serve custom pages under /extensions/ with the WebUI namespace rules.

The Vulpy WebUI is a single manifest entry named `vulpy-commerce` with six built-in features. It is not designed for per-feature toggles. Instead, Vulpy offers two extension points so you can add your own admin surfaces without forking the UI.

<Tip>
  **Ask Fox to scaffold and edit.** Fox works in the same checkout as you and can create feature folders, wire manifests, and update env vars.

  Try prompts like:

  * "Scaffold a new WebUI feature named `vulpy-commerce-order-monitor`."
  * "Add an iframe target for my Grafana dashboard."
  * "Show me the current `VULPY_WEBUI_IFRAMES` value."
</Tip>

## Extension points

1. **Iframe targets via `VULPY_WEBUI_IFRAMES`**: list extra URLs in an environment variable and Fox renders them as additional tabs in the side panel.
2. **Custom pages under `/extensions/`**: drop files into the `pages/` directory inside `extensions/hermes-webui/` and they are served through the `/extensions/` route.

## Namespacing rules

To avoid collisions with Vulpy or other products, prefix anything you add:

* Registry keys: `vulpy-commerce.*`
* CSS classes: `vc-*`
* Data attributes: `data-vc-*`

## How to add an iframe target

<Steps>
  <Step title="Set the environment variable">
    Add `VULPY_WEBUI_IFRAMES` to your environment file, with a comma-separated list of URLs you want to appear as side-panel tabs.
  </Step>

  <Step title="Restart Fox">
    Run `pnpm db:hermes:up` (or `pnpm vulpy hermes up` on a server) so the new variable is picked up by the WebUI container.
  </Step>

  <Step title="Verify in the WebUI">
    Open the WebUI at port `8787`. The new tabs appear in the side panel and load the target pages inside iframes.
  </Step>
</Steps>

<Tip>
  Iframe targets must allow themselves to be framed. Set a permissive `frame-ancestors` CSP directive or match the WebUI origin in your target application.
</Tip>

## Custom pages

Fox and you share the `/app/workspace` directory, which is bind-mounted from your host checkout. Any file you add under `extensions/hermes-webui/pages/` is served live at `/extensions/<filename>`. Use this for bespoke internal admin views, dashboards, or tools that do not fit inside an iframe.

Changes on the host are reflected immediately because the directory is mounted into the running container.

<Warning>
  Do not leak secrets into extension pages. The WebUI is protected by basic authentication, but it is not a hardened public admin surface. Treat extension pages as internal tools.
</Warning>

<CardGroup cols={2}>
  <Card title="Fox WebUI" icon="layout" href="/fox/webui">
    Learn how the WebUI is structured and how Fox presents missions and context.
  </Card>

  <Card title="WebUI Customization" icon="puzzle" href="/customize/webui-extensions">
    Go deeper on theming, layout overrides, and advanced extension patterns.
  </Card>
</CardGroup>