v1.3.2 to v1.3.3

---

name: live-demo

description: >

Turn a working robium app into a public, interactive web demo: a

mission-control demo page (start/stop instance buttons, live boot

terminal, fleet budget), per-visitor simulator instances on Cloud Run

(scale-to-zero), and a visualizer handoff (Foxglove deep link or

self-hosted viewer). Use when: 'live demo', 'demo page', 'let visitors

drive the robot', 'try it live on the website', 'demo instance

start/stop', 'host the sim for the demo', choosing the demo visualizer,

or budgeting/deploying demo backends. Load after an app passes its smoke

(bridge/viewer mechanics) and integration (container patterns). Not for:

developer-facing visualization during a build (foxglove/rviz2) or

general website building.

---

# live-demo

Everything between "the app's smoke test is green" and "a stranger on the

website is driving the robot." This skill owns the demo architecture that

robium.ai/demos/nav-trial runs in production: a control page whose

Start/Stop buttons manage private, per-visitor simulator instances on

Cloud Run, a session gateway inside the app container, and a viewer

handoff. Every command, flag, and gotcha here was verified live

not a design sketch.

## When to use this skill

- Publishing any robium app as an interactive web demo, and every design

choice inside that: flow shape, page anatomy, instance lifecycle,

visualizer, budget, and the Cloud Run deployment.

- Debugging a deployed demo (instance won't boot, viewer can't connect,

status endpoint misroutes).

→ `gcloud run deploy` path, the sim flag set, billing modes, the gz/DDS

transport env vars, session affinity, VPC subnet sizing, deploy auth →

