[codex] Persist OAuth state and improve network setup

.gitignore

@@ -1,5 +1,6 @@
 node_modules/
 dist/
 releases/
+workspace/
 .env
 *.log

README.md

@@ -22,7 +22,7 @@ DevSpace is a self-hosted MCP server that lets ChatGPT read, edit, search, and r
 
 ## Installation
 
-DevSpace requires Node `>=20.12 <27`. Node 22 LTS is recommended.
+DevSpace requires Node `>=22.19 <27`. Node 22.19 or newer is required; current Node 22 LTS or Node 24 is recommended.
 
 Install the DevSpace CLI:
 
@@ -48,10 +48,16 @@ During setup, DevSpace asks for:
 
 - the local project folders ChatGPT is allowed to open through DevSpace
 - the local port, usually `7676`
-- your public HTTPS base URL from Cloudflare Tunnel, ngrok, Pinggy, Tailscale Funnel, or
-  another reverse proxy
+- the local listen address, such as `127.0.0.1`, `100.64.0.2`, or `0.0.0.0`
+- whether clients connect through localhost or a custom HTTPS URL
 
-Use the public origin without `/mcp` during setup:
+Choose **Localhost** to use `http://localhost:<port>` automatically. Choose
+**Custom HTTPS URL** to enter a Cloudflare Tunnel, ngrok, Pinggy, Tailscale Funnel,
+reverse proxy, or other network origin.
+
+When an HTTPS URL already exists, `devspace init --force` defaults to keeping it
+unchanged. Choose **Custom HTTPS URL** only when intentionally changing it. Enter
+the public origin without `/mcp`:
 
 ```text
 https://your-tunnel-host.example.com
@@ -68,6 +74,16 @@ the Owner password printed by `devspace init`. It is also stored in:
 
 Keep that password private.
 
+The Owner password is only entered on the approval page. It is not sent with
+every MCP request. After approval, DevSpace issues short-lived access tokens
+and longer-lived refresh tokens.
+
+OAuth client registrations and hashed access and refresh tokens are persisted
+in the DevSpace SQLite state database. Restarting `devspace serve` therefore
+does not invalidate an already registered ChatGPT app. When upgrading from an
+older build that stored OAuth state only in memory, remove and add the ChatGPT
+app one final time so its client registration can be persisted.
+
 ## Connect Your MCP Client
 
 The default local endpoint is:
@@ -82,6 +98,24 @@ Most users should connect through a public HTTPS tunnel:
 https://your-tunnel-host.example.com/mcp
 ```
 
+To accept direct connections from another interface, set the bind address and
+restart DevSpace:
+
+```bash
+devspace config set host 100.64.0.2
+devspace serve
+```
+
+Always configure the MCP client with the full `/mcp` endpoint. The base URL
+stored by DevSpace does not include `/mcp`, but the client-facing URL does:
+
+```text
+https://your-tunnel-host.example.com/mcp
+```
+
+OAuth request logs preserve their original paths, so requests to `/register`,
+`/authorize`, and `/token` are no longer incorrectly reported as `/`.
+
 ## What ChatGPT Can Do
 
 Once connected, ChatGPT can open one of your approved project folders as a
@@ -138,6 +172,7 @@ devspace doctor
 - [ChatGPT Coding Workflow](docs/chatgpt-coding-workflow.md)
 - [Configuration Reference](docs/configuration.md)
 - [Security Model](docs/security.md)
+- [OAuth State and File Permissions](docs/oauth-state-and-security.md)
 - [Troubleshooting Gotchas](docs/gotchas.md)
 
 ## Philosophy
@@ -177,3 +212,17 @@ npm test
 npm run build
 npm run start
 ```
+
+To use the current checkout as the global `devspace` command:
+
+```bash
+npm run typecheck
+npm test
+npm run build
+npm uninstall -g @waishnav/devspace
+npm install -g .
+hash -r
+```
+
+The global npm entry then links back to this checkout. Future source changes
+only require `npm run build`; reinstalling the global link is unnecessary.

docs/configuration.md

@@ -23,9 +23,20 @@ npx @waishnav/devspace init
 npx @waishnav/devspace serve
 npx @waishnav/devspace doctor
 npx @waishnav/devspace config get
+npx @waishnav/devspace config set host 0.0.0.0
 npx @waishnav/devspace config set publicBaseUrl https://devspace.example.com
 ```
 
+Changing `host` takes effect after restarting `devspace serve`. Use a specific
+interface address when possible. `0.0.0.0` exposes the service on every IPv4
+interface, so firewall access should be restricted accordingly.
+
+During `devspace init`, the port is followed by a separate local listen-address
+step. The later URL step first offers to keep an existing URL unchanged, then offers
+Localhost or Custom HTTPS URL. Localhost uses
+`http://localhost:<port>` automatically. Custom HTTPS URL waits for an explicit
+tunnel or reverse-proxy origin.
+
 ## Core Environment Variables
 
 | Variable | Purpose |
@@ -37,7 +48,7 @@ npx @waishnav/devspace config set publicBaseUrl https://devspace.example.com
 | `DEVSPACE_ALLOWED_HOSTS` | Optional Host header allowlist override. |
 | `DEVSPACE_OAUTH_OWNER_TOKEN` | Owner password for OAuth approval. Must be at least 16 characters. |
 | `DEVSPACE_WORKTREE_ROOT` | Directory for managed Git worktrees. Defaults to `~/.devspace/worktrees`. |
-| `DEVSPACE_STATE_DIR` | Directory for SQLite state. Defaults to `~/.local/share/devspace`. |
+| `DEVSPACE_STATE_DIR` | Directory for private SQLite state. Defaults to `~/.local/share/devspace`. |
 
 ## OAuth
 

docs/gotchas.md

@@ -15,15 +15,15 @@ If you installed globally, confirm npm's global bin directory is on `PATH`.
 
 ## Unsupported Node Version
 
-DevSpace requires Node `>=20.12 <27`.
+DevSpace requires Node `>=22.19 <27`.
 
 Check:
 
 ```bash
 node --version
 ```
 
-Install Node 22 LTS with your preferred version manager such as `nvm`, `fnm`, or
+Install Node 22.19 or newer with your preferred version manager such as `nvm`, `fnm`, or
 `mise`.
 
 ## `better-sqlite3` Could Not Load
@@ -100,6 +100,27 @@ Use this only for intentional local debugging:
 DEVSPACE_ALLOWED_HOSTS="*" npx @waishnav/devspace serve
 ```
 
+## OAuth Request Paths In Logs
+
+Configure the ChatGPT app with the full MCP endpoint:
+
+```text
+https://your-host.example.com/mcp
+```
+
+The public base URL stored by DevSpace is the origin without `/mcp`, while MCP
+clients connect to `/mcp`. Older DevSpace versions could log OAuth router
+requests such as `/register` or `/token` as `/` because Express rewrote the
+mounted router path before the response log was emitted. Current versions log
+the original request path.
+
+## OAuth `invalid_client` After Restart
+
+DevSpace persists dynamically registered OAuth clients and hashed access and
+refresh tokens in its SQLite state database. If upgrading from a version that
+kept OAuth state only in memory, remove and add the ChatGPT app one final time
+to obtain a persisted client ID. Later DevSpace restarts should reuse it.
+
 ## OAuth Redirect Host Rejected
 
 By default, DevSpace allows redirects for: