docs: add Linux network binding warning for LM Studio with Docker#555
Conversation
On Linux, LM Studio defaults to binding on 127.0.0.1 (localhost only). When OpenHands runs inside Docker, the container cannot reach the host's loopback interface — even with --add-host host.docker.internal:host-gateway. This adds a warning box after the 'Start the LLM server' step explaining: - Why the connection fails on Linux - How to fix it (enable 'Serve on Local Network' in LM Studio) - How to verify connectivity from inside the container This is the #1 support question for Linux users with local LLMs behind Docker. The Ollama, SGLang, and vLLM sections already include --host 0.0.0.0 but the LM Studio quickstart was missing this guidance. Co-authored-by: smolpaws <engel@enyst.org>
|
✅ Review complete. This review was performed through OpenHands Cloud Automation. You can log in and view the conversation here. |
all-hands-bot
left a comment
all-hands-bot
left a comment
There was a problem hiding this comment.
Code Review: PR #555
Overview
This PR adds a warning box to the LM Studio quickstart documentation explaining the network binding issue on Linux when running OpenHands in Docker.
Assessment
🟢 Good Taste — Clean, well-scoped documentation change that solves a real user problem.
Analysis
[CRITICAL ISSUES] — None.
[IMPROVEMENT OPPORTUNITIES] — None. The warning is appropriately concise and actionable.
[STYLE NOTES]
- The existing suggestion from @enyst about rewording "By default, LM Studio only listens on" is a reasonable nit but not blocking. The current phrasing is clear enough.
[TESTING GAPS] — N/A (documentation only).
Notes
The PR description is exemplary:
- Clear "What" section explaining the change
- "Why" section providing context about this being the #1 support question
- Specific actionable steps in "What changes"
- Real user story in "Context" linking to Slack discussion
This follows the pattern already established in the Ollama/SGLang/vLLM sections which show --host 0.0.0.0. The addition makes LM Studio documentation consistent with the other backends.
[RISK ASSESSMENT]
- [Overall PR] Risk Assessment: LOW
Documentation-only change with no code modifications. The content is well-tested by being a solution to a real support issue.
VERDICT:
Worth merging: Core logic is sound, no blocking issues.
KEY INSIGHT:
This is a textbook documentation fix: addresses a real, high-friction problem with minimal, well-scoped changes and excellent PR description.
This review was generated by an AI agent (OpenHands) on behalf of the user through OpenHands Automation.
3 participants
What
Adds a warning box to the LM Studio quickstart section explaining that on Linux, LM Studio defaults to binding on
127.0.0.1and the Docker container cannot reach it — even with--add-host host.docker.internal:host-gateway.Why
This is the #1 support question for Linux users running local LLMs with Docker. The error message (
litellm.InternalServerError: OpenAIException - Connection error) gives no clue about the root cause.The Ollama, SGLang, and vLLM sections already show
--host 0.0.0.0in their example commands, but the LM Studio quickstart was missing any mention of network binding.What changes
<Warning>box after 'Step 4: Start the LLM server' explaining:docker exec ... curlContext
Came up in #questions on Slack — a user on Fedora spent 30+ messages debugging what turned out to be this exact issue.