diff --git a/docs/configuration.md b/docs/configuration.md
index 408018c7f..5b78ec876 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -15,6 +15,11 @@ Authentication stays separate because it contains a secret:
 Run `devspace init` to create both files. `devspace config set publicBaseUrl
 <url|null>` updates the JSONC document without discarding its comments.
 
+DevSpace reads server configuration when `devspace serve` starts. After editing
+`config.jsonc` or running `devspace config set`, restart the running server to
+apply changes such as `workspaces.allowedRoots` or `server.publicBaseUrl`.
+Changes on disk do not automatically update a running server.
+
 ## Complete example
 
 ```jsonc
diff --git a/src/cli-config.test.ts b/src/cli-config.test.ts
new file mode 100644
index 000000000..baddbe5dd
--- /dev/null
+++ b/src/cli-config.test.ts
@@ -0,0 +1,26 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { loadDevspaceFiles } from "./user-config.js";
+import { writeTestDevspaceConfig } from "./test-support/config.test.js";
+
+test("config set tells users to restart the running server", () => {
+  const configDir = mkdtempSync(join(tmpdir(), "devspace-cli-config-test-"));
+  try {
+    const env = { ...process.env, ...writeTestDevspaceConfig(configDir) };
+    const stdout = execFileSync(
+      "node",
+      ["--import", "tsx", "src/cli.ts", "config", "set", "publicBaseUrl", "https://example.com"],
+      { encoding: "utf8", env },
+    );
+
+    assert.match(stdout, /Updated .*config\.jsonc/);
+    assert.match(stdout, /Restart `devspace serve` to apply this change/);
+    assert.equal(loadDevspaceFiles(env).config.server.publicBaseUrl, "https://example.com");
+  } finally {
+    rmSync(configDir, { recursive: true, force: true });
+  }
+});
diff --git a/src/cli.ts b/src/cli.ts
index 3037f65e8..3b020ae05 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -446,6 +446,7 @@ function runConfigCommand(args: string[]): void {
     normalizeOptionalPublicBaseUrl(value),
   );
   console.log(`Updated ${files.configPath}`);
+  console.log("Restart `devspace serve` to apply this change to a running server.");
 }
 
 async function runWorktreesCommand(args: string[]): Promise<void> {