Skip to content

web: --port 0 lets the OS choose a free port - #2684

Open
acinader wants to merge 1 commit into
simonmichael:mainfrom
acinader:web-port-zero
Open

web: --port 0 lets the OS choose a free port#2684
acinader wants to merge 1 commit into
simonmichael:mainfrom
acinader:web-port-zero

Conversation

@acinader

@acinader acinader commented Aug 4, 2026

Copy link
Copy Markdown
Contributor

Closes #2559.

With this change, hledger-web --port 0 now asks the operating system for a free port. The chosen port is reported in the startup message and used in the default base url, so scripts (and humans) can discover it:

$ hledger-web --serve --port 0
Serving web UI and json API at IP address 127.0.0.1 (local access), port 60019
with base url http://127.0.0.1:60019

Implementation notes, as discussed on the issue:

  • To learn the chosen port we bind the listening socket ourselves and hand it to warp via runSettingsSocket. The binding uses streaming-commons' bindRandomPortTCP (the same function warp's own openFreePort builds on), so --host values are interpreted exactly as warp does. streaming-commons was already in the build plan as a transitive dependency; it's now a direct one.
  • An explicit --base-url is left untouched; only the default host:port base url is rebuilt with the chosen port.
  • --port 0 with --serve-browse reports a clear error suggesting --serve/--serve-api, since browse mode needs a known port up front to open the browser at. (Supporting it would require reworking wai-handler-launch; deliberately out of scope, per the issue discussion.)
  • Flag help and the manual are updated.

Tested by hand: --serve and --serve-api with --port 0 (banner, base url, and HTTP responses on the reported port), the --serve-browse error, --base-url passthrough, and normal explicit-port operation.

AI usage: Claude Fable 5, ~50k output tokens (also noted in the commit message).

The chosen port is reported in the startup message and used in the
default base url, so scripts can discover it. To learn the port, we
bind the listening socket ourselves (with streaming-commons'
bindRandomPortTCP, which warp's own helpers build on) and hand it to
warp. Supported with --serve and --serve-api; --serve-browse reports
an error, since it needs a known port up front to open the browser at.

AI usage: Claude Fable 5, ~50k output tokens
@acinader
acinader marked this pull request as ready for review August 12, 2026 19:59
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.

hledger-web: Randomize port

1 participant