Skip to main content
The dashboard gives existing state a window; it does not build a second house behind the curtains.

​
1. Motivation

Configuration and workspace inspection otherwise bounce between CLI calls and short Python scripts. The dashboard exposes the same public surfaces through a strict TypeScript client over one generated OpenAPI contract:
It adds no planner, configuration store, Registry, or row persistence path. The browser UI lives under apps/gui/; Python owns the transport-neutral application service and HTTP boundary under heavenbase.api.

​
2. Start the Workbench

The server binds to 127.0.0.1:42777 by default and prefers the macOS system WebView host, with the system browser as a fallback. On first run, HeavenBase ensures a default workspace exists.
--app explicitly requests a Chromium --app window. --install-app installs ~/Applications/HeavenBase.app so Finder and the Dock can launch the system WebView host directly.
Non-loopback binds require --allow-network. That exposes an unauthenticated configuration API to the selected network, so review the risk first.

​
3. Inspect Configuration

The configuration workbench reads and writes through CM_HVNB. It shows whether each key is built-in, overridden, or custom and supports scope selection, history, version comparison, reset, and search. Built-in keys stay locked. Environment interpolation is shown as written, and secret-like values are masked.

​
4. Browse Workspace State

The data browser lists registered WorkspaceSpec values and opens one workspace at a time. For each Entity, it offers sortable, filterable, paged tables, row inspection, Data and Schema views, placement metadata, query capabilities, and workspace health. The command palette searches Catalog and MetaSchema cards through ws.search(...).
Workspace rows are read-only in the 0.1.2.2 dashboard. It does not register Entities, alter schemas, upsert rows, or delete rows.

​
5. Use the Optional Assistant

The assistant uses the model configured under heavenbase.dashboard.assistant. Its tools can list Entities, inspect schemas, sample rows, calculate exact whole-column statistics, search the workspace, query and explain data, and read masked configuration. Query results carry exact pre-pagination total and truncated facts so the interface does not present a page as the whole result. You can stop an active turn from the interface. Cancellation closes the client stream and releases the server-side progress feed; a provider that ignores cancellation remains bounded by its own timeout. The optional run_python assistant tool is disabled by default under heavenbase.dashboard.assistant.run_python. Enabling it executes caller-authored Python in the HeavenBase process with the live workspace bound, so expose it only to trusted local users. Credentials remain masked by default. Enabling heavenbase.dashboard.assistant.share_credentials may send raw values to the configured external model provider and requires explicit disclosure acknowledgement.

​
6. Embed the Adapter

Use the public API boundary when another local host owns process lifecycle:
app is the ASGI transport over the transport-neutral DashboardAPI. Use heavenbase.dashboard.serve(...) only when HeavenBase should own the loopback server and desktop-host lifecycle. The dashboard is an adapter over public configuration, Registry, workspace, Catalog, MetaSchema, query, and LLM surfaces. Core domains do not import it.

​
Summary

  • The dashboard visualizes existing HeavenBase authorities.
  • The TypeScript client and Python service share one generated OpenAPI contract.
  • Loopback is the safe default; network exposure is explicit.
  • Workspace browsing is read-only.
  • Assistant cancellation and result-coverage facts remain explicit.
  • The assistant shares credentials or executes Python only after explicit opt-in.

​
Further Exploration

Related resources:
  • Configuration — Scoped values and retained history
  • Workspace — The application boundary shown by the dashboard
  • Catalog — Object and structure discovery
  • CLI Reference — Dashboard flags and other hb commands