docs: add expose ports section to Jobs configuration guide (#2551)

* docs: add expose ports section to Jobs configuration guide

Document the new --expose / expose=[] option that lets users expose
container ports through the public jobs proxy (available since
huggingface_hub v1.19.0). Includes CLI and Python examples, URL
format, and authentication requirements.

Complements #2550 which covers pricing.

Co-authored-by: Lucain <Wauplin@users.noreply.github.com>

* nit

* bit

* revert

* nit

* docs: add Sandboxes section to Jobs examples page

Mention that expose ports makes Jobs a great fit for building
sandboxes (temporary self-contained environments for agents and
LLM applications).

Co-authored-by: Lucain <Wauplin@users.noreply.github.com>

* Update docs/hub/jobs-configuration.md

Co-authored-by: Daniel van Strien <davanstrien@users.noreply.github.com>

* Update docs/hub/jobs-configuration.md

Co-authored-by: Daniel van Strien <davanstrien@users.noreply.github.com>

* Update docs/hub/jobs-configuration.md

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Lucain <Wauplin@users.noreply.github.com>
Co-authored-by: Daniel van Strien <davanstrien@users.noreply.github.com>

Author: 3 people

docs/hub/jobs-configuration.md

@@ -213,6 +213,41 @@ l40sx4           4x Nvidia L40S          48 vCPU   382 GB   3200 GB   4x L40S (1
 l40sx8           8x Nvidia L40S          192 vCPU  1534 GB  6500 GB   8x L40S (384 GB)          $0.3917   $23.50
 ```
 
+## Expose Ports
+
+Jobs can expose container ports through the public jobs proxy using `--expose <port>` (CLI) or `expose=[<port>]` (Python API). Each exposed port is reachable at `https://<job_id>--<port>.hf.jobs` and requires an HF token with `read` access to the job's namespace:
+
+```bash
+curl -H "Authorization: Bearer $HF_TOKEN" https://<job_id>--<port>.hf.jobs/
+```
+
+This works on `hf jobs run`, `hf jobs uv run`, and their scheduled variants. Repeat the flag to expose multiple ports (`--expose 8000 --expose 8001`), or pass several ports in the list (`expose=[8000, 8001]`).
+
+> [!NOTE]
+> Exposed ports are billed at a small flat hourly rate on top of the job's hardware price, only while the job is running. See the [pricing page](./jobs-pricing) for details.
+
+### CLI
+
+```bash
+# Expose a web server running on port 8000
+>>> hf jobs run --expose 8000 python:3.12 python -m http.server 8000
+✓ Job started
+  id: 6a2aa7cec4f53f9fc5aa4cff
+  url: https://huggingface.co/jobs/Wauplin/6a2aa7cec4f53f9fc5aa4cff
+Hint: Exposed ports are reachable at (requires an HF token with read access to the job):
+  https://6a2aa7cec4f53f9fc5aa4cff--8000.hf.jobs
+Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...
+```
+
+### Python
+
+```python
+>>> from huggingface_hub import run_job
+>>> job = run_job(image="python:3.12", command=["python", "-m", "http.server", "8000"], expose=[8000])
+>>> job.status.expose_urls
+['https://6a2ab384c4f53f9fc5aa4d4f--8000.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.

docs/hub/jobs-examples.md

@@ -27,6 +27,10 @@ The [uv-scripts](https://huggingface.co/uv-scripts) organization maintains a col
 
 The [hugging-face-jobs skill](https://github.com/huggingface/skills/tree/main/skills/hugging-face-jobs) lets coding agents like Claude Code and Cursor submit and monitor Jobs directly from your editor.
 
+## Sandboxes
+
+The [expose ports](./jobs-configuration#expose-ports) feature of Jobs makes them a great fit for building sandboxes, i.e. temporary self-contained environments used by agents and LLM applications.
+
 ## Community Tutorials and Projects
 
 - [Train on massive datasets without downloading](https://danielvanstrien.xyz/posts/2026/hf-streaming-unsloth/train-massive-datasets-without-downloading.html) - Stream datasets directly on Jobs with Unsloth, no local storage needed