| 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, and asks the operating system to open the launch URL |
| 25 | in the default browser. Stop the process with `Ctrl+C`; the browser session |
| 26 | ends with it. |
| 27 | |
| 28 | ## What the browser can do |
| 29 | |
| 30 | The v0.9.1 client provides a responsive thread and search rail, Runtime-owned |
| 31 | session facts, transcript and tool receipts, and a composer. It can create, |
| 32 | select, rename, and archive threads; start or steer turns; interrupt work; |
| 33 | resolve approvals; and answer Runtime user-input requests. |
| 34 | |
| 35 | The browser is another view of the same local Runtime. It does not create a |
| 36 | second cloud account, copy provider credentials into browser storage, or |
| 37 | weaken the configured approval and sandbox policies. |
| 38 | |
| 39 | ## Authentication boundary |
| 40 | |
| 41 | The browser-launch URL contains a random, short-lived, one-time bootstrap |
| 42 | capability. It never contains the Runtime bearer token. A loopback request |
| 43 | exchanges the capability for an `HttpOnly`, `SameSite=Strict`, process-local |
| 44 | session cookie and immediately invalidates the capability. |
| 45 | |
| 46 | Reused, expired, malformed, and non-loopback bootstrap attempts fail closed. |
| 47 | The Runtime token is not placed in rendered HTML, browser storage, URL |
| 48 | queries or fragments, or browser-launch arguments. The one-time bootstrap |
| 49 | value briefly passes through the operating system's browser launcher; it is |
| 50 | single-use and short-lived, but a hostile process already running as the same |
| 51 | OS user remains inside the local trust boundary. |
| 52 | |
| 53 | Cookie-authenticated state-changing requests must also present the exact |
| 54 | local web origin. Cross-origin browser requests are rejected. Existing |
| 55 | explicit bearer and Runtime-token-header clients retain their normal Runtime |
| 56 | API behavior. |
| 57 | |
| 58 | ## Local means local |
| 59 | |
| 60 | `codewhale web` accepts only `--port`; there is no `--host` or insecure-auth |
| 61 | option on this command. Do not treat it as a public website or expose its port |
| 62 | directly through router forwarding, a public reverse proxy, or a tunnel. |
| 63 | |
| 64 | The separate `codewhale app-server --mobile` and `--http` modes have different |
| 65 | deployment and authentication contracts. Read [RUNTIME_API.md](RUNTIME_API.md) |
| 66 | before operating either one, especially before selecting a non-loopback bind. |
| 67 | |
| 68 | ## Troubleshooting |
| 69 | |
| 70 | - If port `7878` is occupied, pass an unused `--port` value. |
| 71 | - If the browser cannot be opened, the command exits with an error rather than |
| 72 | printing or leaving a reusable bootstrap capability behind. Check the |
| 73 | operating system's default-browser setup, then start `codewhale web` again. |
| 74 | - If the page loads but a provider is unavailable, inspect `codewhale doctor` |
| 75 | and `/provider`; the web command does not configure or move provider |
| 76 | credentials. |
| 77 | - If a session expired, stop and restart `codewhale web` to mint a new |
| 78 | process-local session. Reusing an old bootstrap URL is expected to fail. |
| 79 | |
| 80 | For integration endpoints, headers, events, and the complete web-session |
| 81 | contract, see [RUNTIME_API.md](RUNTIME_API.md). |
| 82 |