`cloud-run` (this skill owns the *orchestrator, gateway, and page*; the

deploy target under them is `cloud-run`'s).

- foxglove_bridge setup, layouts, or MCAP for *development* use →

- Container/compose patterns for the app itself → `integration`.

- Whether the app is *done* enough to demo → `testing` (smoke test

green is this skill's entry bar).

- Env reproducibility of the app → `environments`.

## Key directives

- **Delegation posture: embed.** The demo architecture (gateway contract,

Cloud Run tuning for sims, viewer decision table) exists nowhere

are `foxglove`'s; everything demo-shaped is embedded here.

- **A demo is a product surface: the smoke test extends to it.** <!-- id: demo-smoke-extends-product-surface --> The app's

demo scenario gets its own gated smoke (`make demo-smoke`): WebSocket

handshake through the gateway, `/start` claim, `/status` reaches

`ready`, intruder session rejected (409/403), one scripted goal

succeeds, `/shutdown` kills the container. Ship no demo without it.

- **Scale-to-zero is non-negotiable; per-session cost is explicit.** <!-- id: scale-to-zero-non-negotiable-explicit-cost -->

`min-instances=0` always. State the per-session cost implication of the

an "idle" demo bill silently.

- **One visitor, one instance, enforced in the gateway.** <!-- id: one-visitor-one-instance-gateway-enforced --> The session

UUID claims an instance; a live tunnel is never shareable; an idle claim

is takeable (reload semantics). Never rely on Cloud Run routing alone

for isolation.

- **Lifecycle belongs to something that outlives the instance.** <!-- id: lifecycle-needs-host-level-orchestrator --> The

in-container gateway cannot start or restart itself (it dies with the

button needs a host-level **orchestrator**. On Cloud Run the control

plane *is* that orchestrator, which is why this only becomes visible the

day you run the demo locally. Build it behind a `Driver` interface

(LocalDocker now, CloudRun later) rather than special-casing localhost,

keep it out of the data path (it hands the browser a per-instance host

and gets out of the way), and give it the fleet cap. See

`references/orchestrator-pattern.md`.

- **Be honest on the page.** <!-- id: honest-cold-boot-copy-on-page --> Cold-boot time (30–90 s, with self-restart

on unlucky boots), session caps, and busy states are stated in the

broken the moment it isn't.

## Quick start

The proven path (mission-control flow, Foxglove deep-link viewer):

nav/policy stack + `foxglove_bridge` on an internal port + an

auto-init node (set initial pose / whatever makes the app immediately

drivable) + the session gateway owning `$PORT`. Copy

`examples/demo_gateway.py` (verified) and adapt the two constants.

Gazebo+Nav2 stack):

```bash

gcloud run deploy demo-<app> --image=<image> \

--region=us-central1 --port=8765 \

--concurrency=4 --session-affinity \

--min-instances=0 --max-instances=5 --timeout=1800 \

--cpu=8 --memory=8Gi --cpu-boost --no-cpu-throttling \

--execution-environment=gen2 \

--set-env-vars=GZ_RELAY=127.0.0.1,GZ_IP=127.0.0.1,FASTDDS_BUILTIN_TRANSPORTS=UDPv4 \

--command=/entrypoint.sh --args="ros2,launch,<pkg>,demo.launch.py" \

--allow-unauthenticated --quiet

```

for the affinity cookie to work from your site's pages (see gotchas).

anatomy (see `references/demo-page.md`): Start/Stop buttons, terminal

majority, fleet budget line, viewer button gated on `ready`.

live URL; only then link it from the homepage proof/apps card

("Try the live demo →").

## Usage patterns

**Choose the demo flow.** Three shapes, in order of proven-ness:

| Flow | What the visitor gets | When |

| --- | --- | --- |

| **Mission-control page** (proven) | Start/Stop instance buttons, live boot terminal, fleet count, viewer opens on ready | Default. Honest about boot time; visitors see the machinery (which *is* the pitch for infra products).<!-- id: flow-mission-control-default --> |

| Deep-link only | One "open in Foxglove" link; connection cold-boots the instance | Minimal page work; boot happens behind the viewer's "connecting" spinner; needs the connection itself to hold CPU (request-based billing).<!-- id: flow-deep-link-minimal --> |

**Choose the visualizer** (verified facts, 2026-07-13):

| Option | Login | Layout preload | Embeddable | Verdict |

| --- | --- | --- | --- | --- |

| Self-hosted Lichtblick (open-source Foxglove fork, MPL) | None | ✓ (`globalThis.LICHTBLICK_SUITE_DEFAULT_LAYOUT` build hook) | ✓ (you control headers) | Frictionless but you own the build + browser-storage kiosk-wipe; new-tab use is solid, iframe needs care<!-- id: visualizer-lichtblick-self-hosted --> |

**Instance lifecycle contract** <!-- id: instance-lifecycle-gateway-contract --> (the gateway, `examples/demo_gateway.py`):

`POST /start?session=U` claims · `GET /status?session=U` → JSON

(`claimed/ready/rtf/nodes/uptime_s/remaining_s/fleet{running,budget}/log[]`),

409 for foreign sessions · ws upgrade tunnels to the bridge, one live

tunnel max (second → 503) · `POST /shutdown?session=U` → SIGINT PID 1 →

container exits · idle claims takeable · page sends a `pagehide`

sendBeacon shutdown. Full rationale in `references/gateway-pattern.md`.

**Show the demo where the proof lives.** <!-- id: demo-link-from-proof-card --> The homepage apps/proof card for

the app gets a primary "Try the live demo →" button to `/demos/<app>`;

the demo page carries the reproduction story (the brief that produced the

app) so the demo sells the plugin, not just the robot.

**Fleet/budget display.** <!-- id: fleet-budget-never-fetch-on-page-load --> Budget = `--max-instances`, stated statically

on the page. Live count comes from Cloud Monitoring's

`run.googleapis.com/container/instance_count` queried *by the gateway*

(metadata-server token + `roles/monitoring.viewer` on the runtime service

account), folded into `/status` and cached ~30 s. Never fetch fleet

drive-by visitor; show it only while a session runs.

## Platform gotchas

All verified in production, 2026-07-13 (details + fixes in

`references/cloud-run-tuning.md`), except a bullet dated otherwise:

- **Gazebo discovery needs help on Cloud Run** <!-- id: gazebo-discovery-cloud-run-boot-watchdog --> (no multicast):

`GZ_RELAY=127.0.0.1` + `GZ_IP=127.0.0.1`, and even then the unicast

watchdog** (no sim data within ~120 s → SIGINT PID 1 → fresh instance

on the client's reconnect).

Run's proxy pools keep-alive connections; closing without declaring it

= edge 503 "malformed response" (invisible in local testing).

drops unhandled signals to PID 1 and launch installs no SIGTERM

handler.

`*.run.app` host from your site (cross-site). Map a subdomain of the

site's domain to the service and use `credentials:'include'` +

exact-origin CORS, or affinity silently does nothing.

with no held connection freezes. Start-button flows need

`--no-cpu-throttling` (cost: idle-retention after sessions,

≈$0.20–0.40/session at 8 vCPU); connection-driven flows can stay

request-based since the ws holds CPU.

`FASTDDS_BUILTIN_TRANSPORTS=UDPv4` silences `open_and_lock_file` errors.

pinned constant merges every instance's ROS graph the moment two run at

once (two Gazebo `/clock` publishers → `Moved backwards in time,

re-publishing joint transforms!` forever). The orchestrator assigns the

lowest free ID (1–200) per instance.

- **WebSocket probes need `curl --http1.1`** <!-- id: websocket-probes-need-http1-subprotocol --> against https Cloud Run

(h2 negotiation breaks the upgrade), and `foxglove_bridge ≥3.x` expects

subprotocol `foxglove.sdk.v1` (the classic `foxglove.websocket.v1`

gets a misleading 400).

claims + abortable runs** <!-- id: single-instance-503-needs-abortable-takeable-claims --> (2026-07-15, user-corrected). On Cloud Run a

503 reroutes to a fresh instance, so "second viewer gets 503" only holds

with a fleet; a lone local instance can't reroute. Gradio keeps running a

generator job after its SSE client disconnects, so a page refresh orphans

the in-flight run holding the app's run lock, and the refreshed page (new

session UUID) then gets `/start` 503 + `/status` 409 forever. Fix for

single-instance local demos: make runs abortable (a `threading.Event` per

step), have `/start` always take the claim, have the page retry `/start`

on 409, and acquire the run lock with a 30 s timeout.

## Customization

- **Different app:** the gateway and page are app-agnostic; the app-side

work is the `demo` launch (stack + bridge + auto-init making it

instantly drivable) and picking what "ready" means (nav: initial pose

set + RTF measured; a policy demo might be "model loaded + env reset").

- **Different budget/size:** `--max-instances` (budget), `--cpu/--memory`

(a Gazebo+Nav2 stack wanted 8 vCPU for RTF ≈ 1; measure with the

`DEMO READY rtf=` log line), `--timeout` (session cap).

- **Non-ROS demos:** the gateway pattern (claim/status/shutdown +

ws tunnel) works for any ws-speaking backend; swap the bridge for your

stream and the status file for your readiness signal. A second proven

backend shape is a Gradio/FastAPI-mount gateway (`gr.mount_gradio_app`

ws-tunnel one (2026-07-15), worth reaching for so it isn't re-derived.

For a CPU-only demo image, install torch from the CPU wheel index

(`--index-url https://download.pytorch.org/whl/cpu`): the default wheel

drags in the full multi-GB CUDA stack (nvidia-cudnn/cusolver) a CPU

+ vla-trial).

## References

orchestrator/gateway split, the local-vs-cloud `Driver` seam,

per-instance `ROS_DOMAIN_ID`, the in-browser PTY shell, the local dev

costs, gz/FastDDS env fixes, same-site affinity, fleet monitoring IAM.

The general, non-demo-specific form of these mechanics is owned by the

`cloud-run` skill; this file keeps the demo-tuning specifics.

flow, honesty copy, where demo links go on the site.

2026-07-13, nav-trial live demo on robium.org).

- Upstream: [Cloud Run docs](https://cloud.google.com/run/docs),

[Foxglove deep links](https://docs.foxglove.dev/docs/visualization/shareable-links),

[gz-transport relay](https://gazebosim.org/api/transport/14/relay.html),

[Lichtblick](https://github.com/lichtblick-suite/lichtblick). Sibling

skills: `cloud-run` (the Cloud Run deploy mechanics/gotchas this demo

target sits on), `foxglove` (bridge/viewer), `integration` (containers),

`testing` (the entry bar), `environments` (app env).

## Changelog

<!-- One dated line per battle-tested change, added by skill-author hardening sessions. -->

- 1.3.2 (2026-08-01): decision-table rows anchored (learning-engine Phase 1 follow-up); no content changes.

- 1.3.1 (2026-08-01): anchor IDs added to claim-bearing items (learning-engine Phase 1); no content changes.

- 1.3.0 (2026-08-01): the Cloud Run deploy mechanics/gotchas now have their

References) delegating the build → deploy path, flag set, billing modes,

gz/DDS transport env, affinity, and VPC sizing to it, while this skill keeps

ownership of the orchestrator, session gateway, and mission-control page. The

demo-specific cloud-run-tuning notes stay here as the tuned specifics.

gotcha for single-instance local demos (a lone instance can't reroute a

503 the way a Cloud Run fleet does; Gradio orphans a generator job after

its SSE client disconnects, so a refresh deadlocks with /start 503 +

and a 30 s run-lock timeout); Customization Non-ROS demos gains a second

proven gateway shape (Gradio/FastAPI mount via gr.mount_gradio_app) and a

CPU-wheel note (install torch from the CPU index so CPU demo images skip

the multi-GB CUDA stack, seen 2x).

(gateway same-site at demo.robium.ai, CORS origin https://robium.ai).

Refreshed the current-state domain references in SKILL.md,

references/demo-page.md, and examples/demo_gateway.py. Dated 1.0.0/1.1.0

changelog history left unchanged.

new `references/orchestrator-pattern.md` (the gateway can't manage its

own lifecycle and a browser can't start containers, so lifecycle needs a

host-level orchestrator; the local-vs-cloud `Driver` seam; per-instance

`ROS_DOMAIN_ID`; PTY-over-WebSocket in-browser shell; local dev loop),

plus a Key directive and a gotcha pointing at it. Also: Direct VPC egress

needs a `/24`-sized subnet for the instance pool (a `/28` fails deploy),

and the stale-host `setInterval` trap that dynamic per-instance backends

its egress-block verification is still pending.

- 1.0.0 (2026-07-13): created from the nav-trial live-demo deployment on

and visualizer decision table, all production-verified same day.