From 4cd687ef01ed04ec31b961e8524a3ae47335bcf5 Mon Sep 17 00:00:00 2001 From: Jesse Szepieniec Date: Tue, 9 Jun 2026 10:27:28 +0200 Subject: [PATCH] fix: document COLLAB_EMBEDDED_WS=true requirement for local self-hosting 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 --- .env.example | 5 +++++ README.md | 4 +++- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/.env.example b/.env.example index 0d1ec67..8816b52 100644 --- a/.env.example +++ b/.env.example @@ -3,3 +3,8 @@ VITE_ENABLE_TELEMETRY=false # Optional app version tag for event properties VITE_APP_VERSION=dev + +# Required for local self-hosting: tells the server the collab WebSocket runs +# on the same port as the HTTP server (embedded mode). Without this, the server +# assumes the collab runtime is on PORT+1 and the editor stays in "connecting". +COLLAB_EMBEDDED_WS=true diff --git a/README.md b/README.md index feb75e9..811e7ee 100644 --- a/README.md +++ b/README.md @@ -44,11 +44,13 @@ npm run dev Start the local server: ```bash -npm run serve +COLLAB_EMBEDDED_WS=true npm run serve ``` The default setup serves the editor on `http://localhost:3000` and the API/server on `http://localhost:4000`. +> **Note:** `COLLAB_EMBEDDED_WS=true` is required for local self-hosting. Without it the server assumes the collab WebSocket runs on `PORT+1` (4001 by default) rather than the same port, and the editor will remain stuck in a "connecting" state. See `.env.example`. + ## Core Routes Canonical Proof SDK routes: