docs: castle is now the default; document the override table BU_CDP_HTTP is an override rather than a requirement, and /browser-status explains the lazy connection instead of showing a bare red light.
Igor Soarez igor@soarez.org
Tue, 28 Jul 2026 22:09:36 +0100
1 files changed,
18 insertions(+),
4 deletions(-)
jump to
M
FORK.md
→
FORK.md
@@ -45,11 +45,25 @@ same identifier works on macOS and Linux, which a local-path install could not
do — pi records those by resolved absolute path, and `settings.json` is shared across hosts via the dotfiles symlink. -Then point it at the browser: +Nothing else to configure: castle is the built-in default +(`DEFAULT_REMOTE_CDP` in `src/cdp/endpoint.ts`). -``` -export BU_CDP_HTTP=10.88.0.25:9223 -``` +## Choosing a browser + +| `BU_CDP_HTTP` | behaviour | +|---|---| +| unset | castle, falling back to this machine's browser if unreachable | +| `host:port` | that endpoint; **unreachable is a hard error** | +| `local` (also `localhost`, `off`, `none`, `0`, `no`) | upstream behaviour — this machine's own browser | + +The asymmetry is deliberate. An explicit endpoint is an instruction, so failing +to reach it must not quietly automate a different browser — that would drive +your own signed-in Chrome instead of the shared one. The default is only a +preference, so a laptop away from the wire network still gets the local browser. + +`/browser-status` names the resolved target and whether it is reachable. Note +the connection is **lazy**: nothing dials the browser until the first `browser_*` +tool runs, so a fresh session reports "not connected yet" rather than an error. `pi update` reconciles the clone to the configured ref rather than pulling stock from npm, so the patch cannot be silently reverted — which is exactly what the