Add server_url parameter for self-hosting Trackio servers (#510)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: gradio-pr-bot <gradio-pr-bot@users.noreply.github.com>

Author: 3 people

.changeset/vast-yaks-wait.md

@@ -0,0 +1,5 @@
+---
+"trackio": minor
+---
+
+feat: Add server_url and TRACKIO_SERVER_URL for self-hosted servers; space_id and TRACKIO_SPACE_ID take precedence when both are set

README.md

@@ -35,9 +35,9 @@ Trackio's main features:
   ```
   and keep your existing logging code.
 
-- **Local-first** design: dashboard runs locally by default. You can also host it on Spaces by specifying a `space_id` in `trackio.init()`.
-  - Persists logs in a Sqlite database locally (or, if you provide a `space_id`, in a private Hugging Face Dataset)
-  - Visualize experiments with a **Svelte 5** dashboard locally (or, if you provide a `space_id`, on Hugging Face Spaces)
+- **Local-first** design: dashboard runs locally by default. You can also send metrics to a Hugging Face Space with `space_id` for free or to a self-hosted Trackio server you run yourself with `server_url`
+  - Persists logs in a Sqlite database locally (or on the remote target you chose: Space, or the machine hosting your self-hosted server)
+  - Visualize experiments with a **Svelte 5** dashboard locally, on Hugging Face Spaces, or on your own host when you self-host the server
 - **LLM-friendly**: Built with autonomous ML experiments in mind, Trackio includes a CLI for programmatic access and a Python API for run management, making it easy for LLMs to log metrics and query experiment data.
   - Use `trackio query project --project <name> --sql "SELECT ..."` for read-only SQL when `trackio list` and `trackio get` are not enough
   - See the storage schema and direct query reference at https://huggingface.co/docs/trackio/storage_schema
@@ -155,6 +155,18 @@ trackio.init(project="my-project", space_id="username/space_id")
 
 it will use an existing or automatically deploy a new Hugging Face Space as needed. You should be logged in with the `huggingface-cli` locally and your token should have write permissions to create the Space.
 
+## Self-hosted Trackio server
+
+You can run the Trackio dashboard and API on your own machine or infrastructure and point training jobs at it over HTTP. Pass the write-access URL from `trackio.show()` (which may include `write_token` in the query), or a base URL plus the `TRACKIO_WRITE_TOKEN` environment variable. The client sends that token on requests; it is not your Hugging Face token.
+
+```py
+trackio.init(project="my-project", server_url="http://127.0.0.1:7860?write_token=YOUR_TOKEN")
+```
+
+You can also set `TRACKIO_SERVER_URL` (and optionally `TRACKIO_WRITE_TOKEN` if the URL has no query string). If `space_id` / `TRACKIO_SPACE_ID` and `server_url` / `TRACKIO_SERVER_URL` are both set, Trackio uses the Hugging Face Space and ignores the self-hosted URL.
+
+See the documentation: [Self-host the Server](https://huggingface.co/docs/trackio/self_hosted_server).
+
 ## Syncing Offline Projects to Spaces
 
 If you've been tracking experiments locally and want to move them to Hugging Face Spaces for sharing or collaboration, use the `sync` function:

docs/source/_toctree.yml

@@ -13,6 +13,8 @@
     title: Track
   - local: launch
     title: Launch the Dashboard
+  - local: self_hosted_server
+    title: Self-host the Server
   - local: deploy_embed
     title: Deploy and Embed Dashboards
   - local: manage

docs/source/environment_variables.md

@@ -14,6 +14,23 @@ export TRACKIO_DIR="/path/to/trackio/data"
 
 Note: This environment variable applies as long as Trackio is not running in a Space with persistent storage enabled. If Trackio is running in a Space with persistent storage enabled (which is detected with the `PERSISTANT_STORAGE_ENABLED` env variable), then the Trackio data will be stored in `/data/trackio`.
 
+### `TRACKIO_SERVER_URL`
+
+Base URL of a self-hosted Trackio server (`http://` or `https://`). You may include `write_token` in the query string (as in the `full_url` from `trackio.show()`), or keep the URL bare and set `TRACKIO_WRITE_TOKEN` instead. When set, `trackio.init()` sends metrics to that server. Equivalent to passing `server_url=` to `trackio.init()`.
+
+**Precedence:** If `TRACKIO_SPACE_ID` is also set (or `space_id` is passed in code), the Hugging Face Space is used and `TRACKIO_SERVER_URL` is ignored. Same rule when both `space_id` and `server_url` are passed: `space_id` wins.
+
+See [Self-host the Server](self_hosted_server.md).
+
+```bash
+export TRACKIO_SERVER_URL="http://127.0.0.1:7860"
+export TRACKIO_WRITE_TOKEN="YOUR_TOKEN"
+```
+
+### `TRACKIO_WRITE_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_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.

docs/source/index.md

@@ -14,9 +14,9 @@
   import trackio as wandb
   ```
 
-- **Local-first** design: dashboard runs locally by default. You can also host it on Spaces by specifying a `space_id`.
-- Persists logs locally (or in a private Hugging Face Dataset)
-- Visualize experiments with a Gradio dashboard locally (or on Hugging Face Spaces)
+- **Local-first** design: dashboard runs locally by default. You can also log to a Hugging Face Space (`space_id`) for free or to a **self-hosted** Trackio server (`server_url`)
+- Persists logs locally, in a Hugging Face Dataset when using Spaces, or on the machine hosting your self-hosted server
+- Visualize experiments with a Gradio dashboard locally, on Hugging Face Spaces, or on your own host when self-hosting
 - **LLM-friendly**: Designed for autonomous ML experiments with CLI commands and Python APIs that enable LLMs to easily log and query experiment data.
 - Everything here, including hosting on Hugging Face, is **free**!
 

docs/source/self_hosted_server.md

@@ -0,0 +1,77 @@
+# Self-host the Trackio server
+
+You can run the Trackio dashboard and API on your own machine (or any host you control) and send metrics from training scripts to that server over HTTP. This is an alternative to logging to a Hugging Face Space via `space_id`.
+
+## Run the server locally
+
+Install Trackio, then start the dashboard. By default it listens on `127.0.0.1` and uses the port from `GRADIO_SERVER_PORT` if set, otherwise **7860** (see [Launch the Dashboard](launch.md)).
+
+<hfoptions id="language">
+<hfoption id="Shell">
+
+```sh
+trackio show
+```
+
+</hfoption>
+<hfoption id="Python">
+
+```py
+import trackio
+
+trackio.show()
+```
+
+</hfoption>
+</hfoptions>
+
+Leave that process running while you train. The terminal prints a base URL for the UI and a URL that includes a **write token**; anyone who can reach that URL with the token can perform write operations supported by the server (for example renaming runs), so treat it like a secret on untrusted networks.
+
+## Listen on all interfaces
+
+To access the dashboard from another machine on your network (or from containers), bind to all interfaces:
+
+<hfoptions id="language">
+<hfoption id="Shell">
+
+```sh
+trackio show --host 0.0.0.0
+```
+
+</hfoption>
+<hfoption id="Python">
+
+```py
+import trackio
+
+trackio.show(host="0.0.0.0")
+```
+
+</hfoption>
+</hfoptions>
+
+Ensure your firewall and security policies allow the traffic you intend.
+
+## Point training code at your server
+
+In your training script, pass a `server_url` and supply the **write token**: either embed `write_token` in the query string (the same URL the dashboard prints for write access, or the `full_url` return value from `trackio.show()`), or pass a base URL like `http://127.0.0.1:7860/` and set the `TRACKIO_WRITE_TOKEN` environment variable to that token. Metric ingestion and uploads require this token when the server is not on Hugging Face Spaces. You can also set `TRACKIO_SERVER_URL` instead of passing `server_url` in code.
+
+```py
+import trackio
+
+trackio.init(
+    project="my-project",
+    server_url="http://127.0.0.1:7860?write_token=YOUR_TOKEN",
+)
+trackio.log({"loss": 0.25})
+trackio.finish()
+```
+
+Precedence: **`space_id` / `TRACKIO_SPACE_ID` always wins** over `server_url` / `TRACKIO_SERVER_URL` when both are set (in code or in the environment). Trackio then behaves as if only the Space were configured.
+
+Hugging Face–specific options such as `dataset_id` and `bucket_id` apply only when logging to a Space. When only `server_url` is in effect, configure persistence on the machine where the server runs (for example via `TRACKIO_DIR` on that host). See [Environment Variables](environment_variables.md).
+
+## Related
+
+- [Launch the Dashboard](launch.md) — CLI options, port, and remote access
+- [Environment Variables](environment_variables.md) — `TRACKIO_SERVER_URL`, `TRACKIO_DIR`, and others

docs/source/track.md

@@ -44,6 +44,17 @@ trackio.init(project="my_project", name="tuned_run_1", group="tuned")
 
 Runs with the same group name can be grouped together in sidebar, making it easier to compare related experiments. You can also group runs by any other configuration parameter (see [Tracking Configuration](#tracking-configuration) below).
 
+### Remote logging (Hugging Face Space or self-hosted server)
+
+By default, metrics are stored locally and you open the dashboard on your machine. You can instead send metrics to:
+
+- A **Hugging Face Space**, by passing `space_id` (or setting `TRACKIO_SPACE_ID`). Trackio can create or reuse the Space and sync data there.
+- A **self-hosted Trackio server** (HTTP or HTTPS), by passing `server_url` (or setting `TRACKIO_SERVER_URL`). Use the write-access URL from `trackio.show()` (optionally with `write_token` in the query), or a base URL plus `TRACKIO_WRITE_TOKEN`. The client authenticates with the same **write token** the dashboard uses (not your Hugging Face token).
+
+If both a Space and a self-hosted URL are configured (`space_id` / `TRACKIO_SPACE_ID` together with `server_url` / `TRACKIO_SERVER_URL`), **the Space takes precedence** and the self-hosted URL is ignored. Options such as `dataset_id` and `bucket_id` apply to Hugging Face deployments; when only `server_url` is in effect, configure storage on the host that runs the server (see [Environment Variables](environment_variables.md)).
+
+For setup steps (running `trackio show`, binding to `0.0.0.0`, write tokens), see [Self-host the Server](self_hosted_server.md).
+
 ## Logging Data
 
 Once your run is initialized, you can start logging data using the [`log`] function:

tests/e2e-local/test_api.py

@@ -1,11 +1,13 @@
 import asyncio
 import tempfile
 from pathlib import Path
+from urllib.parse import parse_qs, urlparse
 
 import httpx
 import pytest
 
 import trackio
+import trackio.context_vars as context_vars
 import trackio.utils as trackio_utils
 from trackio import Api
 from trackio.remote_client import RemoteClient as Client
@@ -199,6 +201,31 @@ def test_local_dashboard_supports_remote_client(temp_dir):
         app.close()
 
 
+def test_server_url_logs_to_self_hosted_server(temp_dir):
+    project = "test_self_hosted"
+    run_name = "self-hosted-run"
+
+    app, url, _, full_url = trackio.show(block_thread=False, open_browser=False)
+
+    try:
+        write_token = parse_qs(urlparse(full_url).query).get("write_token", [None])[0]
+        assert write_token
+
+        context_vars.current_server.set(None)
+        context_vars.current_project.set(None)
+        context_vars.current_run.set(None)
+
+        trackio.init(project=project, name=run_name, server_url=full_url)
+        trackio.log(metrics={"loss": 0.5})
+        trackio.finish()
+
+        client = Client(url, verbose=False)
+        runs = client.predict(project, api_name="/get_runs_for_project")
+        assert any(r.get("name") == run_name for r in runs)
+    finally:
+        app.close()
+
+
 def test_local_dashboard_returns_400_for_missing_required_parameter(temp_dir):
     app, url, _, _ = trackio.show(block_thread=False, open_browser=False)
 
@@ -258,7 +285,10 @@ def test_local_dashboard_upload_api_accepts_only_server_uploaded_paths(temp_dir)
     blocked_target = trackio_utils.MEDIA_DIR / project / "files" / "blocked.txt"
     allowed_target = None
 
-    app, url, _, _ = trackio.show(block_thread=False, open_browser=False)
+    app, url, _, full_url = trackio.show(block_thread=False, open_browser=False)
+    write_token = parse_qs(urlparse(full_url).query).get("write_token", [None])[0]
+    assert write_token
+    write_headers = {"x-trackio-write-token": write_token}
 
     try:
         with source_path.open("rb") as handle:
@@ -279,6 +309,7 @@ def test_local_dashboard_upload_api_accepts_only_server_uploaded_paths(temp_dir)
 
         allowed_resp = httpx.post(
             f"{url.rstrip('/')}/api/bulk_upload_media",
+            headers=write_headers,
             json={
                 "uploads": [
                     {
@@ -295,6 +326,7 @@ def test_local_dashboard_upload_api_accepts_only_server_uploaded_paths(temp_dir)
         )
         blocked_resp = httpx.post(
             f"{url.rstrip('/')}/api/bulk_upload_media",
+            headers=write_headers,
             json={
                 "uploads": [
                     {
@@ -326,6 +358,8 @@ def test_local_dashboard_upload_api_accepts_only_server_uploaded_paths(temp_dir)
 
 def test_local_dashboard_supports_mcp(temp_dir):
     pytest.importorskip("mcp")
+    from mcp import ClientSession
+    from mcp.client.streamable_http import streamable_http_client
 
     project = "test_local_mcp"
     run_name = "mcp-run"
@@ -341,9 +375,6 @@ def test_local_dashboard_supports_mcp(temp_dir):
     )
 
     async def check_mcp() -> None:
-        from mcp import ClientSession
-        from mcp.client.streamable_http import streamable_http_client
-
         async with streamable_http_client(f"{url.rstrip('/')}/mcp") as (
             read_stream,
             write_stream,