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.

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 69.48%. Comparing base (a4dc39f) to head (15e7c04).
⚠️ Report is 1 commits behind head on main.

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   69.52%   69.48%   -0.04%     
==========================================
  Files         480      480              
  Lines       48978    49025      +47     
==========================================
+ Hits        34051    34066      +15     
- Misses      12302    12331      +29     
- Partials     2625     2628       +3

☔ 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.

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.

pkg/networking/port_test.go

pkg/container/docker/client.go

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 😃

pkg/container/docker/client_helpers_test.go

github-actions

Large PR Detected

This PR exceeds 1000 lines of changes and requires justification before it can be reviewed.

How to unblock this PR:

Add a section to your PR description with the following format:

## Large PR Justification

[Explain why this PR must be large, such as:]
- Generated code that cannot be split
- Large refactoring that must be atomic
- Multiple related changes that would break if separated
- Migration or data transformation

Alternative:

Consider splitting this PR into smaller, focused changes (< 1000 lines each) for easier review and reduced risk.

See our Contributing Guidelines for more details.

This review will be automatically dismissed once you add the justification section.

github-actions · 2026-03-18T21:32:09Z

✅ PR size has been reduced below the XL threshold. The size review has been dismissed and this PR can now proceed with normal review. Thank you for splitting this up!

PR size has been reduced below the XL threshold. Thank you for splitting this up!

jerm-dro · 2026-03-25T21:29:08Z

@Sanskarzz This is approved but it looks like the branch has merge conflicts and CI hasn't run on the latest commit. Can you rebase against main, run task docs to regenerate, and push so CI can run? Once it's green we can merge.

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

Sanskarzz · 2026-03-25T22:36:48Z

@Sanskarzz This is approved but it looks like the branch has merge conflicts and CI hasn't run on the latest commit. Can you rebase against main, run task docs to regenerate, and push so CI can run? Once it's green we can merge.

@jerm-dro I have rebased and executed task docs, but no new docs were generated. CI is green now.

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

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

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

pkg/networking/port_test.go Outdated Show resolved Hide resolved

jerm-dro reviewed Mar 2, 2026

View reviewed changes

pkg/container/docker/client.go Show resolved Hide resolved

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

jerm-dro previously approved these changes Mar 11, 2026

View reviewed changes

pkg/container/docker/client_helpers_test.go Show resolved Hide resolved

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

github-actions bot added size/XL Extra large PR: 1000+ lines changed and removed size/S Small PR: 100-299 lines changed labels Mar 18, 2026

github-actions bot previously requested changes Mar 18, 2026

View reviewed changes

github-actions bot added size/XL Extra large PR: 1000+ lines changed size/S Small PR: 100-299 lines changed and removed size/XL Extra large PR: 1000+ lines changed labels Mar 18, 2026

jerm-dro previously approved these changes Mar 18, 2026

View reviewed changes

Sanskarzz dismissed jerm-dro’s stale review via 71b22b2 March 23, 2026 21:48

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

jerm-dro previously approved these changes Mar 23, 2026

View reviewed changes

Sanskarzz added 6 commits March 26, 2026 03:43

ref: support multi port like docker

f904584

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

fix: add docs

2f88002

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

fix: used require assertions

c925545

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

fix: assert non-zero

d5903d6

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

fix: lint

4974b60

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

fix: swag docs

15e7c04

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

Sanskarzz dismissed jerm-dro’s stale review via 15e7c04 March 25, 2026 22:21

Sanskarzz force-pushed the addports branch from 71b22b2 to 15e7c04 Compare March 25, 2026 22:21

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

jerm-dro approved these changes Mar 25, 2026

View reviewed changes

JAORMX merged commit 87529a1 into stacklok:main Mar 26, 2026
37 checks passed

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
JAORMX merged 6 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!

Uh oh!

Uh oh!

Sanskarzz commented Mar 9, 2026

Uh oh!

Sanskarzz commented Mar 11, 2026

Uh oh!

jerm-dro left a comment

Uh oh!

Uh oh!

github-actions bot left a comment

Uh oh!

github-actions bot commented Mar 18, 2026

Uh oh!

jerm-dro commented Mar 25, 2026

Uh oh!

Sanskarzz commented Mar 25, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 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!

Uh oh!

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!

Uh oh!

github-actions bot left a comment

Choose a reason for hiding this comment

Large PR Detected

How to unblock this PR:

Alternative:

Uh oh!

github-actions bot commented Mar 18, 2026

Uh oh!

jerm-dro commented Mar 25, 2026

Uh oh!

Sanskarzz commented Mar 25, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

codecov bot commented Feb 19, 2026 •

edited

Loading