8e34589f25
* docs(web): align the public surface with Blue Stage Carry the TUI's semantic Blue Stage palette into the website, keep Signal Gold on the whale and human-attention accents, and enforce the cross-surface token contract in tests. Route existing Install and Providers topics to their first-party pages and document the loopback-only browser client's real bootstrap and authentication boundaries. Signed-off-by: Hunter B <hmbown@gmail.com> * docs: keep translated READMEs in public-surface parity Mirror the browser-client command and guide link across all six translated READMEs, with the source stamp updated to the exact English README. This restores the repository translation gate without translating or reordering executable commands. Signed-off-by: Hunter B <hmbown@gmail.com> --------- Signed-off-by: Hunter B <hmbown@gmail.com>
3.4 KiB
Local browser client
codewhale web opens Codewhale's embedded browser client over the canonical
Runtime API. It is a local surface: the server always binds to
127.0.0.1, cannot be rebound to a LAN address, and cannot run with Runtime
authentication disabled.
Start it
From the workspace Codewhale should operate in, run:
codewhale web
The default address is http://127.0.0.1:7878. To avoid a local port
collision, choose another loopback port:
codewhale web --port 8788
Codewhale starts the Runtime API, serves the dependency-free client embedded
in the installed binary, and asks the operating system to open the launch URL
in the default browser. Stop the process with Ctrl+C; the browser session
ends with it.
What the browser can do
The v0.9.1 client provides a responsive thread and search rail, Runtime-owned session facts, transcript and tool receipts, and a composer. It can create, select, rename, and archive threads; start or steer turns; interrupt work; resolve approvals; and answer Runtime user-input requests.
The browser is another view of the same local Runtime. It does not create a second cloud account, copy provider credentials into browser storage, or weaken the configured approval and sandbox policies.
Authentication boundary
The browser-launch URL contains a random, short-lived, one-time bootstrap
capability. It never contains the Runtime bearer token. A loopback request
exchanges the capability for an HttpOnly, SameSite=Strict, process-local
session cookie and immediately invalidates the capability.
Reused, expired, malformed, and non-loopback bootstrap attempts fail closed. The Runtime token is not placed in rendered HTML, browser storage, URL queries or fragments, or browser-launch arguments. The one-time bootstrap value briefly passes through the operating system's browser launcher; it is single-use and short-lived, but a hostile process already running as the same OS user remains inside the local trust boundary.
Cookie-authenticated state-changing requests must also present the exact local web origin. Cross-origin browser requests are rejected. Existing explicit bearer and Runtime-token-header clients retain their normal Runtime API behavior.
Local means local
codewhale web accepts only --port; there is no --host or insecure-auth
option on this command. Do not treat it as a public website or expose its port
directly through router forwarding, a public reverse proxy, or a tunnel.
The separate codewhale app-server --mobile and --http modes have different
deployment and authentication contracts. Read RUNTIME_API.md
before operating either one, especially before selecting a non-loopback bind.
Troubleshooting
- If port
7878is occupied, pass an unused--portvalue. - If the browser cannot be opened, the command exits with an error rather than
printing or leaving a reusable bootstrap capability behind. Check the
operating system's default-browser setup, then start
codewhale webagain. - If the page loads but a provider is unavailable, inspect
codewhale doctorand/provider; the web command does not configure or move provider credentials. - If a session expired, stop and restart
codewhale webto mint a new process-local session. Reusing an old bootstrap URL is expected to fail.
For integration endpoints, headers, events, and the complete web-session contract, see RUNTIME_API.md.