fix: document COLLAB_EMBEDDED_WS=true requirement for local self-hosting#56
Open
jessems wants to merge 1 commit into
Open
fix: document COLLAB_EMBEDDED_WS=true requirement for local self-hosting#56jessems wants to merge 1 commit into
jessems wants to merge 1 commit into
Conversation
Without this env var, the server assumes the collab WebSocket runs on PORT+1 (4001 by default) rather than the embedded port (4000). The editor silently stays in "connecting" state with no useful error message. Added COLLAB_EMBEDDED_WS=true to .env.example with an explanation, and updated the README quickstart to include it in the npm run serve command. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
COLLAB_EMBEDDED_WS=true, the server calculates the collab WebSocket URL asPORT+1(4001 by default) rather than the actual server port (4000).wsUrlBase=ws://localhost:4000/wsat startup, but the URL served to clients points elsewhere — the mismatch is invisible without inspecting the/collab-sessionAPI response.Root cause
In
server/routes.ts,resolveRequestScopedCollabWsBasedefaults toappPort + 1for loopback hosts unlessCOLLAB_EMBEDDED_WSis set, because in the hosted deployment the collab runtime runs as a separate process on a different port. For self-hosted local use, the runtime is always embedded and the env var must be set explicitly.Fix
COLLAB_EMBEDDED_WS=trueto.env.examplewith an explanation.npm run servecommand to include it.Reproduction
Test plan
COLLAB_EMBEDDED_WS=true npm run serve/collab-sessionreturnsws://localhost:4000/ws