Support publishing additional container ports in thv run by Sanskarzz · Pull Request #3892 · stacklok/toolhive

Sanskarzz · 2026-02-19T11:34:34Z

Summary

This PR adds support for the --publish / -p flag to the thv run command, enabling users to expose arbitrary container ports to the host, similar to docker run -p. It also fixes a bug in the Docker runtime client where explicitly requested host ports were being overwritten by random ports.

Key Changes

Added --publish flag to thv run.
Implemented networking.ParsePortSpec for robust port specification parsing.
Updated runtime.Setup to handle multiple port bindings efficiently.
Fixed pkg/container/docker/client.go to respect existing HostPort assignments in generatePortBindings.
Added unit tests for port parsing logic.

Signed-off-by: Sanskarzz <sanskar.gur@gmail.com>

codecov · 2026-02-19T12:02:35Z

Codecov Report

❌ Patch coverage is 44.44444% with 30 lines in your changes missing coverage. Please review.
✅ Project coverage is 67.98%. Comparing base (0657df9) to head (b386476).

Files with missing lines	Patch %	Lines
pkg/runtime/setup.go	0.00%	15 Missing ⚠️
pkg/networking/port.go	71.42%	3 Missing and 3 partials ⚠️
pkg/container/docker/client.go	61.53%	2 Missing and 3 partials ⚠️
pkg/runner/config_builder.go	0.00%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3892      +/-   ##
==========================================
- Coverage   68.10%   67.98%   -0.13%     
==========================================
  Files         461      461              
  Lines       46700    46760      +60     
==========================================
- Hits        31804    31788      -16     
- Misses      12131    12177      +46     
- Partials     2765     2795      +30

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Signed-off-by: Sanskarzz <sanskar.gur@gmail.com>

jerm-dro

Mostly LGTM to me. Can you manually verify this fixes the user's reported issue by running this locally? A series of screenshots or video will do.

jerm-dro · 2026-03-02T19:56:28Z

pkg/networking/port_test.go

+			if tt.wantError {
+				if err == nil {
+					t.Errorf("ParsePortSpec(%s) expected error but got nil", tt.portSpec)
+				}
+				return
+			}
+
+			if err != nil {
+				t.Errorf("ParsePortSpec(%s) unexpected error: %v", tt.portSpec, err)
+				return
+			}
+
+			if tt.expectedHostPort != "" && hostPort != tt.expectedHostPort {
+				t.Errorf("ParsePortSpec(%s) hostPort = %s, want %s", tt.portSpec, hostPort, tt.expectedHostPort)
+			}
+
+			if tt.expectedHostPort == "" && hostPort == "" {
+				t.Errorf("ParsePortSpec(%s) hostPort is empty, want random port", tt.portSpec)
+			}
+
+			if containerPort != tt.expectedContainer {
+				t.Errorf("ParsePortSpec(%s) containerPort = %d, want %d", tt.portSpec, containerPort, tt.expectedContainer)
+			}


nit: can you rewrite these assertions to use the require package (e.g.require.Equal or require.True)?

This will make the tests less nested and easier to read.

I have rewritten the nested if statements into cleaner require assertions in pkg/networking/port_test.go as requested.

jerm-dro · 2026-03-02T20:01:51Z

pkg/container/docker/client.go

+				hostPortStr := bindings[0].HostPort
+				if hostPortStr == "" || hostPortStr == "0" {
+					hostPort = networking.FindAvailable()
+					if hostPort == 0 {
+						return nil, 0, fmt.Errorf("could not find an available port")
+					}
+					bindings[0].HostPort = fmt.Sprintf("%d", hostPort)
+					portBindings[key] = bindings
+				} else {
+					var err error
+					hostPort, err = strconv.Atoi(hostPortStr)
+					if err != nil {
+						return nil, 0, fmt.Errorf("failed to convert host port %s to int: %w", hostPortStr, err)
+					}
+				}


Is this the fix for:

It also fixes a bug in the Docker runtime client where explicitly requested host ports were being overwritten by random ports.

?

If so, can you find a way to add a regression test and some unit tests here? The generatePortBindings function seems like it should be amenable to unit testing without any refactoring.

Added two new regression tests for generatePortBindings to client_helpers_test.go:

TestGeneratePortBindings_NonAuxiliaryKeepsExplicitHostPort: ensures explicit host ports (e.g., "9090") are kept instead of replaced with a random port.

TestGeneratePortBindings_NonAuxiliaryAssignsRandomPortForZero: ensures passing "0" correctly assigns a random available port.

Signed-off-by: Sanskarzz <sanskar.gur@gmail.com>

Sanskarzz · 2026-03-09T07:48:25Z

Mostly LGTM to me. Can you manually verify this fixes the user's reported issue by running this locally? A series of screenshots or a video will do.

It looks like I need to create one or two MCP servers that are exposed on multiple ports. One of them is ghcr.io/manykarim/rf-mcp:latest, which was mentioned in the discussion. I have tested it earlier, but I’ll run it again locally and share screenshots shortly.

@jerm-dro, if you have a similar MCP server in your inventory that exposes multiple ports, could you please share it?

Sanskarzz · 2026-03-11T14:01:08Z

Mostly LGTM to me. Can you manually verify this fixes the user's reported issue by running this locally? A series of screenshots or video will do.

Apologies for the late response
Here is a series of commands to verify this fix

sanskar@sanskar-HP-Laptop-15s-du1xxx:~/opensource/stacklok/toolhive$ ./bin/thv run --name manykarim-rf-mcp \
  --transport streamable-http \
  --target-port 8002 \
  --publish 8004:8001 \
  ghcr.io/manykarim/rf-mcp:latest \
  -- --host 0.0.0.0 --port 8002 & sleep 10 && docker ps | grep manykarim-rf-mcp && ./bin/thv status manykarim-rf-mcp 
[1] 192790
{"time":"2026-03-11T19:15:58+05:30","level":"WARN","msg":"MCP server has no provenance information set, skipping image verification","image":"ghcr.io/manykarim/rf-mcp:latest"}
{"time":"2026-03-11T19:15:58+05:30","level":"INFO","msg":"pulling image","image":"ghcr.io/manykarim/rf-mcp:latest"}
Successfully pulled ghcr.io/manykarim/rf-mcp:latest
{"time":"2026-03-11T19:16:02+05:30","level":"INFO","msg":"logging to","path":"/home/sanskar/.local/share/toolhive/logs/manykarim-rf-mcp.log"}
[1]+  Done                    ./bin/thv run --name manykarim-rf-mcp --transport streamable-http --target-port 8002 --publish 8004:8001 ghcr.io/manykarim/rf-mcp:latest -- --host 0.0.0.0 --port 8002
bc5271e828a5   ghcr.io/manykarim/rf-mcp:latest            "uv run --no-sync ro…"   6 seconds ago   Up 5 seconds                      8000/tcp, 127.0.0.1:8002->8002/tcp, 0.0.0.0:8004->8001/tcp, [::]:8004->8001/tcp                                 manykarim-rf-mcp
Name:        manykarim-rf-mcp
Status:      starting
Package:     
URL:         
Port:        0
Transport:   
Created:     2026-03-11 19:08:50

sanskar@sanskar-HP-Laptop-15s-du1xxx:~/opensource/stacklok/toolhive$ ./bin/thv status manykarim-rf-mcp 
Name:         manykarim-rf-mcp
Status:       running
Package:      ghcr.io/manykarim/rf-mcp:latest
URL:          http://127.0.0.1:52771/mcp
Port:         52771
Transport:    streamable-http
Proxy Mode:   streamable-http
Group:        default
Created:      2026-03-11 19:08:50
Uptime:       6m

sanskar@sanskar-HP-Laptop-15s-du1xxx:~/opensource/stacklok/toolhive$ docker ps | grep manykarim-rf-mcp
bc5271e828a5   ghcr.io/manykarim/rf-mcp:latest            "uv run --no-sync ro…"   6 minutes ago   Up 6 minutes                      8000/tcp, 127.0.0.1:8002->8002/tcp, 0.0.0.0:8004->8001/tcp, [::]:8004->8001/tcp                                 manykarim-rf-mcp

jerm-dro

Thanks for including the screenshots of the manual validation 😃

jerm-dro · 2026-03-11T15:42:28Z

pkg/container/docker/client_helpers_test.go

+
+	require.Contains(t, out, "8080/tcp")
+	require.Len(t, out["8080/tcp"], 1)
+	assert.Equal(t, fmt.Sprintf("%d", hostPort), out["8080/tcp"][0].HostPort)


nit, feel free to ignore: could also assert non-zero

I added assert.NotEqual(t, "0", out["8080/tcp"][0].HostPort) to the test in client_helpers_test.go.

Signed-off-by: Sanskarzz <sanskar.gur@gmail.com>

ref: support multi port like docker

ea09ace

