From 95fddc436f1cfe3f696b57e54af6d519a53aae01 Mon Sep 17 00:00:00 2001
From: Vincent Driessen <me@nvie.com>
Date: Mon, 10 Aug 2026 16:31:31 +0200
Subject: [PATCH] Update dev server docs to the 1.9.0 flag state (#3659)

---
 docs/pages/tools/dev-server.mdx               | 29 ++++++++++++++-----
 ...t-up-continuous-integration-ci-testing.mdx |  2 +-
 ...end-to-end-e2e-testing-with-playwright.mdx | 10 +++++--
 3 files changed, 30 insertions(+), 11 deletions(-)

diff --git a/docs/pages/tools/dev-server.mdx b/docs/pages/tools/dev-server.mdx
index 89595d5c5bd..1fe282522f7 100644
--- a/docs/pages/tools/dev-server.mdx
+++ b/docs/pages/tools/dev-server.mdx
@@ -225,6 +225,12 @@ This mode will:
 2. Run your unit tests.
 3. Stop the dev server.
 
+The command inherits `LIVEBLOCKS_BASE_URL`, `LIVEBLOCKS_PUBLIC_KEY` and
+`LIVEBLOCKS_SECRET_KEY`, along with the `NEXT_PUBLIC_`, `VITE_` and `PUBLIC_`
+prefixed variants for client-side code. If your app reads its connection details
+from the environment, it talks to the dev server without any change to your
+source or `.env` files.
+
 Example output:
 
 ```bash
@@ -275,6 +281,21 @@ We recommend:
    against a fresh instance (your local data in `.liveblocks/` won't be affected
    by your unit tests).
 
+## Persisting data
+
+Whether room data is kept is an explicit choice. By default,
+`npx liveblocks dev` persists data in the `.liveblocks/` folder, and `--cmd`
+uses a throwaway directory that is discarded when the command exits. Override
+either default with `--persist` or `--no-persist`:
+
+```bash
+# Throwaway server, nothing is written to .liveblocks/
+npx liveblocks dev --no-persist
+
+# Keep data between runs, useful when --cmd runs your app instead of your tests
+npx liveblocks dev --persist --cmd 'next dev'
+```
+
 ## Continuous Integration (CI) testing
 
 You can use the dev server in CI environments by setting up a test environment
@@ -304,13 +325,7 @@ You can run the dev server as a Docker container, which is useful for CI
 environments where you may not have Bun installed.
 
 ```bash
-docker run -p 1153:1153 ghcr.io/liveblocks/cli dev
-```
-
-To persist data between container restarts, mount a volume:
-
-```bash
-docker run -p 1153:1153 -v liveblocks-data:/app/.liveblocks ghcr.io/liveblocks/cli dev
+docker run -p 1153:1153 ghcr.io/liveblocks/dev-server
 ```
 
 ## Source code
diff --git a/guides/pages/how-to-set-up-continuous-integration-ci-testing.mdx b/guides/pages/how-to-set-up-continuous-integration-ci-testing.mdx
index bf73416d8a1..6378b152085 100644
--- a/guides/pages/how-to-set-up-continuous-integration-ci-testing.mdx
+++ b/guides/pages/how-to-set-up-continuous-integration-ci-testing.mdx
@@ -81,7 +81,7 @@ jobs:
     +++
     services:
       liveblocks:
-        image: liveblocks/dev-server
+        image: ghcr.io/liveblocks/dev-server:latest
         ports:
           - 1153:1153
     +++
diff --git a/guides/pages/how-to-set-up-end-to-end-e2e-testing-with-playwright.mdx b/guides/pages/how-to-set-up-end-to-end-e2e-testing-with-playwright.mdx
index f78f5fc8db8..982b3b5473e 100644
--- a/guides/pages/how-to-set-up-end-to-end-e2e-testing-with-playwright.mdx
+++ b/guides/pages/how-to-set-up-end-to-end-e2e-testing-with-playwright.mdx
@@ -98,7 +98,7 @@ export default defineConfig({
       ? []
       : [
           {
-            command: `npx liveblocks dev --ephemeral --no-check --port ${LIVEBLOCKS_PORT}`,
+            command: `npx liveblocks dev --no-persist --no-check --port ${LIVEBLOCKS_PORT}`,
             port: LIVEBLOCKS_PORT,
             reuseExistingServer: true,
           },
@@ -120,6 +120,9 @@ export default defineConfig({
 
 A few things to note:
 
+- **`--no-persist`**—Starts the server in a throwaway directory, so tests never
+  touch the `.liveblocks/` folder you use for everyday development. Pair it with
+  `--no-check`, which skips the interactive project setup check on start.
 - **`reuseExistingServer`**—Locally, this lets you leave the servers running
   between test runs for faster iteration. In CI, a fresh server is started each
   time.
@@ -312,8 +315,9 @@ workflow built using this guide. You can use it as a starting point:
 
 ## Tips
 
-- **Unique room IDs per test**: The dev server persists storage to disk, so
-  using unique room IDs prevents state from leaking between tests.
+- **Unique room IDs per test**: Room state lives for as long as the dev server
+  does, so using unique room IDs prevents state from leaking between tests
+  within a run.
 - **Retries**: Collaborative tests involve WebSocket connections and async
   syncing. Adding a few retries in CI (`retries: 2` or more) helps absorb
   occasional timing-related flakiness.