Add configurable custom frontends for Trackio (#531)

Co-authored-by: gradio-pr-bot <gradio-pr-bot@users.noreply.github.com>

Author: abidlabs

.changeset/little-cats-bet.md

@@ -0,0 +1,5 @@
+---
+"trackio": minor
+---
+
+feat:Add configurable custom frontends for Trackio

README.md

@@ -146,6 +146,32 @@ import trackio
 trackio.show(project="my-project")
 ```
 
+You can also point Trackio at a custom static frontend directory:
+
+```bash
+trackio show --frontend ./my-trackio-frontend
+```
+
+```py
+import trackio
+
+trackio.show(frontend_dir="./my-trackio-frontend")
+```
+
+The directory only needs an `index.html` file. Trackio keeps serving the same backend API under `/api/*`, so you can replace the UI without forking the backend. If the directory is missing or invalid, Trackio falls back to a minimal starter template.
+
+To make a custom frontend apply everywhere by default:
+
+```bash
+trackio config set frontend ./my-trackio-frontend
+```
+
+Reset it with:
+
+```bash
+trackio config unset frontend
+```
+
 ## Deploying to Hugging Face Spaces
 
 When calling `trackio.init()`, by default the service will run locally and store project data on the local machine.
@@ -183,10 +209,14 @@ If you've been tracking experiments locally and want to move them to Hugging Fac
 ```py
 import trackio
 
-trackio.sync(project="my-project", space_id="username/space_id")
+trackio.sync(
+    project="my-project",
+    space_id="username/space_id",
+    frontend_dir="./my-trackio-frontend",
+)
 ```
 
-This uploads your local project database to a new or existing Space. The Space will display all your logged experiments and metrics.
+This uploads your local project database to a new or existing Space. The Space will display all your logged experiments and metrics, and if a custom frontend is configured or passed explicitly it will be deployed there too.
 
 **Example workflow:**
 
@@ -199,7 +229,11 @@ trackio.log({"loss": 0.5})
 trackio.finish()
 
 # Later, sync to Spaces
-trackio.sync(project="my-project", space_id="username/my-experiments")
+trackio.sync(
+    project="my-project",
+    space_id="username/my-experiments",
+    frontend_dir="./my-trackio-frontend",
+)
 ```
 
 ## Embedding a Trackio Dashboard

docs/source/environment_variables.md

@@ -31,6 +31,18 @@ export TRACKIO_WRITE_TOKEN="YOUR_TOKEN"
 
 The dashboard **write token** for a self-hosted Trackio server (same value as the `write_token` query parameter in the write-access URL). Use this when `TRACKIO_SERVER_URL` or `server_url` is a base URL without query parameters. The client sends this token on each request (for example as the `X-Trackio-Write-Token` header) so metric ingestion and uploads are authenticated when not running on Hugging Face Spaces.
 
+### `TRACKIO_FRONTEND_DIR`
+
+Path to a custom static frontend directory for Trackio. The directory must contain `index.html`.
+
+When set, Trackio uses that frontend for `trackio.show()` and for deploy flows such as `trackio.sync()` and `trackio.freeze()`, unless an explicit `frontend_dir` / `--frontend` argument is passed.
+
+```bash
+export TRACKIO_FRONTEND_DIR="/path/to/my-trackio-frontend"
+```
+
+If the configured directory is invalid, Trackio ignores it and falls back to the built-in frontend selection logic. The automatic starter-template copy behavior only applies when an explicit `frontend_dir` / `--frontend` argument points to a missing or empty directory.
+
 ### `TRACKIO_LOGO_LIGHT_URL` and `TRACKIO_LOGO_DARK_URL`
 
 Customize the logos displayed in the Trackio dashboard for light and dark themes. You can provide URLs to custom logos. Note that both environment variables should be supplied; otherwise, the Trackio default will be used for any variable that is not provided.
@@ -164,5 +176,3 @@ export GRADIO_MCP_SERVER="True"
 
 
 See [this more comprehensive list](https://www.gradio.app/guides/environment-variables) of environment variables used by Gradio.
-
-

docs/source/launch.md

@@ -46,15 +46,56 @@ trackio.show(project="my-project")
 </hfoption>
 </hfoptions>
 
-## Changing the Theme
-
-You can change the theme of the dashboard by providing an optional `theme` argument.
+## Using a Custom Frontend
+
+You can replace the bundled dashboard with your own static frontend directory. The directory only needs an `index.html` file; your frontend can call the existing Trackio API under `/api/*`.
+
+The intended workflow is:
+
+1. Run `trackio show --frontend ./my-trackio-frontend`.
+2. Ask your LLM to edit the files in that directory.
+3. Keep the browser open while Trackio live reloads the frontend as those files change.
+
+If the directory passed to `--frontend` does not exist, or exists but is empty, Trackio copies in the starter frontend automatically, prints that it did so, and then serves that directory. The starter is a complete plain-HTML/CSS/JS template: it calls the Trackio API, loads projects and runs, fetches metric values, and draws simple charts that you can replace with your own UI.
+
+The currently available HTTP endpoints are:
+
+- `POST /api/get_run_mutation_status`
+- `POST /api/upload_db_to_space`
+- `POST /api/bulk_upload_media`
+- `POST /api/log`
+- `POST /api/bulk_log`
+- `POST /api/bulk_log_system`
+- `POST /api/bulk_alert`
+- `POST /api/get_alerts`
+- `POST /api/get_metric_values`
+- `POST /api/get_runs_for_project`
+- `POST /api/get_metrics_for_run`
+- `POST /api/get_all_projects`
+- `POST /api/get_project_summary`
+- `POST /api/get_run_summary`
+- `POST /api/get_system_metrics_for_run`
+- `POST /api/get_system_logs`
+- `POST /api/get_system_logs_batch`
+- `POST /api/get_snapshot`
+- `POST /api/get_logs`
+- `POST /api/get_logs_batch`
+- `POST /api/get_traces`
+- `POST /api/query_project`
+- `POST /api/get_settings`
+- `POST /api/get_project_files`
+- `POST /api/delete_run`
+- `POST /api/rename_run`
+- `POST /api/force_sync`
+- `POST /api/upload` for multipart file uploads used by media and file-related flows
+
+For reading stored files returned by the API, Trackio also serves `GET /file?path=...`.
 
 <hfoptions id="language">
 <hfoption id="Shell">
 
 ```sh
-trackio show --theme "soft"
+trackio show --frontend ./my-trackio-frontend
 ```
 
 </hfoption>
@@ -63,13 +104,27 @@ trackio show --theme "soft"
 ```py
 import trackio 
 
-trackio.show(theme="soft")
+trackio.show(frontend_dir="./my-trackio-frontend")
 ```
 
 </hfoption>
 </hfoptions>
 
-To see the available themes, check out the [themes gallery](https://huggingface.co/spaces/gradio/theme-gallery).
+If the provided frontend directory is non-empty but invalid, Trackio falls back to the shipped starter template.
+
+## Setting a Persistent Default Frontend
+
+If you want the same custom frontend to be used by `trackio show`, `trackio sync`, and deploy flows by default, save it in Trackio's persistent config:
+
+```sh
+trackio config set frontend ./my-trackio-frontend
+```
+
+Reset it with:
+
+```sh
+trackio config unset frontend
+```
 
 ## Customizing Plot Colors
 

examples/custom-frontends/README.md

@@ -0,0 +1,18 @@
+# Custom Frontend Examples
+
+These folders are not used by Trackio at runtime.
+
+They exist so the custom frontend feature can ship with a few visually distinct examples
+that are easy to screenshot, copy, and remix.
+
+Each example includes:
+
+- `frontend/`: a complete static frontend directory that can be passed to `trackio show --frontend`
+- `screenshot.png`: a screenshot for docs, PRs, and social posts
+
+Examples:
+
+- `editorial`
+- `signal`
+- `starter`
+- `sunrise`

examples/custom-frontends/editorial/frontend/app.js

@@ -0,0 +1,14 @@
+import { mountTheme } from "./shared-theme.js";
+
+mountTheme({
+  title: document.querySelector("#title"),
+  projectSelect: document.querySelector("#project-select"),
+  runSelect: document.querySelector("#run-select"),
+  metricsEl: document.querySelector("#metrics"),
+  metricsSubtitle: document.querySelector("#metrics-subtitle"),
+  projectSummary: document.querySelector("#project-summary"),
+  runsCount: document.querySelector("#runs-count"),
+  metricsCount: document.querySelector("#metrics-count"),
+  selectedRunName: document.querySelector("#selected-run-name"),
+  selectedRunMeta: document.querySelector("#selected-run-meta"),
+});

examples/custom-frontends/editorial/frontend/index.html

@@ -0,0 +1,61 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Editorial</title>
+    <link rel="stylesheet" href="./styles.css" />
+  </head>
+  <body>
+    <main class="shell">
+      <aside class="sidebar">
+        <img
+          src="/static/trackio/trackio_logo_type_light_transparent.png"
+          alt="Trackio"
+          class="editorial-logo"
+        />
+        <p class="kicker">Editorial</p>
+        <h1 id="title">Loading</h1>
+        <p id="project-summary" class="sidebar-note">Choose a project and run.</p>
+
+        <section class="control-block">
+          <label class="control-label" for="project-select">Project</label>
+          <select id="project-select" class="selector"></select>
+        </section>
+
+        <section class="control-block">
+          <label class="control-label" for="run-select">Run</label>
+          <select id="run-select" class="selector"></select>
+        </section>
+
+        <section class="stat-grid">
+          <div class="stat-card">
+            <span class="stat-label">Runs</span>
+            <strong id="runs-count">0</strong>
+          </div>
+          <div class="stat-card">
+            <span class="stat-label">Metrics</span>
+            <strong id="metrics-count">0</strong>
+          </div>
+        </section>
+      </aside>
+
+      <section class="content">
+        <div class="panel metrics-panel">
+          <div class="panel-head">
+            <div>
+              <h2>Metrics</h2>
+              <p id="metrics-subtitle" class="section-note">Metric plots for the selected run.</p>
+            </div>
+            <div class="panel-meta">
+              <span id="selected-run-name">Loading run</span>
+              <span id="selected-run-meta">Waiting for Trackio data.</span>
+            </div>
+          </div>
+          <div id="metrics"></div>
+        </div>
+      </section>
+    </main>
+    <script type="module" src="./app.js"></script>
+  </body>
+</html>