Introduction

Welcome back, intrepid experimenter! So far, you’ve mastered tracking your machine learning experiments locally with Trackio, enjoying the simplicity of its Gradio dashboard right on your machine. But what if you need to share your progress with a teammate across the globe? Or perhaps you want to monitor a long-running experiment from your phone while away from your desk? That’s where remote syncing comes in!

In this chapter, we’ll unlock the power of Hugging Face Spaces to elevate your Trackio workflow. You’ll learn how to seamlessly push your local experiment data and its interactive dashboard to a remote Hugging Face Space. This integration transforms your local tracking into a collaborative, accessible, and persistent record of your ML journey. Get ready to share your insights with the world!

To get the most out of this chapter, ensure you’re comfortable with the basics of initializing Trackio runs and logging metrics, as covered in Chapters 3 and 4.

Core Concepts: Bridging Local to Cloud

Before we dive into the code, let’s understand the magic behind syncing Trackio with Hugging Face Spaces.

What is Hugging Face Spaces?

Hugging Face Spaces is a platform designed for hosting machine learning demos, applications, and now, experiment dashboards! Think of it as a place where you can deploy interactive web applications (often built with Gradio or Streamlit) that showcase your ML models or, in our case, visualize your experiment results. Each Space is essentially a Git repository that can host code and data, and Hugging Face handles the infrastructure to run your app.

Why Sync Trackio with Spaces?

Syncing your Trackio experiments to a Hugging Face Space offers several compelling advantages:

  1. Remote Accessibility: View your experiment dashboards from any web browser, anywhere, without needing your local machine running.
  2. Collaboration: Easily share live experiment results with teammates, collaborators, or the wider ML community. No more sharing screenshots or static reports!
  3. Persistent Storage: Your experiment data and dashboard persist on Hugging Face’s infrastructure, providing a reliable backup and historical record.
  4. Simplified Deployment: Trackio handles the complexities of setting up and updating a Gradio app on Spaces, so you can focus on your ML.

Trackio’s Spaces Integration Model

Trackio’s integration with Hugging Face Spaces is quite clever. When you enable Spaces syncing, Trackio essentially creates or updates a Hugging Face Space that hosts a Gradio application. This Gradio app is configured to read your experiment data (which Trackio also pushes to the Space’s repository) and render the familiar Trackio dashboard.

This means you’re not just pushing raw data; you’re pushing an interactive dashboard that anyone with the link can explore. Trackio manages the data syncing and the Gradio app updates, making the process almost transparent to you.

Authentication: Your Key to the Cloud

To interact with Hugging Face Spaces (create repositories, push changes), you’ll need to authenticate. This is done using a Hugging Face API token. It’s like a password for your programs to access your Hugging Face account. We’ll show you how to get and use this token securely.

Step-by-Step Implementation: Syncing Your First Experiment

Let’s get our hands dirty and sync a simple experiment to Hugging Face Spaces.

Step 1: Install huggingface_hub and Log In

Trackio leverages the huggingface_hub library to interact with Hugging Face’s services. Let’s make sure you have it installed and are logged in.

First, open your terminal or command prompt and install the library:

pip install huggingface_hub==0.20.0 # As of 2026-01-01, this is a stable recent version

(Note: The exact version might be slightly newer, but 0.20.0 is a good reference for stable features for 2026. Always check the official huggingface_hub documentation for the absolute latest stable release if you encounter issues.)

Next, you’ll need to log in to Hugging Face. This will prompt you to enter your Hugging Face API token.

huggingface-cli login

It will ask for your token. You can generate one from your Hugging Face profile settings under “Access Tokens.” Make sure it has “Write” permissions so Trackio can create and update your Spaces.

Pro-Tip: For production environments or CI/CD, it’s best practice to store your Hugging Face token as an environment variable (e.g., HF_TOKEN) rather than hardcoding it or passing it directly in scripts. Trackio will automatically pick it up if it’s set.

Step 2: Initialize a Trackio Run with Spaces Sync

