Dashboard Registries

Overview

A dashboard registry is a static JSON index that lists .bar dashboards for installation. Metrix.Bar reads the registry, presents the catalog, and downloads each dashboard over HTTPS — no package server or account is required.

Every registry publishes an index.json at a fixed URL. Entries point at same-origin .bar files, carry integrity hashes, and use short IDs that combine into a globally unique install ID on the device.

The index.json Schema

{
  "$schema": "https://metrix.bar/dashboards/schema.json",
  "schema_version": 1,
  "id": "official",
  "name": "Official",
  "dashboards": [
    {
      "id": "github-repo",
      "name": "GitHub Repository",
      "file": "github-repo.bar",
      "protocol_version": "0",
      "version": "1.0.0",
      "category": "development",
      "description": "Track GitHub repository stars, forks, and activity.",
      "icon": "star",
      "license": "AGPL-3.0-only",
      "homepage": "https://agili.app",
      "sha256": "7c9bbe54c15a8b940486b167094a18f7f9f6f3eccad4d5c63a17e070eebacc72"
    }
  ]
}

Download the complete official GitHub dashboard. The digest must match the exact bytes you publish.

The schema is published at /dashboards/schema.json.

Install IDs

Installing a dashboard joins the registry ID and dashboard ID with a double hyphen:

{registryID}--{dashboardID}
official--github-repo
awesome--crypto-ticker

The install ID is local to the device and never appears in the registry. On install Metrix.Bar:

1. Fetches the .bar over HTTPS.
2. Verifies the raw bytes against the entry's sha256 and records that digest in the provenance Source as sha256.
3. Rewrites only the root <bar id="…"> to the composite install ID and re-parses the document.
4. Computes the digest of the rewritten file and records it as installed_sha256 (the on-disk file no longer matches sha256 in index.json because of the rewritten root ID — this is expected).

The provenance record also binds registry_id, registry_url (canonical registry URL), and dashboard_id. Binding strictly follows registryID + dashboardID + Canonical registry URL. If provenance is missing or the registry URL changes, Metrix.Bar does not take over an installed dashboard, and unlinked local dashboards never guess a remote source.

Because the root ID rewrite alters the installed file, installed_sha256 normally differs from the raw sha256. The app checks these hashes separately:

• Local modification check: compares the current on-disk .bar SHA-256 against installed_sha256.
• Upstream update check: compares the remote entry's sha256 against the recorded raw sha256.

Official and Awesome

• Official — https://metrix.bar/dashboards/index.json. Fixed and always enabled; it cannot be removed or disabled. It distributes all 16 official .bar dashboards — only the GitHub repository dashboard is also bundled with the app; the rest install from this registry on demand.
• Awesome — https://awesome.metrix.bar/dashboards/index.json. A preset community registry address, disabled by default; availability when enabled depends on whether awesome.metrix.bar provides a valid index.

Both are ordinary registries — only the defaults differ.

Self-Hosted Registries

Any HTTPS URL serving a valid index.json works as a registry. Requirements:

• HTTPS, or HTTP on your local network — Registries and .bar downloads use HTTPS on any host and port; hosts on your local network (private IPs, .local and similar) may also use plain HTTP for self-hosting. Credentials and fragments are rejected and redirects must stay on the same origin. Requests follow the app's proxy settings, so fake-IP and TUN proxies work. Addresses in metrixbar:// links still must be public HTTPS.
• Same-origin files — every file resolves relative to the index.json URL and must stay strictly on the same origin; redirects must also stay on the same origin.
• Valid schema — the document must match dashboard-registry.schema.json (schema_version: 1, slug IDs, required fields, SHA-256 hashes).
• Asynchronous validation — Saving registry configurations persists the settings immediately; network fetch and validation run asynchronously in the background. If verification fails or the network is unreachable, Metrix.Bar retains the error state and any cached index rather than rejecting the configuration.
• Unique IDs — dashboard IDs must be unique inside the registry and follow the slug pattern (no --, which is reserved for install IDs).

A minimal self-hosted index is a static file on any HTTPS host (the SHA-256 digest below matches the raw byte content <bar protocol-version="0" version="1.0.0" id="example" category="development"><docs>Example setup instructions</docs><script><![CDATA[const id = "example";]]></script></bar> without a trailing newline):

{
  "$schema": "https://metrix.bar/dashboards/schema.json",
  "schema_version": 1,
  "id": "my-team",
  "name": "My Team",
  "dashboards": [
    {
      "id": "example",
      "name": "Example",
      "file": "example.bar",
      "protocol_version": "0",
      "version": "1.0.0",
      "docs": "Example setup instructions",
      "sha256": "85d4f03b07795353f523e35227c575af674c6910e00e0f833bf6ed54ee6bac94"
    }
  ]
}

