--- title: "Dashboard Registries: index.json, Install IDs & Updates · Metrix.Bar" description: "Reference for Metrix.Bar dashboard registries: the index.json schema, official and Awesome sources, composite install IDs, SHA-256 verification, HTTPS rules, self-hosting, and the update flow." canonical: "https://metrix.bar/docs/registries" language: "en" --- # Dashboard Registries > How Metrix.Bar discovers, verifies, and installs .bar dashboards from remote 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 ```json { "$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](https://metrix.bar/dashboards/github-repo.bar). The digest must match the exact bytes you publish. | Field | Required | Rules | | ------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `$schema` | No | Optional JSON Schema URI hint (e.g. `https://metrix.bar/dashboards/schema.json`) for editor autocompletion and validation. Clients do not download this URI; `schema_version` remains the sole protocol contract. | | `schema_version` | Yes | Must be `1`. | | `id` | Yes | Registry slug — `/^[a-z0-9]+(?:-[a-z0-9]+)*$/`, no `--`. | | `name` | Yes | Display name. | | `dashboards[].id` | Yes | Dashboard slug, same ID pattern, unique inside the registry. | | `dashboards[].name` | Yes | Display name. | | `dashboards[].file` | Yes | Same-origin relative path to the `.bar` file — no leading `/`, no scheme or host, no query (`?`), fragment (`#`), or backslash (`\`). Decoded percent-encoding must remain a relative `.bar` path on the same origin. | | `dashboards[].protocol_version` | Yes | Must be `"0"`. | | `dashboards[].version` | Yes | Strict SemVer 2.0.0 — `major.minor.patch`, optional pre-release/build, no `v` prefix, no leading zeros in numeric parts. | | `dashboards[].category` | No | Optional stable slug; defaults to `other` when omitted. Explicit empty string `""` or `null` is invalid. Official categories: `ai`, `analytics`, `development`, `weather`, `finance`, `utilities`. | | `dashboards[].description` | No | Optional short summary. May be empty string `""`, but cannot be `null`. | | `dashboards[].icon` | No | Optional icon name or URL. May be empty string `""`, but cannot be `null`. | | `dashboards[].license` | No | Optional SPDX-style license string. May be empty string `""`, but cannot be `null`. | | `dashboards[].homepage` | No | Optional display URL. If present, must be a non-empty absolute HTTPS URL without credentials, with a non-empty host (custom ports and fragments allowed); cannot be `null`. Display only. | | `dashboards[].docs` | No | Optional plain-text setup and configuration instructions from the `.bar` `` block, preserving internal newlines. Cannot be `null`. Omitted or empty string is not displayed. | | `dashboards[].sha256` | Yes | Lowercase 64-char hex digest of the raw `.bar` bytes as published. | The schema is published at [`/dashboards/schema.json`](/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 `` 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 `Example setup instructions` without a trailing newline): ```json { "$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: ```bash 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 (`-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/`, `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 `` 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/` to select a dashboard, or `metrixbar://refresh[/]` 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/?registry_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=` 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=` 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.