| 1 | # Local browser client |
| 2 | |
| 3 | > 阅读简体中文版：[zh_hans/WEB.md](zh_hans/WEB.md)。 |
| 4 | |
| 5 | `codewhale web` opens Codewhale's embedded browser client over the canonical |
| 6 | Runtime API. It is a local surface: the server always binds to |
| 7 | `127.0.0.1`, cannot be rebound to a LAN address, and cannot run with Runtime |
| 8 | authentication disabled. |
| 9 | |
| 10 | ## Start it |
| 11 | |
| 12 | From the workspace Codewhale should operate in, run: |
| 13 | |
| 14 | ```bash |
| 15 | codewhale web |
| 16 | ``` |
| 17 | |
| 18 | The default address is `http://127.0.0.1:7878`. To avoid a local port |
| 19 | collision, choose another loopback port: |
| 20 | |
| 21 | ```bash |
| 22 | codewhale web --port 8788 |
| 23 | ``` |
| 24 | |
| 25 | Codewhale starts the Runtime API, serves the dependency-free client embedded |
| 26 | in the installed binary, prints a single-use launch URL, and asks the operating |
| 27 | system to open that URL in the default browser. If the browser does not open, |
| 28 | use the printed URL within ten minutes. Stop the process with `Ctrl+C`; the |
| 29 | browser session ends with it. |
| 30 | |
| 31 | ## What the browser can do |
| 32 | |
| 33 | The embedded client provides a responsive thread and search rail, Runtime-owned |
| 34 | session facts, transcript and tool receipts, and a composer. It can create, |
| 35 | select, rename, and archive threads; start or steer turns; interrupt work; |
| 36 | resolve approvals; and answer Runtime user-input requests. |
| 37 | |
| 38 | The browser is another view of the same local Runtime. It does not create a |
| 39 | second cloud account, copy provider credentials into browser storage, or |
| 40 | weaken the configured approval and sandbox policies. |
| 41 | |
| 42 | ## Authentication boundary |
| 43 | |
| 44 | The browser-launch URL contains a random, short-lived, one-time bootstrap |
| 45 | capability. It never contains the Runtime bearer token. A loopback request |
| 46 | exchanges the capability for an `HttpOnly`, `SameSite=Strict`, process-local |
| 47 | session cookie and immediately invalidates the capability. |
| 48 | |
| 49 | Reused, expired, malformed, and non-loopback bootstrap attempts fail closed. |
| 50 | The Runtime token is not placed in rendered HTML, browser storage, URL |
| 51 | queries or fragments, or browser-launch arguments. The one-time bootstrap |
| 52 | value is printed in the local terminal and briefly passes through the operating |
| 53 | system's browser launcher. It is single-use and expires after ten minutes, but |
| 54 | a hostile process already running as the same OS user remains inside the local |
| 55 | trust boundary. |
| 56 | |
| 57 | Cookie-authenticated state-changing requests must also present the exact |
| 58 | local web origin. Cross-origin browser requests are rejected. Existing |
| 59 | explicit bearer and Runtime-token-header clients retain their normal Runtime |
| 60 | API behavior. |
| 61 | |
| 62 | ## Local means local |
| 63 | |
| 64 | `codewhale web` accepts only `--port`; there is no `--host` or insecure-auth |
| 65 | option on this command. Do not treat it as a public website or expose its port |
| 66 | directly through router forwarding, a public reverse proxy, or a tunnel. |
| 67 | |
| 68 | The separate `codewhale app-server --mobile` and `--http` modes have different |
| 69 | deployment and authentication contracts. Read [RUNTIME_API.md](RUNTIME_API.md) |
| 70 | before operating either one, especially before selecting a non-loopback bind. |
| 71 | |
| 72 | ## Troubleshooting |
| 73 | |
| 74 | - If port `7878` is occupied, pass an unused `--port` value. |
| 75 | - If the browser does not open, copy the printed single-use bootstrap URL into |
| 76 | a browser on the same machine within ten minutes. Start `codewhale web` again |
| 77 | if that URL has already been used or expired. |
| 78 | - If the page loads but a provider is unavailable, inspect `codewhale doctor` |
| 79 | and `/provider`; the web command does not configure or move provider |
| 80 | credentials. |
| 81 | - If a session expired, stop and restart `codewhale web` to mint a new |
| 82 | process-local session. Reusing an old bootstrap URL is expected to fail. |
| 83 | |
| 84 | For integration endpoints, headers, events, and the complete web-session |
| 85 | contract, see [RUNTIME_API.md](RUNTIME_API.md). |
| 86 |