Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions docs/source/en/guides/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -2100,6 +2100,23 @@ By default `hf jobs ps` displays at most 100 Jobs to avoid bloating the terminal
>>> hf jobs ps -a --limit 0
```

### Expose Job ports

Use `--expose` for a token-protected port and `--expose-public` for a port that should allow unauthenticated access. Both flags can be repeated and combined, and work with Docker, UV, and scheduled Jobs.

```bash
# Start a Job with a public HTTP server
>>> hf jobs run --detach --expose-public 8000 python:3.12 python -m http.server 8000

# Replace the configuration on a running Job: port 8000 is private, 9000 is public
>>> hf jobs expose <job_id> 8000 --public 9000

# Close all exposed ports
>>> hf jobs expose <job_id> --clear
```

`hf jobs expose` takes token-protected ports as positional arguments and public ports with `--public`. It applies the change without rerunning the Job. Ports omitted from the replacement list are closed.

### SSH into a Job

Pass `--ssh` to `hf jobs run` (or `hf jobs uv run`) to make the Job's container reachable over SSH, then connect with `hf jobs ssh`:
Expand Down
23 changes: 23 additions & 0 deletions docs/source/en/guides/jobs.md
Original file line number Diff line number Diff line change
Expand Up @@ -349,6 +349,29 @@ In the CLI, simply pass a local directory as the source side of `-v`:
>>> hf jobs uv run -v ./pdfs:/input -v ./md-out:/output:rw ocr.py
```

## Expose Job ports

Pass `expose` to make a container port reachable through the Jobs proxy. Access requires an HF token with read access to the Job's namespace. Use `expose_public` instead to allow access without authentication:

```python
>>> from huggingface_hub import run_job, update_job_expose
>>> job = run_job(
... image="python:3.12",
... command=["python", "-m", "http.server", "8000"],
... expose_public=[8000],
... )
>>> job.expose_public
[8000]

# Keep the port exposed, but require an HF token from now on
>>> job = update_job_expose(job_id=job.id, expose=[8000])

# Close all exposed ports
>>> job = update_job_expose(job_id=job.id)
```

`expose` and `expose_public` can be combined. `update_job_expose` replaces the full port configuration on a running Job without restarting it: ports that are in neither list are closed. Both options are also available when creating UV and scheduled Jobs.

## SSH into a Job

Pass `ssh=True` to [`run_job`] (or [`run_uv_job`]) to make the Job's container reachable over SSH. The SSH endpoint is available in the Job status:
Expand Down
38 changes: 38 additions & 0 deletions docs/source/en/package_reference/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -2278,6 +2278,7 @@ $ hf jobs [OPTIONS] COMMAND [ARGS]...
**Commands**:

* `cancel`: Cancel a Job
* `expose`: Replace exposed ports on a running Job.
* `hardware`: List available hardware options for Jobs
* `inspect`: Display detailed information on one or more Jobs
* `labels`: Update labels on a Job.
Expand Down Expand Up @@ -2318,6 +2319,39 @@ Learn more
Read the documentation at https://huggingface.co/docs/huggingface_hub/en/guides/cli


### `hf jobs expose`

Replace exposed ports on a running Job.

**Usage**:

```console
$ hf jobs expose [OPTIONS] JOB_ID [PORTS]...
```

**Arguments**:

* `JOB_ID`: Job ID (or 'namespace/job_id') [required]
* `[PORTS]...`: Ports to expose through the jobs proxy. Access requires an HF token with read access to the job's namespace.

**Options**:

* `--public INTEGER`: Expose a port without authentication. Repeat the flag for multiple ports. No need to also pass the port as a positional argument.
* `--clear`: Close all exposed ports.
* `--namespace TEXT`: The namespace where the job will be running. Defaults to the current user's namespace.
* `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens.
* `--help`: Show this message and exit.

Examples
$ hf jobs expose <job_id> 8000
$ hf jobs expose <job_id> 8000 --public 9000
$ hf jobs expose <job_id> --clear

Learn more
Use `hf <command> --help` for more information about a command.
Read the documentation at https://huggingface.co/docs/huggingface_hub/en/guides/cli


### `hf jobs hardware`

List available hardware options for Jobs
Expand Down Expand Up @@ -2507,6 +2541,7 @@ $ hf jobs run [OPTIONS] IMAGE COMMAND...
* `-d, --detach`: Run the Job in the background and print the Job ID.
* `--dry-run`: Print the resolved Job configuration without submitting the Job.
* `--expose INTEGER`: Expose a container port through the jobs proxy. Repeat the flag for multiple ports (e.g. `--expose 8000 --expose 8001`). Each exposed port is reachable on the public jobs domain; access requires an HF token with read access to the job's namespace.
* `--expose-public INTEGER`: Expose a container port through the jobs proxy without authentication. Repeat the flag for multiple ports. No need to also pass the port with `--expose`.
* `--ssh`: Make the job's container reachable over SSH. Connect with `hf jobs ssh <job_id>`. Requires an SSH public key registered on https://huggingface.co/settings/keys.
* `--network-group TEXT`: Join a network group. Jobs in the same namespace and resource group sharing a group are placed together and reach each other on every port. Inside each member, `$HF_NETWORK_GROUP_HOSTNAME` resolves to every member. Lowercase alphanumerics and dashes, 46 characters max.
* `--network-alias TEXT`: Claim an alias in the network group. Members reach the jobs claiming it at `${HF_NETWORK_GROUP_PREFIX}<alias>`. Repeat the flag for several aliases. Lowercase alphanumerics and dashes, 34 characters max, unique within the job. Requires `--network-group`.
Expand Down Expand Up @@ -2739,6 +2774,7 @@ $ hf jobs scheduled run [OPTIONS] SCHEDULE IMAGE COMMAND...
* `--timeout TEXT`: Max duration: int with s (seconds, default), m (minutes), h (hours) or d (days).
* `--dry-run`: Print the resolved Job configuration without submitting the Job.
* `--expose INTEGER`: Expose a container port through the jobs proxy. Repeat the flag for multiple ports (e.g. `--expose 8000 --expose 8001`). Each exposed port is reachable on the public jobs domain; access requires an HF token with read access to the job's namespace.
* `--expose-public INTEGER`: Expose a container port through the jobs proxy without authentication. Repeat the flag for multiple ports. No need to also pass the port with `--expose`.
* `--resource-group-id TEXT`: The ID of the resource group to create the Job in. Used to control access to resources within an organization and for cost attribution/spending-limit features.
* `--namespace TEXT`: The namespace where the job will be running. Defaults to the current user's namespace.
* `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens.
Expand Down Expand Up @@ -2861,6 +2897,7 @@ $ hf jobs scheduled uv run [OPTIONS] SCHEDULE SCRIPT [SCRIPT_ARGS]...
* `--timeout TEXT`: Max duration: int with s (seconds, default), m (minutes), h (hours) or d (days).
* `--dry-run`: Print the resolved Job configuration without submitting the Job.
* `--expose INTEGER`: Expose a container port through the jobs proxy. Repeat the flag for multiple ports (e.g. `--expose 8000 --expose 8001`). Each exposed port is reachable on the public jobs domain; access requires an HF token with read access to the job's namespace.
* `--expose-public INTEGER`: Expose a container port through the jobs proxy without authentication. Repeat the flag for multiple ports. No need to also pass the port with `--expose`.
* `--resource-group-id TEXT`: The ID of the resource group to create the Job in. Used to control access to resources within an organization and for cost attribution/spending-limit features.
* `--namespace TEXT`: The namespace where the job will be running. Defaults to the current user's namespace.
* `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens.
Expand Down Expand Up @@ -2992,6 +3029,7 @@ $ hf jobs uv run [OPTIONS] SCRIPT [SCRIPT_ARGS]...
* `-d, --detach`: Run the Job in the background and print the Job ID.
* `--dry-run`: Print the resolved Job configuration without submitting the Job.
* `--expose INTEGER`: Expose a container port through the jobs proxy. Repeat the flag for multiple ports (e.g. `--expose 8000 --expose 8001`). Each exposed port is reachable on the public jobs domain; access requires an HF token with read access to the job's namespace.
* `--expose-public INTEGER`: Expose a container port through the jobs proxy without authentication. Repeat the flag for multiple ports. No need to also pass the port with `--expose`.
* `--ssh`: Make the job's container reachable over SSH. Connect with `hf jobs ssh <job_id>`. Requires an SSH public key registered on https://huggingface.co/settings/keys.
* `--network-group TEXT`: Join a network group. Jobs in the same namespace and resource group sharing a group are placed together and reach each other on every port. Inside each member, `$HF_NETWORK_GROUP_HOSTNAME` resolves to every member. Lowercase alphanumerics and dashes, 46 characters max.
* `--network-alias TEXT`: Claim an alias in the network group. Members reach the jobs claiming it at `${HF_NETWORK_GROUP_PREFIX}<alias>`. Repeat the flag for several aliases. Lowercase alphanumerics and dashes, 34 characters max, unique within the job. Requires `--network-group`.
Expand Down
3 changes: 3 additions & 0 deletions src/huggingface_hub/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -361,6 +361,7 @@
"update_collection_metadata",
"update_collection_resource_group",
"update_inference_endpoint",
"update_job_expose",
"update_job_labels",
"update_repo_settings",
"update_scheduled_job_labels",
Expand Down Expand Up @@ -1137,6 +1138,7 @@
"update_collection_metadata",
"update_collection_resource_group",
"update_inference_endpoint",
"update_job_expose",
"update_job_labels",
"update_repo_settings",
"update_scheduled_job_labels",
Expand Down Expand Up @@ -1555,6 +1557,7 @@ def __dir__():
update_collection_metadata, # noqa: F401
update_collection_resource_group, # noqa: F401
update_inference_endpoint, # noqa: F401
update_job_expose, # noqa: F401
update_job_labels, # noqa: F401
update_repo_settings, # noqa: F401
update_scheduled_job_labels, # noqa: F401
Expand Down
29 changes: 25 additions & 4 deletions src/huggingface_hub/_jobs_api.py
Original file line number Diff line number Diff line change
Expand Up @@ -227,16 +227,20 @@ class JobInfo:
initiator (`JobInitiator` or `None`):
What triggered the Job, e.g. `JobInitiator(type="scheduled-job", id="...")` for a cron-triggered run.
expose_urls (`list[str]` or `None`):
Public URLs through which the Job's exposed ports are reachable (one per port exposed via `expose=`),
Public URLs through which the Job's exposed ports are reachable (one per exposed port),
e.g. `["https://687fb701029421ae5549d998--8000.hf.jobs"]`. `None` when no port is exposed.
Accessing a URL requires an HF token with read access to the Job's namespace.
Accessing a URL requires an HF token with read access to the Job's namespace, unless the port is public.
ssh_url (`str` or `None`):
SSH endpoint of the Job, e.g. `"ssh://687fb701029421ae5549d998@ssh.hf.jobs"`. Only present when the Job
was started with `ssh=True`. Connecting requires write access to the Job's namespace and an SSH public
key registered on the Hub (https://huggingface.co/settings/keys).
network (`JobNetwork` or `None`):
Network group the Job joined and the aliases it claims, e.g. `JobNetwork(group="train", aliases=["master"])`.
`None` when the Job was started without `network_group=`.
expose (`list[int]` or `None`):
All ports exposed through the Jobs proxy, public ones included.
expose_public (`list[int]` or `None`):
Exposed ports reachable without authentication.

Example:

Expand Down Expand Up @@ -275,6 +279,8 @@ class JobInfo:
owner: JobOwner
initiator: JobInitiator | None
network: JobNetwork | None
expose: list[int] | None
expose_public: list[int] | None

# Inferred fields
endpoint: str
Expand Down Expand Up @@ -315,6 +321,9 @@ def __init__(self, **kwargs) -> None:
)
network = kwargs.get("network")
self.network = JobNetwork(**network) if network else None
expose = kwargs.get("expose") or {}
self.expose = expose.get("ports")
self.expose_public = expose.get("portsPublic")

# Inferred fields
self.endpoint = kwargs.get("endpoint", constants.ENDPOINT)
Expand All @@ -335,6 +344,8 @@ class JobSpec:
arch: str | None
labels: dict[str, str] | None
volumes: list[Volume] | None
expose: list[int] | None
expose_public: list[int] | None

def __init__(self, **kwargs) -> None:
self.docker_image = kwargs.get("dockerImage") or kwargs.get("docker_image")
Expand All @@ -350,6 +361,9 @@ def __init__(self, **kwargs) -> None:
self.labels = kwargs.get("labels")
volumes = kwargs.get("volumes")
self.volumes = [Volume(**v) for v in volumes] if volumes else None
expose = kwargs.get("expose") or {}
self.expose = expose.get("ports")
self.expose_public = expose.get("portsPublic")


@dataclass
Expand Down Expand Up @@ -606,6 +620,12 @@ def _default_job_name_from_script(
return f"{base}-{_short_invocation_hash([script, *script_args, *(config_parts or [])])}"


def _build_expose_payload(expose: list[int] | None, expose_public: list[int] | None) -> dict[str, list[int]]:
# Public ports are exposed too: the server expects them in both lists (`portsPublic` must be a subset of `ports`).
ports_public = list(dict.fromkeys(expose_public or []))
return {"ports": list(dict.fromkeys([*(expose or []), *ports_public])), "portsPublic": ports_public}


def _create_job_spec(
*,
image: str,
Expand All @@ -618,6 +638,7 @@ def _create_job_spec(
labels: dict[str, str] | None = None,
volumes: list[Volume] | None = None,
expose: list[int] | None = None,
expose_public: list[int] | None = None,
ssh: bool = False,
network_group: str | None = None,
network_aliases: list[str] | None = None,
Expand Down Expand Up @@ -654,8 +675,8 @@ def _create_job_spec(
if volumes:
job_spec["volumes"] = [vol.to_dict() for vol in volumes]
# expose ports through the jobs proxy
if expose:
job_spec["expose"] = {"ports": expose}
if expose or expose_public:
job_spec["expose"] = _build_expose_payload(expose, expose_public)
# make the job container reachable over SSH
if ssh:
job_spec["ssh"] = {"enabled": True}
Expand Down
Loading
Loading