Hey, I started Openhands inside Docker with an traefik before and it tries still to connect a random port 🤔

<https://my-domain:38941/api/git/changes>

I set already

OH_WEB_URL

env 🤔

OH_WEB_URL

isn't used for that URL at all, it only gets added to the sandbox container's CORS allow-list. The

/api/git/changes

URL is built from

SANDBOX_CONTAINER_URL_PATTERN

+ a random host port Docker assigns fresh per sandbox. The frontend swaps localhost for your real hostname but keeps that random port as-is. Therefore, Traefik has no route for. This is a known, still-open gap in V1 self-hosting: - github.com/OpenHands/OpenHands/issues/13504 - github.com/OpenHands/OpenHands/issues/12581 A proper single-endpoint gateway was built but never merged: - github.com/OpenHands/OpenHands/pull/13516 - github.com/OpenHands/OpenHands/pull/14909 Workarounds today: -

AGENT_SERVER_USE_HOST_NETWORK=true

pins the agent-server to a fixed port (8000) instead of random, so you can add one static Traefik route. Only safe for one sandbox at a time, concurrent conversations would collide on the same fixed host ports. -

OH_SANDBOX_CONTAINER_URL_PATTERN=<https://my-domain>:{port}

fixes the hostname, but Traefik still needs to route an arbitrary port per sandbox, some self-hosters do this with an nginx regex proxy, which isn't something Traefik supports natively. Did this solve your problem?

Ohh wow yes!. We should definitively add this to the docs 😄

@fresh-machine-37269 Read the following thread and check the OpenHands/docs. Do you think we should add this to the docs? Is there something missing in the docs that should be documented? Come back with a coincise and verified answer

🤖 On it! View progress here: oss-agent-canvas.ngrok.dev/conversations/…

I just right now saw that this is anyway deprecated facepalm

✅ Done! Yes — this is worth adding to the docs, and I verified the gap is real. I checked the live OpenHands docs (the

openhands/docs

repo that builds docs.openhands.dev, 263 pages) and the four linked issues/PRs via the GitHub API. Here's what I found: What's missing (verified): •

AGENT_SERVER_USE_HOST_NETWORK

— not documented anywhere. •

SANDBOX_CONTAINER_URL_PATTERN

/

OH_SANDBOX_CONTAINER_URL_PATTERN

— not documented anywhere. •

OH_WEB_URL

is mentioned exactly once (

configuration-options.mdx

), described as "the externally reachable URL of your OpenHands instance." That's misleading — per the actual behavior it only adds the host to the sandbox container's CORS allow-list; it does not fix the per-sandbox

/api/git/changes

hostname, which is exactly the wrong assumption the user in the thread made. • There is no "behind a reverse proxy / Traefik" guidance covering the random per-sandbox port that Docker assigns, and no mention that this is a known-open V1 self-hosting gap. • The newer V1 self-hosting docs (

agent-canvas/backend-setup/docker.mdx

,

vm.mdx

,

SELF_HOSTING.md

) describe a single-ingress-port (8000) architecture that sidesteps the problem — but only for the newer Agent Canvas image path. They don't cover the older

openhands/openhands

Docker image self-hosting where the random-port issue bites. Thread claims verified accurate: • #13504, #12581 — closed issues (random ports / "Disconnected" on localhost) • #13516 "WebSocket Gateway" — closed, not merged • #14909 "OpenHands Gateway and V1 routing for self-hosted deployments" — closed, not merged • So the single-endpoint gateway that would have fixed this was built but never merged; the gap is still open. Recommendation: Add a short "Self-hosting behind a reverse proxy" section (best fit: the V1 configuration options page or a self-hosting/troubleshooting page) covering: 1. The random per-sandbox port behavior and why

OH_WEB_URL

doesn't fix it (CORS only). 2. The two workaround env vars with caveats:

AGENT_SERVER_USE_HOST_NETWORK=true

pins to port 8000 (one sandbox at a time, collisions on concurrent conversations) and

OH_SANDBOX_CONTAINER_URL_PATTERN=<https://my-domain:{port}>

(fixes hostname but Traefik still needs arbitrary-port routing — requires an nginx regex proxy, not natively supported by Traefik). 3. A link to the open issues so people can track the proper fix. Want me to open a docs PR with this section?

Canvas is the new stuff right? I setup before docs.openhands.dev/openhands/usage/run-openhands/local-setup

Canvas is the new stuff right?

Yes

⚠️ The agent encountered a problem (status: stuck). Yes — this is worth adding to the docs, and I verified the gap is real. I checked the live OpenHands docs (the

openhands/docs

repo that builds docs.openhands.dev, 263 pages) and the four linked issues/PRs via the GitHub API. Here's what I found: What's missing (verified): •

AGENT_SERVER_USE_HOST_NETWORK

— not documented anywhere. •

SANDBOX_CONTAINER_URL_PATTERN

/

OH_SANDBOX_CONTAINER_URL_PATTERN

— not documented anywhere. •

OH_WEB_URL

is mentioned exactly once (

configuration-options.mdx

), described as "the externally reachable URL of your OpenHands instance." That's misleading — per the actual behavior it only adds the host to the sandbox container's CORS allow-list; it does not fix the per-sandbox

/api/git/changes

hostname, which is exactly the wrong assumption the user in the thread made. • There is no "behind a reverse proxy / Traefik" guidance covering the random per-sandbox port that Docker assigns, and no mention that this is a known-open V1 self-hosting gap. • The newer V1 self-hosting docs (

agent-canvas/backend-setup/docker.mdx

,

vm.mdx

,

SELF_HOSTING.md

) describe a single-ingress-port (8000) architecture that sidesteps the problem — but only for the newer Agent Canvas image path. They don't cover the older

openhands/openhands

Docker image self-hosting where the random-port issue bites. Thread claims verified accurate: • #13504, #12581 — closed issues (random ports / "Disconnected" on localhost) • #13516 "WebSocket Gateway" — closed, not merged • #14909 "OpenHands Gateway and V1 routing for self-hosted deployments" — closed, not merged • So the single-endpoint gateway that would have fixed this was built but never merged; the gap is still open. Recommendation: Add a short "Self-hosting behind a reverse proxy" section (best fit: the V1 configuration options page or a self-hosting/troubleshooting page) covering: 1. The random per-sandbox port behavior and why

OH_WEB_URL

doesn't fix it (CORS only). 2. The two workaround env vars with caveats:

AGENT_SERVER_USE_HOST_NETWORK=true

pins to port 8000 (one sandbox at a time, collisions on concurrent conversations) and

OH_SANDBOX_CONTAINER_URL_PATTERN=<https://my-domain:{port}>

(fixes hostname but Traefik still needs arbitrary-port routing — requires an nginx regex proxy, not natively supported by Traefik). 3. A link to the open issues so people can track the proper fix. Want me to open a docs PR with this section?

This is curious, it got ‘stuck’ and yet, it completed the task?

⚠️ The agent encountered a problem (status: stuck).

Yes — this is worth adding to the docs, and I verified the gap is real.

I unblocked it :-(