Building Registries with build.js

You can package and publish custom registries using the standalone builder script hosted directly on the official website:

curl -fsS https://metrix.bar/dashboards/build.js -o build.js
node build.js --input ./dashboards --output ./dist/dashboards --id my-team --name "My Team"

Builder characteristics:

• Zero npm dependencies: Bundles all XML parsing dependencies (saxes and xmlchars). Requires only Node 22+ and runs without npm install.
• Not on npm or MCP: Distributed exclusively as a standalone script from the website; not published to npm and does not register as an MCP tool.
• Byte-exact preservation: Copies .bar files preserving relative directory structure and generates index.json with accurate raw-byte SHA-256 digests and $schema hints.
• Static validation vs. runtime validation: build.js performs static checks (XML syntax, required root attributes, SemVer, category slugs, and homepage URLs). It does not execute scripts or validate runtime environment hooks. For full runtime execution, UI rendering, and permission validation, use the local API's POST /v0/check, POST /v0/validate, or metrixbar check.

Updates

Metrix.Bar automatically checks enabled registries every 24 hours (and on manual refresh). Automatic checks only query for available updates — they never silently apply updates.

• Strict SemVer & Manual confirmation: Updates require a strictly higher SemVer version and must be explicitly confirmed by the user. An upstream hash change on the same version is treated as an anomaly and rejected.
• Local modification check: Metrix.Bar compares the current on-disk .bar SHA-256 against the recorded installed_sha256. If the file was modified locally, the user must explicitly confirm the replacement; before applying, Metrix.Bar automatically creates a timestamped backup copy (<runtimeID>-local-*.bar) in the application data directory.
• Concurrency protection: The confirmation flow verifies the installed file's ETag. If concurrent edits occur before applying, the update aborts.
• Input configuration and secrets: Compatible saved inputs and secrets stored in the OS credential store are preserved across updates. If an update introduces incompatible input removals or type changes, the update is rejected until resolved.

Security Notes

• Registry fetches go out over HTTPS with Metrix.Bar's standard headers (User-Agent: Metrix.Bar/<version>, X-Requested-With: bar.metrix).
• sha256 is verified before a dashboard is installed or updated; a mismatch aborts the install.
• Registry metadata never grants extra permissions — the .bar file's own <permissions> block still controls network origins and file access, and secrets stay in the OS credential store.

Install links

Open metrixbar://open to bring Metrix.Bar forward. Use metrixbar://open/<instanceID> to select a dashboard, or metrixbar://refresh[/<instanceID>] to refresh one or all instances. IDs retain their decoded value and case, including dots and Unicode. Encode IDs as a single path segment; ., .., path separators, and NUL are rejected.

Use metrixbar://install/github-repo for the official catalog, or append ?registry=awesome (or another configured source ID). A disabled source asks for confirmation before it is enabled. To install from another index, use metrixbar://install/<id>?registry_url=<encoded HTTPS index URL>. Metrix.Bar validates the source, displays the dashboard's permissions and inputs, and saves the source only when you confirm installation. Canceling leaves an unconfigured source unsaved. metrixbar://registry/add?url=<encoded HTTPS index URL> asks to add only the source.

Clicking a registry install link again opens the installed dashboard when its source, version, and raw SHA-256 match. The app verifies the current index without saving a check timestamp or cache. A changed hash on the same version is rejected, and higher versions still require update confirmation.

For a direct import, use metrixbar://install?url=<encoded HTTPS .bar URL> and optionally append &sha256=<64 hexadecimal characters>. The app verifies a supplied checksum, shows the download domain, permissions, and inputs, then installs after confirmation. These imports retain their original dashboard ID and download provenance; they do not receive registry updates. Clicking the same URL again opens the installed dashboard when the downloaded SHA-256 matches its recorded original digest, even if the local file has been edited. Changed downloads require another import confirmation; they are never applied automatically and may keep the same version. A supplied checksum must match before either action. Updates preserve compatible settings and secrets, require explicit approval and a backup for local edits, and abort if the file or source changes after preparation. A failed save rolls back the update. A different source cannot overwrite an installed dashboard with the same ID.

Encode nested URLs as query parameter values. Duplicate or conflicting parameters, credentials, fragments, and malformed checksums are rejected. Downloads use bounded public HTTPS requests and same-origin redirects. Multiple links are queued until the main window is ready, with duplicate pending clicks handled once. Canceling or dismissing an error allows the next link to proceed.