README.md

---
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](https://huggingface.co/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:

```dockerfile
# 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:

```python
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](https://huggingface.co/settings/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:

```bash
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:

```bash
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:

```json
{
    "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:

```bash
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:

```bash
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:

```txt
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"}
```