Running Workloads on Hugging Face Jobs

Detailed Guide

Read the detailed guide before executing this skill. It retains the complete procedure and reference material. Treat its safety, prerequisites, and validation requirements as mandatory. For focused work, load the relevant sections; for end-to-end work, read the guide completely.

When to Use This Skill

Use this skill when users want to:

• Run Python workloads on cloud infrastructure
• Execute jobs without local GPU/TPU setup
• Process data at scale
• Run batch inference or experiments
• Schedule recurring tasks
• Use GPUs/TPUs for any workload
• Persist results to the Hugging Face Hub

Prerequisites Checklist

Before starting any job, verify:

✅ Account & Authentication

• Hugging Face Account with Pro, Team, or Enterprise plan (Jobs require paid plan)
• Authenticated login: Check with hf_whoami()
• HF_TOKEN for Hub Access ⚠️ CRITICAL - Required for any Hub operations (push models/datasets, download private repos, etc.)
• Token must have appropriate permissions (read for downloads, write for uploads)

✅ Token Usage (See Token Usage section for details)

When tokens are required:

• Pushing models/datasets to Hub
• Accessing private repositories
• Using Hub APIs in scripts
• Any authenticated Hub operations

How to provide tokens:

# hf_jobs MCP tool — $HF_TOKEN is auto-replaced with real token:
{"secrets": {"HF_TOKEN": "$HF_TOKEN"}}

# HfApi().run_uv_job() — MUST pass actual token:
from huggingface_hub import get_token
secrets={"HF_TOKEN": get_token()}

⚠️ CRITICAL: The $HF_TOKEN placeholder is ONLY auto-replaced by the hf_jobs MCP tool. When using HfApi().run_uv_job(), you MUST pass the real token via get_token(). Passing the literal string "$HF_TOKEN" results in a 9-character invalid token and 401 errors.

Token Usage Guide

Understanding Tokens

What are HF Tokens?

• Authentication credentials for Hugging Face Hub
• Required for authenticated operations (push, private repos, API access)
• Stored securely on your machine after hf auth login

Token Types:

• Read Token - Can download models/datasets, read private repos
• Write Token - Can push models/datasets, create repos, modify content
• Organization Token - Can act on behalf of an organization

When Tokens Are Required

Always Required:

• Pushing models/datasets to Hub
• Accessing private repositories
• Creating new repositories
• Modifying existing repositories
• Using Hub APIs programmatically

Not Required:

• Downloading public models/datasets
• Running jobs that don't interact with Hub
• Reading public repository information

How to Provide Tokens to Jobs

Method 1: Automatic Token (Recommended)

hf_jobs("uv", {
    "script": "your_script.py",
    "secrets": {"HF_TOKEN": "$HF_TOKEN"}  # ✅ Automatic replacement
})

How it works:

• $HF_TOKEN is a placeholder that gets replaced with your actual token
• Uses the token from your logged-in session (hf auth login)
• Most secure and convenient method
• Token is encrypted server-side when passed as a secret

Benefits:

• No token exposure in code
• Uses your current login session
• Automatically updated if you re-login
• Works seamlessly with MCP tools

Method 2: Explicit Token (Not Recommended)

hf_jobs("uv", {
    "script": "your_script.py",
    "secrets": {"HF_TOKEN": "hf_abc123..."}  # ⚠️ Hardcoded token
})

When to use:

• Only if automatic token doesn't work
• Testing with a specific token
• Organization tokens (use with caution)

Security concerns:

• Token visible in code/logs
• Must manually update if token rotates
• Risk of token exposure

Method 3: Environment Variable (Less Secure)

hf_jobs("uv", {
    "script": "your_script.py",
    "env": {"HF_TOKEN": "hf_abc123..."}  # ⚠️ Less secure than secrets
})

Difference from secrets:

• env variables are visible in job logs
• secrets are encrypted server-side
• Always prefer secrets for tokens

Using Tokens in Scripts

In your Python script, tokens are available as environment variables:

# /// script
# dependencies = ["huggingface-hub"]
# ///

import os
from huggingface_hub import HfApi

# Token is automatically available if passed via secrets
token = os.environ.get("HF_TOKEN")


…