docs: correct the "pi-studio has no bind flag" claim everywhere it was baked
Lint / hadolint (push) Successful in 10s
Lint / skill-floor (push) Successful in 14s
Lint / doc-drift (push) Failing after 18s
Lint / actionlint (push) Successful in 31s

1e4c238 fixed README; the same claim lived in three more places, all wrong
since pi-studio 0.9.60 added /studio --listen-all:

- rootfs/usr/local/bin/studio-expose header (and so its --help; the sed range
  grows 2,31p -> 2,35p so --help still ends at "runs it backgrounded.")
- pi-devbox-environment skill section 7: --listen-all as a third path, plus the
  0.10 whole-URL / 409 / "link looks damaged" notes, the published-port rule,
  --stop before --port, and the on-host curl 403-vs-empty-reply diagnostic
- Dockerfile.variant STUDIO_PORT comment

Bridge and --listen-all on one port: whichever starts second fails, measured
both ways on tor-ms22 (v1.11.2): Studio "listen EADDRINUSE ... 0.0.0.0:8765"
with the bridge up; studio-expose rc 1 on socat "bind(...): Address already in
use" with a 0.0.0.0 listener up. README's warning now says both directions.

Cost: studio-expose and the skill are in rootfs/, which base_tag hashes, so the
next release rebuilds the base (recomputed with the CI recipe: base-6f3b20266de1
at 1e4c238 -> base-26d425cea6c2 now). Noted in the CHANGELOG Unreleased entry.
No pin changes. lint-shell, dockerfile-directives and base-hash guards pass;
check-doc-drift is red only for the unrelated pi-extensions 750b2a8 -> 0d8e417.
This commit is contained in:
2026-10-14 19:27:42 +02:00
parent 1e4c238a83
commit a8f5b35d2a
5 changed files with 56 additions and 25 deletions
@@ -356,8 +356,8 @@ window: 0". Leave the indexing alone in this environment.
## 7. pi-studio reachability (only in the `-studio` variant)
Present only if `/opt/pi-studio` exists / the `studio_*` tools are in your tool
list. pi-studio **binds to `127.0.0.1` inside the container** with no host-bind
flag, so a plain `docker -p` publish can't reach it. Two supported paths:
list. By default pi-studio **binds to `127.0.0.1` inside the container**, so a
plain `docker -p` publish can't reach it. Three supported paths:
- **Host networking** (`network_mode: host`): container loopback == host
loopback; open the tokenized URL on the host. (Changes
@@ -365,10 +365,25 @@ flag, so a plain `docker -p` publish can't reach it. Two supported paths:
- **`studio-expose` bridge** (`STUDIO_EXPOSE=1` or run `studio-expose &`): a
`socat` relay from the container's external interface to its loopback, so a
published `127.0.0.1:PORT` + `ssh -L PORT:127.0.0.1:PORT host` reaches it.
- **`/studio --listen-all`** (pi-studio ≥ 0.9.60): binds `0.0.0.0`, so the
published port reaches it with no bridge; the printed URL still says
`127.0.0.1`. **Never on the same port as the bridge**: whichever starts
second fails with `EADDRINUSE`. `ss -ltnp | grep ":$STUDIO_PORT"` showing a
`socat` line means the bridge is up, so start Studio without `--listen-all`.
The real auth token comes from the `/studio` slash command (`/studio --status`
to reprint), **not** from `studio-expose`. For Graphviz, use `dot-watch` →
PNG (Studio renders Mermaid natively and previews PNG, but not SVG/DOT).
to reprint), **not** from `studio-expose`. Hand over the **whole** printed
URL: since pi-studio 0.10 it also carries `studioTabState` + `hostedWorkspace`
(or `docPath`/`watchFile`/… for `--watch`), and a token-only URL is answered
`409`. The URL wraps across TUI lines; if a side panel's text lands inside the
copy, Studio answers *"This link looks damaged…"*. Studio must run on the
**published** port (only the laptop side of `ssh -L` is free to choose), and
`--port` on a running server only warns, so `/studio --stop` first. On the
Docker host, `curl -s http://127.0.0.1:$STUDIO_PORT/` answering `403` means
the chain is up; an empty reply means Studio is down or on another port.
For Graphviz, use `dot-watch` → PNG (Studio renders Mermaid natively and
previews PNG, but not SVG/DOT).
## 8. MemPalace is the shared brain