docs(cloud): document remote web UI preview (#2434)

Co-authored-by: Aqil Aziz <aqilaziz@users.noreply.github.com>

.env.example

@@ -51,6 +51,10 @@ JWT_TOKEN=
 OPENHUMAN_CORE_PORT=7788
 # [optional] Default: http://127.0.0.1:7788/rpc
 OPENHUMAN_CORE_RPC_URL=http://127.0.0.1:7788/rpc
+# [optional] Comma-separated browser origins allowed to call /rpc with the
+# Authorization bearer. Tauri and loopback Vite origins are allowed by default.
+# Set this when serving a private web UI preview from a non-loopback origin.
+# OPENHUMAN_CORE_ALLOWED_ORIGINS=https://openhuman-ui.example.com
 # Core RPC bearer token. Single source of truth for /rpc auth.
 #  - Tauri desktop: set automatically by the shell — leave blank.
 #  - Docker / cloud / VPS: REQUIRED. Generate with `openssl rand -hex 32`.

gitbooks/features/cloud-deploy.md

@@ -31,6 +31,52 @@ in `app/.env.local` and launch.
 
 ---
 
+## Remote UI choices
+
+OpenHuman's supported remote deployment is **core remote, UI local**: run
+`openhuman-core` on a Linux server and point a desktop client at that RPC URL.
+The deployed core does not serve the full React/Tauri UI as a production web
+app yet. Desktop-only features still need the Tauri shell, including tray
+controls, native deep links, CEF account scanners, OS keychain integration, and
+window/screen affordances.
+
+For a browser-accessible UI on a private server today, use the Vite web build as
+a development/preview surface against the remote core:
+
+```bash
+# On the server, run the core with an explicit token.
+export OPENHUMAN_CORE_HOST=0.0.0.0
+export OPENHUMAN_CORE_PORT=7788
+export OPENHUMAN_CORE_TOKEN="$(openssl rand -hex 32)"
+openhuman-core serve
+
+# In another shell on the server, serve the UI only on loopback.
+pnpm --dir app dev -- --host 127.0.0.1 --port 1420
+```
+
+Then tunnel both ports from your workstation:
+
+```bash
+ssh -L 1420:127.0.0.1:1420 -L 7788:127.0.0.1:7788 user@server
+```
+
+Open `http://127.0.0.1:1420`, choose the remote/core option on the first-run
+screen, and enter `http://127.0.0.1:7788/rpc` plus the
+`OPENHUMAN_CORE_TOKEN` value from the server.
+
+If you serve the browser UI from a non-loopback origin, add that exact origin to
+the core's CORS allowlist:
+
+```bash
+export OPENHUMAN_CORE_ALLOWED_ORIGINS="https://openhuman-ui.example.com"
+```
+
+Loopback Vite origins such as `http://127.0.0.1:1420` and
+`http://localhost:1420` are allowed automatically. Public `http://` origins are
+not recommended because every RPC call carries the bearer token.
+
+---
+
 ## Single source of truth for the bearer token
 
 Every `/rpc` call carries `Authorization: Bearer <token>`. The core has two

gitbooks/features/platform.md

@@ -73,6 +73,21 @@ The shell is a delivery vehicle (windowing, process lifecycle, IPC). All product
 
 ***
 
+## Remote/headless usage
+
+Linux servers can host the Rust core without a desktop session. The production
+shape is a remote `openhuman-core` JSON-RPC service plus a local desktop client
+configured with that core URL and bearer token.
+
+A private browser UI is possible for development/preview by serving the Vite
+frontend and pointing it at the remote core, but it is not a full replacement
+for the desktop shell. Native deep links, tray controls, OS keychain access, CEF
+account scanners, and screen/window integrations still require the Tauri app.
+See [Cloud Deploy](cloud-deploy.md#remote-ui-choices) for the current remote UI
+setup.
+
+***
+
 ## Real-time communication
 
 The desktop app maintains a persistent connection to the OpenHuman backend. Responses stream as they are generated; outputs appear progressively, not after a hang. If the network drops, the app reconnects automatically with progressive backoff.