Now, let’s modify a basic Trackio script to enable Spaces syncing. We’ll create a simple experiment that logs a dummy loss value over several steps.

Create a new Python file, say train_and_sync.py:

# train_and_sync.py

import trackio
import time
import random
import os

# --- Configuration for Hugging Face Spaces ---
# Replace 'YOUR_HF_USERNAME/my-first-trackio-space' with your desired repo ID.
# The `hf_repo_id` needs to be in the format 'username/space_name'.
# If the space doesn't exist, Trackio will attempt to create it.
HF_REPO_ID = "YOUR_HF_USERNAME/my-first-trackio-space"

# It's best practice to get the token from an environment variable for security.
# If not set, you can pass it directly (less secure for sharing scripts).
# trackio will also try to use the token from `huggingface-cli login`.
HF_TOKEN = os.getenv("HF_TOKEN") 

print(f"Attempting to sync to Hugging Face Space: {HF_REPO_ID}")

# --- Initialize Trackio with Spaces integration ---
# The `hf_repo_id` parameter tells Trackio where to sync your experiment.
# If `hf_token` is not provided, Trackio will look for it in environment variables
# or from `huggingface-cli login`.
run = trackio.init(project="my_hf_project", 
                   job_type="training", 
                   hf_repo_id=HF_REPO_ID,
                   hf_token=HF_TOKEN # Optional if HF_TOKEN env var is set or logged in
                   )

# --- Log some initial configuration ---
run.config.learning_rate = 0.01
run.config.epochs = 10
run.config.model_name = "SimpleLinear"

print("Starting experiment...")

# --- Simulate training loop ---
for epoch in range(run.config.epochs):
    loss = 1.0 / (epoch + 1) + random.uniform(-0.1, 0.1) # Simulate decreasing loss
    accuracy = 0.5 + (epoch * 0.05) + random.uniform(-0.02, 0.02) # Simulate increasing accuracy

    # Log metrics to Trackio
    run.log({"loss": loss, "accuracy": accuracy})
    print(f"Epoch {epoch+1}: Loss = {loss:.4f}, Accuracy = {accuracy:.4f}")

    time.sleep(2) # Simulate some work

print("Experiment finished. Finalizing Trackio run.")

# --- End the Trackio run ---
run.finish()

print("Trackio run finalized and synced to Hugging Face Spaces (if configured correctly).")

Explanation:

  • HF_REPO_ID = "YOUR_HF_USERNAME/my-first-trackio-space": This is the crucial part. You must replace "YOUR_HF_USERNAME" with your actual Hugging Face username. my-first-trackio-space is the name your Space will have. If a Space with this ID doesn’t exist, Trackio will attempt to create it for you.
  • HF_TOKEN = os.getenv("HF_TOKEN"): We’re retrieving the token from an environment variable. This is the recommended secure way. If you haven’t set HF_TOKEN as an environment variable, Trackio will try to use the token from huggingface-cli login.
  • trackio.init(..., hf_repo_id=HF_REPO_ID, hf_token=HF_TOKEN): By passing hf_repo_id to trackio.init(), you’re telling Trackio to not only track locally but also to push updates to this specific Hugging Face Space. The hf_token is passed for explicit authentication, though often Trackio can infer it.
  • run.log({"loss": loss, "accuracy": accuracy}): This is the same logging mechanism we used for local tracking. Trackio now intelligently handles pushing these updates to your designated Space.
  • run.finish(): It’s important to call finish() at the end of your script. This ensures all pending data is pushed and the run is properly concluded, both locally and on Spaces.

Step 3: Run the Script and Observe

Now, run your script from the terminal:

python train_and_sync.py

As the script runs, you’ll see output in your terminal. Trackio will print messages indicating that it’s syncing to Hugging Face.

Initially, Trackio might take a moment to set up the Space (if it’s new) and deploy the Gradio app. Once it’s deployed, you’ll see a message like:

Trackio dashboard available at: https://huggingface.co/spaces/YOUR_HF_USERNAME/my-first-trackio-space

Copy this URL and open it in your web browser. You should see your Trackio dashboard, live and updating as your script progresses!

What to observe:

  • A new public (by default) Hugging Face Space will be created under your account.
  • The Space will host a Gradio application.
  • The Gradio application will display the Trackio dashboard, showing the “loss” and “accuracy” metrics plotting in real-time.
  • You can share this URL with anyone, and they can view your experiment results.

Mini-Challenge: Track a Custom Metric

Let’s put your understanding to the test.

Challenge: Modify the train_and_sync.py script to simulate tracking a third metric: val_loss. This metric should also generally decrease, but perhaps with more fluctuation. Log both loss and val_loss in each step. Ensure the val_loss also appears on your remote Hugging Face Spaces dashboard.

Hint: Remember that run.log() can take a dictionary of multiple metrics. Just add val_loss to the dictionary you pass to run.log().

What to observe/learn: After running the modified script, refresh your Hugging Face Space dashboard. You should now see three different plots: loss, accuracy, and val_loss. This demonstrates how easily you can extend your remote tracking to include any relevant data.

Common Pitfalls & Troubleshooting

Even with the best intentions, things can sometimes go sideways. Here are a few common issues you might encounter when syncing with Hugging Face Spaces:

  1. Authentication Errors (HuggingFaceHubException or HTTPError 401):

    • Problem: You’re not logged in, or your token is invalid/lacks sufficient permissions.
    • Solution:
      • Run huggingface-cli login again and ensure you paste the correct token.
      • Verify your token has “Write” permissions in your Hugging Face settings.
      • If using an environment variable, double-check its name (HF_TOKEN) and value.
      • Ensure your HF_REPO_ID is correctly formatted as username/space_name.

  2. Spaces Not Updating or Not Found:

    • Problem: Your local script runs, but the remote dashboard doesn’t show updates, or the Space URL doesn’t work.
    • Solution:
      • Network Connectivity: Ensure your machine has a stable internet connection.
      • Correct hf_repo_id: Double-check that the HF_REPO_ID in your script matches the actual Space ID you intend to use or create. A typo will cause issues.
      • Space Deployment Time: If it’s a new Space, it might take a few minutes for Hugging Face to build and deploy the Gradio app. Be patient! Check the “Logs” tab on your Space’s page on Hugging Face for deployment status.
      • run.finish() Called: Make sure run.finish() is called at the end of your script to ensure all buffered data is pushed.
      • Space Status: Visit your Space on Hugging Face. Is it running? Is it stuck in “Building” or “Error” state? The logs there will be your best friend.

  3. Permission Denied when Creating a Space:

    • Problem: Trackio tries to create a new Space, but you get a permission error.
    • Solution:
      • Your Hugging Face token might not have the necessary permissions to create new repositories/Spaces. Ensure it has “Write” access.
      • The HF_REPO_ID might be invalid (e.g., using special characters not allowed in repo names).

Summary

Congratulations! You’ve successfully extended your Trackio capabilities to the cloud by integrating with Hugging Face Spaces.

Here are the key takeaways from this chapter:

  • Hugging Face Spaces provides a robust platform for hosting your interactive ML dashboards.
  • Trackio’s integration enables seamless syncing of your local experiment data and its Gradio dashboard to a remote Space.
  • Authentication via a Hugging Face API token with “Write” permissions is essential for this process.
  • You enable Spaces syncing by passing the hf_repo_id parameter to trackio.init().
  • Your remote dashboard provides accessibility, collaboration, and persistent storage for your experiments.
  • Troubleshooting often involves checking authentication, hf_repo_id correctness, and Space deployment status on Hugging Face.

In the next chapter, we’ll delve into managing your Trackio experiment data, including database management, backups, and exploring advanced customization options to tailor Trackio even further to your needs.

References

This page is AI-assisted and reviewed. It references official documentation and recognized resources where relevant.