Signed-off-by: Sanskarzz <sanskar.gur@gmail.com>

Sanskarzz requested review from ChrisJBurns, JAORMX, amirejaz, blkt, eleftherias, jhrozek, lujunsan, rdimitrov and yrobla as code owners February 19, 2026 11:34

Merge branch 'main' into addports

87686ac

github-actions bot added the size/S Small PR: 100-299 lines changed label Feb 19, 2026

fix: CI error removed unwanted package from setup.go

bc0747e

Signed-off-by: Sanskarzz <sanskar.gur@gmail.com>

github-actions bot added size/S Small PR: 100-299 lines changed and removed size/S Small PR: 100-299 lines changed labels Feb 19, 2026

fix: add docs

45115fd

Signed-off-by: Sanskarzz <sanskar.gur@gmail.com>

Sanskarzz force-pushed the addports branch from 9fb626e to 45115fd Compare February 19, 2026 13:35

github-actions bot added size/S Small PR: 100-299 lines changed and removed size/S Small PR: 100-299 lines changed labels Feb 19, 2026

jerm-dro reviewed Mar 2, 2026

View reviewed changes

Sanskarzz and others added 2 commits March 8, 2026 19:44

fix: used require assertions

e2d12a7

Signed-off-by: Sanskarzz <sanskar.gur@gmail.com>

Merge branch 'main' into addports

491d95b

github-actions bot added size/S Small PR: 100-299 lines changed and removed size/S Small PR: 100-299 lines changed labels Mar 8, 2026

fix: conflict

b6bf64a

Signed-off-by: Sanskarzz <sanskar.gur@gmail.com>

github-actions bot removed the size/S Small PR: 100-299 lines changed label Mar 8, 2026

github-actions bot added the size/S Small PR: 100-299 lines changed label Mar 8, 2026

fix: CI

bab7735

Signed-off-by: Sanskarzz <sanskar.gur@gmail.com>

github-actions bot added size/S Small PR: 100-299 lines changed and removed size/S Small PR: 100-299 lines changed labels Mar 9, 2026

jerm-dro previously approved these changes Mar 11, 2026

View reviewed changes

fix: assert non-zero

fbc81c3

Signed-off-by: Sanskarzz <sanskar.gur@gmail.com>

Sanskarzz dismissed jerm-dro’s stale review via fbc81c3 March 13, 2026 06:09

github-actions bot added size/S Small PR: 100-299 lines changed and removed size/S Small PR: 100-299 lines changed labels Mar 13, 2026

Merge branch 'main' into addports

c7abcce

github-actions bot added size/S Small PR: 100-299 lines changed and removed size/S Small PR: 100-299 lines changed labels Mar 13, 2026

Merge branch 'main' into addports

b386476

github-actions bot added size/S Small PR: 100-299 lines changed and removed size/S Small PR: 100-299 lines changed labels Mar 13, 2026

jerm-dro approved these changes Mar 13, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Support publishing additional container ports in thv run#3892

Support publishing additional container ports in thv run#3892
Sanskarzz wants to merge 11 commits intostacklok:mainfrom
Sanskarzz:addports

Sanskarzz commented Feb 19, 2026

Uh oh!

codecov bot commented Feb 19, 2026 •

edited

Loading

Uh oh!

jerm-dro left a comment

Uh oh!

jerm-dro Mar 2, 2026

Uh oh!

Sanskarzz Mar 8, 2026

Uh oh!

jerm-dro Mar 2, 2026

Uh oh!

Sanskarzz Mar 8, 2026 •

edited

Loading

Uh oh!

Sanskarzz commented Mar 9, 2026

Uh oh!

Sanskarzz commented Mar 11, 2026

Uh oh!

jerm-dro left a comment

Uh oh!

jerm-dro Mar 11, 2026

Uh oh!

Sanskarzz Mar 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

Sanskarzz commented Feb 19, 2026

Uh oh!

codecov bot commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

jerm-dro left a comment

Choose a reason for hiding this comment

Uh oh!

jerm-dro Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

Sanskarzz Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

jerm-dro Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

Sanskarzz Mar 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Sanskarzz commented Mar 9, 2026

Uh oh!

Sanskarzz commented Mar 11, 2026

Uh oh!

jerm-dro left a comment

Choose a reason for hiding this comment

Uh oh!

jerm-dro Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Sanskarzz Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

codecov bot commented Feb 19, 2026 •

edited

Loading

Sanskarzz Mar 8, 2026 •

edited

Loading