From 5fb7d2f298b32e734fcab8c4ea40c8583b812630 Mon Sep 17 00:00:00 2001 From: Wauplin Date: Fri, 12 Jun 2026 13:58:30 +0200 Subject: [PATCH 1/4] docs: add SSH section to Jobs configuration guide Document the new --ssh / ssh=True option that opens an interactive SSH session into a running Job, plus the new `hf jobs ssh ` command (with --dry-run and -i/--identity-file). Includes CLI and Python examples, the ssh://@ssh.hf.jobs endpoint format, and access requirements (write access to the namespace + a registered SSH key). SSH is not billed on top of the job's hardware price. Complements #2551 which covers exposing ports. Co-Authored-By: Claude Opus 4.8 --- docs/hub/jobs-configuration.md | 45 ++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/docs/hub/jobs-configuration.md b/docs/hub/jobs-configuration.md index 1f398e295..18e2b357e 100644 --- a/docs/hub/jobs-configuration.md +++ b/docs/hub/jobs-configuration.md @@ -248,6 +248,51 @@ Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ... ['https://6a2ab384c4f53f9fc5aa4d4f--8000.hf.jobs'] ``` +## SSH + +You can open an interactive SSH session into a running Job to debug, inspect, or work directly inside the container. Enable it with `--ssh` (CLI) or `ssh=True` (Python API), then connect with `hf jobs ssh `. + +Only users with write access to the Job's namespace are allowed in (the Job creator, or members of the owner organization), authenticated by an SSH public key registered at [https://huggingface.co/settings/keys](https://huggingface.co/settings/keys). + +> [!NOTE] +> SSH access is **not billed** on top of the Job's hardware price. + +SSH is available on `hf jobs run` and `hf jobs uv run`. It is not supported for scheduled jobs. + +### CLI + +```bash +# Start a job with SSH enabled +>>> hf jobs run --ssh --detach --timeout 10m python:3.12 sleep infinity +✓ Job started + id: 6a2bd1f1871c005b5352ad31 + url: https://huggingface.co/jobs/Wauplin/6a2bd1f1871c005b5352ad31 +Hint: Use `hf jobs ssh 6a2bd1f1871c005b5352ad31` to open an SSH session into the job. + +# Open an SSH session into the job +>>> hf jobs ssh 6a2bd1f1871c005b5352ad31 +``` + +You can also print the SSH command without running it (`--dry-run`), or pass a specific identity file (`-i`/`--identity-file`): + +```bash +>>> hf jobs ssh 6a2bd1f1871c005b5352ad31 --dry-run +ssh 6a2bd1f1871c005b5352ad31@ssh.hf.jobs + +>>> hf jobs ssh 6a2bd1f1871c005b5352ad31 -i ~/.ssh/id_ed25519 +``` + +### Python + +```python +>>> from huggingface_hub import run_job +>>> job = run_job(image="python:3.12", command=["sleep", "infinity"], ssh=True) +>>> job.status.ssh_url +'ssh://6a2bd1f1871c005b5352ad31@ssh.hf.jobs' +``` + +Then connect from a terminal with `hf jobs ssh `, or directly with `ssh @ssh.hf.jobs`. + ## Timeout Jobs have a default timeout (30 minutes), after which they will automatically stop. This is important to know when running long-running tasks like model training. From 5d662dca93c09c4c80455c3787712d4113711cd1 Mon Sep 17 00:00:00 2001 From: Wauplin Date: Fri, 12 Jun 2026 14:10:49 +0200 Subject: [PATCH 2/4] better --- docs/hub/jobs-configuration.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/hub/jobs-configuration.md b/docs/hub/jobs-configuration.md index 18e2b357e..a3d858eed 100644 --- a/docs/hub/jobs-configuration.md +++ b/docs/hub/jobs-configuration.md @@ -250,12 +250,9 @@ Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ... ## SSH -You can open an interactive SSH session into a running Job to debug, inspect, or work directly inside the container. Enable it with `--ssh` (CLI) or `ssh=True` (Python API), then connect with `hf jobs ssh `. +You can open an interactive SSH session into a running Job to debug, inspect, or work directly inside the container. Enable it at job creation with `--ssh` (CLI) or `ssh=True` (Python API), then connect with `hf jobs ssh `. -Only users with write access to the Job's namespace are allowed in (the Job creator, or members of the owner organization), authenticated by an SSH public key registered at [https://huggingface.co/settings/keys](https://huggingface.co/settings/keys). - -> [!NOTE] -> SSH access is **not billed** on top of the Job's hardware price. +Only users with write access to the Job's namespace are allowed in (i.e. the Job creator, or members of the owner organization), authenticated by an SSH public key registered at [https://huggingface.co/settings/keys](https://huggingface.co/settings/keys). SSH is available on `hf jobs run` and `hf jobs uv run`. It is not supported for scheduled jobs. From 82d077d141c463dc8200498d27302a0033f1a6d2 Mon Sep 17 00:00:00 2001 From: Wauplin Date: Fri, 12 Jun 2026 14:49:55 +0200 Subject: [PATCH 3/4] docs: add SSH port forwarding section to Jobs guide Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/hub/jobs-configuration.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/hub/jobs-configuration.md b/docs/hub/jobs-configuration.md index a3d858eed..23547538e 100644 --- a/docs/hub/jobs-configuration.md +++ b/docs/hub/jobs-configuration.md @@ -290,6 +290,26 @@ ssh 6a2bd1f1871c005b5352ad31@ssh.hf.jobs Then connect from a terminal with `hf jobs ssh `, or directly with `ssh @ssh.hf.jobs`. +### Port forwarding + +Since this is a regular SSH connection, you can use SSH's `-L` and `-R` flags to forward ports between your machine and the Job. Connect directly with `ssh` (use `hf jobs ssh --dry-run` to get the exact destination) and add the forwarding flags. + +Use `-L` (local forwarding) to access a service running inside the Job from your machine. For example, to reach a TensorBoard started in a training Job: + +```bash +# Forward local port 6006 to the Job's TensorBoard on port 6006 +>>> ssh -L 6006:localhost:6006 6a2bd1f1871c005b5352ad31@ssh.hf.jobs +``` + +Then open [http://localhost:6006](http://localhost:6006) in your browser. + +Use `-R` (remote forwarding) to let the Job access a service running on your machine. For example, to expose a local database or API to the Job: + +```bash +# Make your local port 8080 reachable from inside the Job on port 8080 +>>> ssh -R 8080:localhost:8080 6a2bd1f1871c005b5352ad31@ssh.hf.jobs +``` + ## Timeout Jobs have a default timeout (30 minutes), after which they will automatically stop. This is important to know when running long-running tasks like model training. From cedb5fc48d458a3daf4f50416b9d643fc278c516 Mon Sep 17 00:00:00 2001 From: Lucain Date: Tue, 16 Jun 2026 08:45:34 +0200 Subject: [PATCH 4/4] Update docs/hub/jobs-configuration.md Co-authored-by: Pedro Cuenca --- docs/hub/jobs-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/hub/jobs-configuration.md b/docs/hub/jobs-configuration.md index 23547538e..98d5a1448 100644 --- a/docs/hub/jobs-configuration.md +++ b/docs/hub/jobs-configuration.md @@ -252,7 +252,7 @@ Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ... You can open an interactive SSH session into a running Job to debug, inspect, or work directly inside the container. Enable it at job creation with `--ssh` (CLI) or `ssh=True` (Python API), then connect with `hf jobs ssh `. -Only users with write access to the Job's namespace are allowed in (i.e. the Job creator, or members of the owner organization), authenticated by an SSH public key registered at [https://huggingface.co/settings/keys](https://huggingface.co/settings/keys). +Only users with Write access to the Job's namespace are allowed (i.e. the Job creator, or members of the owner organization with Write permissions). Authentication is performed via SSH public keys registered at [https://huggingface.co/settings/keys](https://huggingface.co/settings/keys). SSH is available on `hf jobs run` and `hf jobs uv run`. It is not supported for scheduled jobs.