Skip to content

[Jobs] Manage public and private exposed ports - #5027

Merged
Wauplin merged 7 commits into
mainfrom
codex/jobs-expose-ports
Sep 29, 2026
Merged

Wauplin merged 7 commits into
mainfrom
codex/jobs-expose-ports

Conversation

@Wauplin

@Wauplin Wauplin commented Sep 28, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

  • Add expose_public and --expose-public when creating Docker, UV, or scheduled Jobs. The server accepts portsPublic at creation; the client previously sent only token-protected ports.
  • Add update_job_expose and hf jobs expose <job_id> [PORTS]... [--public PORT] to replace ports on a running Job. --clear closes all exposed ports.
  • Expose the current private/public port lists on JobInfo and scheduled JobSpec, and document both modes.

expose (token-protected) and expose_public (unauthenticated) are independent: a public port does not need to be listed in expose too. The server requires portsPublic to be a subset of ports (it returns 400 portsPublic must be a subset of ports otherwise), but that is a wire-format detail. The client merges public ports into ports before sending, so users don't have to repeat themselves (--expose-public 8000 instead of --expose 8000 --expose-public 8000). On JobInfo, expose still reflects the server's ports field, which means it lists all exposed ports, public ones included.

hf jobs expose takes token-protected ports as positional arguments and public ports with --public (hf jobs expose <job_id> 8000 --public 9000). The command name already says "expose", so hf jobs expose <job_id> --expose 8000 --expose-public 9000 would repeat it. hf jobs run keeps --expose / --expose-public, because there the flags sit next to many unrelated options.

update_job_expose replaces the full configuration, as required by the endpoint: ports that are in neither expose nor expose_public are closed. Calling it with neither list closes all ports.

Example

Start a Job with a public HTTP server:

$ hf jobs run --detach --expose-public 8000 python:3.12 python -m http.server 8000
Job configuration:
  image          python:3.12
  command        python -m http.server 8000
  flavor         cpu-basic
  labels         name=python-3-12-2c304d37
  expose_public  8000
✓ Job started
  id: 6abb8d05c617607c354d45cf
  name: python-3-12-2c304d37
  url: https://huggingface.co/jobs/Wauplin/6abb8d05c617607c354d45cf
Hint: Job auto-named 'python-3-12-2c304d37'. Pass `--name` or run `hf jobs labels Wauplin/6abb8d05c617607c354d45cf --name NAME` to rename it.
Hint: Exposed ports are reachable at:
  https://6abb8d05c617607c354d45cf--8000.hf.jobs
Hint: Use `hf jobs logs -f Wauplin/6abb8d05c617607c354d45cf` to stream logs, or `hf jobs inspect Wauplin/6abb8d05c617607c354d45cf` to check status.
Hint: Use `hf jobs wait Wauplin/6abb8d05c617607c354d45cf` to block until it finishes.

$ curl -s -o /dev/null -w '%{http_code}\n' https://6abb8d05c617607c354d45cf--8000.hf.jobs/
200

Switch the port to token-protected access on the running Job:

$ hf jobs expose 6abb8f26c617607c354d469a 8000
✓ Exposed ports updated
  id: 6abb8f26c617607c354d469a
  ports: [8000]
  public_ports: []

$ curl -s -o /dev/null -w '%{http_code}\n' https://6abb8f26c617607c354d469a--8000.hf.jobs/
401

Mix private and public ports, then close everything:

$ hf jobs expose 6abb8f26c617607c354d469a 8000 --public 9000
✓ Exposed ports updated
  id: 6abb8f26c617607c354d469a
  ports: [8000, 9000]
  public_ports: [9000]

$ hf jobs expose 6abb8f26c617607c354d469a --clear
✓ Exposed ports updated
  id: 6abb8f26c617607c354d469a
  ports: []
  public_ports: []

The Job was canceled afterward. make style, make quality, and targeted Jobs CLI/API tests pass. One pure payload check was added (public ports merged into ports); no new mocked endpoint tests.

🤖 Generated with Claude Code


Note

Medium Risk
Changes Jobs networking and authentication (public vs token-protected ports) and adds a live port-reconfiguration API; misconfiguration could expose services without auth, though behavior is explicit and documented.

Overview
Adds unauthenticated port exposure for Hub Jobs alongside the existing token-protected --expose / expose flow, and lets you change exposed ports on a running Job without restarting it.

Creation time: expose_public and --expose-public are wired through run_job, run_uv_job, and scheduled job APIs/CLI. The client builds the Hub payload via _build_expose_payload, merging public ports into ports so portsPublic stays a subset of ports without users duplicating port numbers.

Runtime updates: New HfApi.update_job_expose (exported as update_job_expose) PUTs /api/jobs/{namespace}/{job_id}/expose and replaces the full port set—omitted ports are closed; calling with no lists clears everything. CLI: hf jobs expose <job_id> [PORTS]... [--public PORT]... [--clear].

Models & UX: JobInfo / JobSpec surface expose and expose_public from the API; docs and CLI reference are updated. Post-run hints no longer assume every exposed URL requires a token.

Reviewed by Cursor Bugbot for commit b629e7c. Bugbot is set up for automated code reviews on this repo. Configure here.

@bot-ci-comment

Copy link
Copy Markdown

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

Wauplin and others added 2 commits September 28, 2026 17:14
Public ports are merged into the exposed ports list client-side, since the
server only requires portsPublic to be a subset of ports at the wire level.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

@Wauplin Wauplin left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✔️

@Wauplin
Wauplin marked this pull request as ready for review September 29, 2026 10:11
Wauplin and others added 3 commits September 29, 2026 12:13
'hf jobs expose <id> 8000 --public 9000' instead of
'hf jobs expose <id> --expose 8000 --expose-public 9000'.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
The CLI framework adds --format/--json/--quiet automatically.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

@Wauplin Wauplin left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✔️

@hanouticelina hanouticelina left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thank you!

@Wauplin
Wauplin merged commit 3fd18f2 into main Sep 29, 2026
17 of 25 checks passed
@Wauplin
Wauplin deleted the codex/jobs-expose-ports branch September 29, 2026 12:59
@huggingface-hub-bot

Copy link
Copy Markdown
Contributor

This PR has been shipped as part of the v2.1.0 release.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants