diff --git a/.env.example b/.env.example
index 0d1ec677..8816b524 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 feb75e91..811e7ee5 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: