docs/ENVIRONMENT_VARIABLES.md

🔧 Trackio Environment Variables Reference

Quick Setup

Set these environment variables in your Hugging Face Space:

# Required: Your HF token for dataset access
HF_TOKEN=your_hf_token_here

# Optional: Dataset repository to use (defaults to tonic/trackio-experiments)
TRACKIO_DATASET_REPO=your-username/your-dataset-name

Environment Variables

Variable	Required	Default	Description
HF_TOKEN	✅ Yes	None	Your Hugging Face token for dataset access
TRACKIO_DATASET_REPO	❌ No	tonic/trackio-experiments	Dataset repository to load experiments from
SPACE_ID	🔄 Auto	None	HF Space ID (automatically detected)

Configuration Examples

1. Default Setup

HF_TOKEN=your_token_here
# Uses: tonic/trackio-experiments

2. Personal Dataset

HF_TOKEN=your_token_here
TRACKIO_DATASET_REPO=your-username/trackio-experiments

3. Team Dataset

HF_TOKEN=your_token_here
TRACKIO_DATASET_REPO=your-org/team-experiments

4. Project-Specific Dataset

HF_TOKEN=your_token_here
TRACKIO_DATASET_REPO=your-username/smollm3-experiments

How to Set in HF Spaces

1. Go to your Hugging Face Space settings
2. Navigate to "Settings" → "Environment variables"
3. Add the variables:
   • HF_TOKEN: Your HF token
   • TRACKIO_DATASET_REPO: Your dataset repository (optional)

Testing Configuration

Run the configuration script to check your setup:

python configure_trackio.py

This will:

• ✅ Show current environment variables
• 🧪 Test dataset access
• 📊 Display experiment count
• 💾 Generate configuration file

Getting Your HF Token

1. Go to Hugging Face Settings
2. Click "New token"
3. Give it a name (e.g., "Trackio Access")
4. Select "Write" permissions
5. Copy the token and set it as HF_TOKEN

Dataset Repository Format

The TRACKIO_DATASET_REPO should follow this format:

username/dataset-name

Examples:

• tonic/trackio-experiments
• your-username/my-experiments
• your-org/team-experiments

Troubleshooting

Issue: "HF_TOKEN not found"

Solution: Set your HF token in the Space environment variables

Issue: "Failed to load dataset"

Solutions:

1. Check your token has read access to the dataset
2. Verify the dataset repository exists
3. Try the backup fallback (automatic)

Issue: "Failed to save experiments"

Solutions:

1. Check your token has write permissions
2. Verify the dataset repository exists
3. Check network connectivity

Security Notes

• 🔒 Dataset is private by default
• 🔑 Only accessible with your HF_TOKEN
• 🛡️ No sensitive data exposed publicly
• 🔐 Secure storage on HF infrastructure