docs: fix Desktop IDE setup notes (CORS + discoverability)

Align AGENTS.md, SELF_HOST_GUIDE, and root README with desktop/README.md: keep loopback CORS wildcards when setting a public origin, link Desktop install, and document Node 22 / tunnel prerequisites. Match SecurityConfig @value fallback to application.properties port wildcards. Co-authored-by: Venkat SF <venkatesh.sakamuri@stayflexi.com>
venkateshsakamuri-lab · Aug 23, 2026 · Aug 4, 2026 · Aug 9, 2026 · Aug 16, 2026 · Aug 21, 2026
commit cf05221dae9ab807fead81b187261df6d87134e2
@@ -127,9 +127,14 @@ or an in-process SSH local forward (`ssh2`, no `ssh` binary needed).
 | `desktop/src/main/windows/workspace.js` | Frameless shell: native chrome + embedded DeepSQL view |
 | `desktop/src/renderer/shared/theme.css` | Mirrors `src/index.css` tokens — keep in step |
 
-No backend change was needed: `docker/nginx/default.conf` already serves the SPA,
-`/api` and `/agent-api` from one origin, which is what makes the thin-client
-model work without CORS or cookie special-casing.
+`docker/nginx/default.conf` already serves the SPA, `/api`, and `/agent-api` from
+one origin, so cookies and SSE behave like a normal browser. **CORS is the one
+backend setting the thin client still needs:** an SSH tunnel uses origin
+`http://127.0.0.1:<sticky-port>`, so `CORS_ALLOWED_ORIGINS` on the VM must keep
+the loopback port wildcards (`http://127.0.0.1:*,http://localhost:*`) alongside
+any public hostname. Overriding that env var *replaces* the built-in list — a
+public-origin-only value breaks Desktop tunnel login with a confusing 403.
+Setup and diagnosis: [`desktop/README.md`](desktop/README.md#cors-on-the-vm-the-403-nobody-can-read).
 
 ## Performance & Safety Guardrails
 
@@ -308,10 +313,15 @@ only covers cloud-specific, non-obvious caveats.
   `deepsql agent --connection <uuid> "…"`. Interactive: `deepsql` / `deepsql agent`.
   The CLI is a thin client over `POST /api/agent/chat` (not a local agent runtime);
   backend + agent API (:8787) + provisioner must already be up.
-- **Spring CORS must allow both loopback hosts.** Set
-  `CORS_ALLOWED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000` in `.env`. Opening
-  the UI as `http://127.0.0.1:3000` while only `localhost` is allowlisted yields **403**
-  on `POST /api/agent/session` (and other cookie-auth APIs).
+- **Spring CORS must allow loopback (and Desktop tunnel ports).** Prefer
+  `CORS_ALLOWED_ORIGINS=http://localhost:3000,http://127.0.0.1:*,http://localhost:*`
+  in `.env` (match `.env.example`). Fixed `:3000` alone is enough for Vite on that
+  port; the `*` port wildcards are required for DeepSQL Desktop’s SSH tunnel, which
+  binds a sticky random local port. Opening the UI as `http://127.0.0.1:…` while
+  only `localhost` (or only a public hostname) is allowlisted yields **403** on
+  `POST /api/agent/session` (and other cookie-auth APIs). Electron GUI itself is
+  out of scope for headless Cloud Agents — use Vite + these CORS patterns here;
+  see [`desktop/README.md`](desktop/README.md) when developing the client.
 - **Before running backend tests that boot the Spring context** (e.g. `ApiSmokeTest`), stop
   the running backend first — both use `ddl-auto=update` on the same `dba_agent` DB and can
   deadlock on an `ALTER TABLE`. Test env vars are documented in `CLAUDE.md` (Testing).

@@ -129,7 +129,8 @@ project** — `cd desktop && npm install`, not part of the root `package.json`.
 
 ```bash
 cd desktop
-npm start                 # run     npm run dev          # run with DevTools
+npm start                 # run
+npm run dev               # run with DevTools
 npm test                  # drift guard for the DevTools kill switch
 npm run dist:mac          # dmg + zip (arm64 + x64), also :win / :linux
 npm run smoke -- --url https://deepsql.example.com   # headless connection check

@@ -241,6 +241,22 @@ your schema — all from one shared brain.
 - **Postgres and MySQL, in your infra.** One dialect registry, read-only execution, and SSH
   tunnelling to reach databases behind a bastion.
 
+### DeepSQL Desktop (optional)
+
+A thin Electron client for a self-hosted VM — direct TLS or an in-process SSH tunnel —
+without bundling a second copy of the web UI. Separate npm project:
+
+```bash
+cd desktop
+npm install
+npm start
+```
+
+Requires **Node 22+**. Forward the tunnel to the **frontend container (port 3000)**, not a
+host reverse proxy on `:80`. Keep loopback CORS wildcards on the VM
+(`http://127.0.0.1:*,http://localhost:*`) or tunnel login fails with a confusing 403 — see
+[`desktop/README.md`](desktop/README.md).
+
 ---
 
 ## Operating the stack

@@ -52,7 +52,7 @@ public class SecurityConfig {
      * only {@code application*.properties} — could not see it, and it ships to every reader
      * of the public repository. {@code CorsAllowlistSafetyTest} now scans this file too.
      */
-    @Value("${cors.allowed.origins:http://localhost:3000,http://localhost:3001,http://localhost:3002,http://127.0.0.1:3000,http://127.0.0.1:3001,http://127.0.0.1:3002}")
+    @Value("${cors.allowed.origins:http://localhost:3000,http://localhost:3001,http://localhost:3002,http://127.0.0.1:3000,http://127.0.0.1:3001,http://127.0.0.1:3002,http://127.0.0.1:*,http://localhost:*}")
     private String corsAllowedOrigins;
 
     @Bean

@@ -57,6 +57,9 @@ launch needs **right-click → Open** (or `xattr -dr com.apple.quarantine
 
 ### From source
 
+**Requires Node.js 22+** (matches the Desktop release CI). GUI needs a display; on
+headless Linux use `xvfb-run` for the packaged app or the selftests.
+
 ```bash
 cd desktop
 npm install
@@ -336,6 +339,7 @@ scripts/
   generate-icons.js   SVG → build/icon.png via Electron
   smoke.js            headless connection check
   tunnel-selftest.js  end-to-end SSH tunnel test
+  settings-selftest.js proves an edited setting reaches the live connection
 ```
 
 The renderers are plain HTML/CSS/JS with no build step: they are chrome around

@@ -426,17 +426,22 @@ serve from.
 | `DEEPSQL_BACKEND_PORT` | 8080 | [`docker-compose.yml:94`](../../docker-compose.yml) |
 | `DEEPSQL_POSTGRES_PORT` | 5432 (published as `127.0.0.1:…` only) | [`docker-compose.yml`](../../docker-compose.yml) |
 | `DEEPSQL_VALKEY_PORT` | 6379 (published as `127.0.0.1:…` only) | [`docker-compose.yml`](../../docker-compose.yml) |
-| `CORS_ALLOWED_ORIGINS` | `http://localhost:3000` | `application.properties:87` → [`SecurityConfig.java`](../../backend/src/main/java/com/dbaagent/config/SecurityConfig.java) |
+| `CORS_ALLOWED_ORIGINS` | loopback hosts + port wildcards (see `.env.example`) | `application.properties` → [`SecurityConfig.java`](../../backend/src/main/java/com/dbaagent/config/SecurityConfig.java) |
 
 ```env
 DEEPSQL_FRONTEND_PORT=13000
-CORS_ALLOWED_ORIGINS=http://localhost:13000
+# Port wildcards keep DeepSQL Desktop SSH-tunnel origins working (sticky local port).
+CORS_ALLOWED_ORIGINS=http://localhost:13000,http://127.0.0.1:*,http://localhost:*
 ```
 
-Behind a reverse proxy, `CORS_ALLOWED_ORIGINS` must list the **public** origin
-(`https://deepsql.your-company.example`), not the container port. Consider binding
-postgres and valkey to `127.0.0.1` on a public host, or dropping their `ports:` entries
-entirely — nothing outside the Compose network needs them.
+`CORS_ALLOWED_ORIGINS` **replaces** the built-in allowlist rather than extending it.
+Behind a reverse proxy, list the **public** origin
+(`https://deepsql.your-company.example`) **and** keep
+`http://127.0.0.1:*,http://localhost:*` if anyone will use [DeepSQL Desktop](../../desktop/README.md)
+(SSH tunnel → `http://127.0.0.1:<port>`). A public-origin-only value makes tunnel
+login fail with `403 Invalid CORS request` while GETs still look healthy. Consider
+binding postgres and valkey to `127.0.0.1` on a public host, or dropping their
+`ports:` entries entirely — nothing outside the Compose network needs them.
 
 ### Optional integrations
 
@@ -482,7 +487,8 @@ Once TLS is in place, three settings must follow or authentication behaves oddly
 
 ```env
 SECURITY_COOKIE_SECURE=true
-CORS_ALLOWED_ORIGINS=https://deepsql.your-company.example
+# Public origin for browsers + loopback wildcards for DeepSQL Desktop tunnels.
+CORS_ALLOWED_ORIGINS=https://deepsql.your-company.example,http://127.0.0.1:*,http://localhost:*
 APP_BASE_URL=https://deepsql.your-company.example
 APP_PUBLIC_URL=https://deepsql.your-company.example
 ```
@@ -803,7 +809,7 @@ Agent-specific (in addition to the core stack):
 - [ ] `ENCRYPTION_KEY` backed up somewhere other than where the database dumps live
 - [ ] TLS terminated in front of the frontend, with `SECURITY_COOKIE_SECURE=true`
 - [ ] `APP_BASE_URL` and `APP_PUBLIC_URL` set to the public URL, and the startup log line checked
-- [ ] `CORS_ALLOWED_ORIGINS` set to the public origin only
+- [ ] `CORS_ALLOWED_ORIGINS` includes the public origin **and** `http://127.0.0.1:*,http://localhost:*` (Desktop tunnel / local loopback)
 - [ ] `EMBEDDING_FAIL_OPEN=false` (the `prod` default) so retrieval failures surface
 - [ ] Postgres and valkey not published to a public interface
 - [ ] `.env` never committed — it is gitignored, keep it that way
@@ -816,6 +822,7 @@ Agent-specific (in addition to the core stack):
 
 - [`README.md`](../../README.md) — overview, quick start, LLM configuration, development
 - [`.env.example`](../../.env.example) — inline documentation for every shipped variable
+- [`desktop/README.md`](../../desktop/README.md) — DeepSQL Desktop (Electron) install, SSH tunnel, and CORS requirements
 - [`mcp/README.md`](../../mcp/README.md) — the `deepsql` CLI and MCP server, including client configuration for Claude Desktop and Codex
 - [`docs/root/MCP_PHASE1.md`](./MCP_PHASE1.md) — MCP tools and environment variables
 - [`docs/LOGGING-GUIDE.md`](../LOGGING-GUIDE.md) — log format