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