README.md

metadata

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

Explainer Dashboard

TanStack Start dashboard for running and inspecting Explainer environment episodes.

Install

cd dashboard
npm install

Run Locally

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:

http://127.0.0.1:8080/

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

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.

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

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.

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:

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:

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.