README.md

metadata

title: Run Hello World
emoji: 👀
colorFrom: pink
colorTo: yellow
sdk: docker
pinned: false

Getting Started with the Jobs API

The Jobs API allows users to execute scripts remotely. The key concept is simple: you write a script, host it in a dedicated space, and then any user can execute it as a job with their arguments. Let's walk through the setup step by step.

Creating a Space

To begin, you'll need to create a space to host your script. Follow these steps:

1. Visit Hugging Face Spaces.
2. Click on New Space.
3. Name your space (e.g., run-hello-world).
4. Select Docker as the space type.
5. Choose the Blank template.
6. For hardware, select CPU basic • 2vCPU • 16GB FREE (note: this does not limit the resources used when running jobs).
7. Set visibility to Public.

Once created, your space will contain two default files: README.md and .gitattributes. To make it functional for running jobs, you need to add two more files: Dockerfile and run_job.py.

Setting Up the Environment

The Dockerfile defines the environment in which your script will run. Below is the simplest version to get started:

# Use a lightweight Python image as the base
FROM python:3.11-slim

# Set the working directory inside the container
WORKDIR /app

# Copy all files to the container
COPY . /app

Writing the Job Script

The second required file is run_job.py, which contains the script you want to execute. To start, create a simple script that prints a message:

print("Hello, world!")

At this stage, your space will display a Runtime error. This is expected since no application has been defined yet. However, this is not an issue as we don’t need one for job execution. You can add an application later if you want to provide a user-friendly interface for managing jobs.

Running a Job

Step 1: Create an API Token

Before launching a job, you need to create a dedicated token for job execution. This token identifies the user requesting the job, ensures access permissions, and handles billing if necessary.

1. Go to Hugging Face Tokens.
2. Click on Create new token.
3. Give it a name of your choice.
4. Select the permission Start and manage Jobs on your behalf.
5. Click Create token.
6. Copy the token and store it securely. Do not share it with anyone.

Step 2: Execute a Job

Open a terminal and run the following command:

curl -L 'https://huggingface.co/api/jobs/<username>' \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Bearer <token>' \
     -d '{
         "spaceId": "<space-id>",
         "command": ["python", "<script-name>.py"],
         "arguments": ["--arg1", "value1", "--arg2", "value2"],
         "environment": {"ENV_VAR1": "value1", "ENV_VAR2": "value2"},
         "flavor": "<flavor>"
     }'

Let's break down the command:

• -L 'https://huggingface.co/api/jobs/<username>': API endpoint to launch a job. Replace <username> with your Hugging Face username.
• -H 'Authorization: Bearer <token>': The token you created earlier, used for authentication and permission verification.
• -d '{...}': The body of the request, containing job parameters:
  • spaceId: The identifier of your space (e.g., qgallouedec/run-hello-world).
  • command: The command to execute. Here, we run a Python script: ["python", "run_job.py"].
  • arguments: Optional arguments for the script. If none are needed, use an empty array: [].
  • environment: Environment variables for the job. If none are needed, use {}.
  • flavor: The type of machine to run the job on. Available options include cpu-basic, cpu-upgrade, t4-small, t4-medium, a10g-small, a10g-large, a10g-largex2, a10glargex4, a100-large, h100, h100x8, l4x4, l4x1, l40sx1, l40sx4, l40sx8.

In my example, the command would look like this:

curl -L 'https://huggingface.co/api/jobs/qgallouedec' \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Bearer hf_MyTokenIsSecret' \
     -d '{
        "spaceId": "qgallouedec/run-hello-world",
        "command": ["python", "run_job.py"],
        "arguments": [],
        "environment": {},
        "flavor": "cpu-basic" 
}'

In the above example, the namespace of the space (qgallouedec) matches the username of the person who launch the job. However, this is usually not always the case, as users can launch jobs from spaces created by others.

Step 3: Interpreting the Response

Once the job is launched, you'll receive a response like this:

{
    "metadata": {
        "job_id": "-FZNr5FTonBJJ8F2ENXnDQ5SY",
        "owner": {"id": "631ce4b244503b72277fc89f", "name": "qgallouedec"}
    },
    "spec": {
        "input": {"spaceId": "qgallouedec/run-hello-world"},
        "timeout": null,
        "env": {},
        "command": ["python", "run_job.py"],
        "args": [],
        "flavor": "cpu-basic",
        "owner": {"id": "631ce4b244503b72277fc89f", "name": "qgallouedec"}
    },
    "status": {
        "stage": "RUNNING",
        "error": null,
        "message": null,
        "abuse": {"flagged": false, "reason": "", "detector": "", "at": "2025-03-17T00:22:06.432Z"}
    }
}

The most important field here is job_id (-FZNr5FTonBJJ8F2ENXnDQ5SY), which allows you to track the job's progress and access logs to verify execution.

Monitoring Job Progress

To monitor the job's progress, you can use the following command:

curl -L 'https://huggingface.co/api/jobs/<username>/<job_id>/logs-stream' \
     -H 'Authorization: Bearer <token>'

In my case, the command would look like this:

curl -L 'https://huggingface.co/api/jobs/qgallouedec/-FZNr5FTonBJJ8F2ENXnDQ5SY/logs-stream' \
     -H 'Authorization: Bearer hf_MyTokenIsSecret'

And you'll receive a stream of logs like this:

data: {"data":"===== Job started at 2025-03-17 00:22:06 =====","timestamp":"2025-03-17T00:22:06Z"}

data: {"data":"Hello, world!","timestamp":"2025-03-17T00:22:08.836Z"}