README.md

---
title: Explainer Dashboard
sdk: docker
app_port: 7860
pinned: false
---

# Explainer Dashboard

TanStack Start dashboard for running and inspecting Explainer environment episodes.

## Install

```bash
cd dashboard
npm install
```

## Run Locally

```bash
cd dashboard
npm run dev
```

The app starts on the Vite dev server URL printed in the terminal. In the current
config this is usually:

```text
http://127.0.0.1:8080/
```

If the default host binding is blocked in your shell, run:

```bash
npm run dev -- --host 127.0.0.1
```

## Environment Variables

Set these in the shell before starting `npm run dev`, or put them in whatever
process manager/deployment environment launches the dashboard.

```bash
export ENV_BASE_URL="https://kgdrathan-explainer-env.hf.space"
export API_BASE_URL="https://router.huggingface.co/v1"
export MODEL_NAME="bedrock-qwen3-coder-30b-a3b"
export HF_TOKEN="hf_..."

npm run dev -- --host 127.0.0.1
```

`HF_TOKEN` can be replaced with `API_KEY` if your OpenAI-compatible endpoint uses
that name.

## Settings Reference

| Variable | Default | Used for |
| --- | --- | --- |
| `ENV_BASE_URL` | `https://kgdrathan-explainer-env.hf.space` | Explainer environment API. The dashboard opens a persistent websocket at `${ENV_BASE_URL}/ws`. |
| `API_BASE_URL` | `https://router.huggingface.co/v1` | OpenAI-compatible chat completions endpoint. |
| `MODEL_NAME` | `bedrock-qwen3-coder-30b-a3b` | Model sent to the chat completions endpoint. |
| `HF_TOKEN` | unset | Bearer token for the LLM endpoint. |
| `API_KEY` | unset | Fallback bearer token if `HF_TOKEN` is not set. |

The settings are read on the server side only:

- Environment URL and runtime config: `src/server/env.functions.ts`
- LLM endpoint, token, and model: `src/server/llm.functions.ts`

The dashboard header shows the resolved `ENV_BASE_URL` and whether a token is
available. It does not show the model name.

## Validate

```bash
npm run lint
npm run build
```

`npm run lint` may print Fast Refresh warnings from shared UI component exports;
those are warnings, not runtime blockers.

During `npm run build`, Wrangler may print a log-directory permission warning in
sandboxed environments. The build is still valid if the command exits with code
`0`.

## Deploy as a Hugging Face Space

Create the Space as a Docker Space, using `dashboard/` as the repository root.
The included `Dockerfile` builds the TanStack app and serves it on port `7860`.

```bash
cd dashboard
hf repos create YOUR_USERNAME/explainer-dashboard --type space --space-sdk docker --private
hf upload YOUR_USERNAME/explainer-dashboard . --type space \
  --exclude node_modules --exclude dist --exclude .env --exclude .env.* \
  --commit-message "Deploy explainer dashboard"
```

Set these Space secrets/variables in the Hugging Face UI, or when creating the
Space with `hf repos create --env ... --secrets ...`:

| Setting | Type | Required | Notes |
| --- | --- | --- | --- |
| `ENV_BASE_URL` | Variable | Yes | URL of the Python Explainer env Space, for example `https://kgdrathan-explainer-env.hf.space`. |
| `API_BASE_URL` | Variable | No | Defaults to `https://router.huggingface.co/v1`. |
| `MODEL_NAME` | Variable | No | Defaults to `bedrock-qwen3-coder-30b-a3b`. |
| `HF_TOKEN` | Secret | Yes | Token used by the server-side LLM call. Use a secret, not a public variable. |
| `API_KEY` | Secret | No | Fallback if `HF_TOKEN` is not set. |

After upload, check build/runtime logs with:

```bash
hf spaces logs YOUR_USERNAME/explainer-dashboard --build
hf spaces logs YOUR_USERNAME/explainer-dashboard
```

## Using a Local Environment Server

Start the Python Explainer environment separately, then point the dashboard at it:

```bash
export ENV_BASE_URL="http://127.0.0.1:8000"
npm run dev -- --host 127.0.0.1
```

The environment server must expose `WS /ws` for persistent reset/step sessions.