FlowPad

Appearance

Run ​

A FlowPad runtime is a served webapp. It does not run JavaScript outside the browser. The "running" state means: a runtime record exists in <host-home>/runtimes/, the gateway is mounting /apps/flowpad/ from the package's dist/, and the page is reachable on the gateway port.

Default behaviour ​

If you ran a plain hivecast install followed by hivecast start, FlowPad already auto-starts. The default runtime registration is:

js
// projects/matrix-3/packages/hivecast/bin/hivecast.mjs:37
{ target: '@open-matrix/flowpad', runtimeKey: 'FLOWPAD', serve: true, autoStartPriority: 35 }

Verify:

bash
node projects/matrix-3/packages/hivecast/bin/hivecast.mjs status --home /tmp/matrix-home
node projects/matrix-3/packages/hivecast/bin/hivecast.mjs runtimes --home /tmp/matrix-home

# Browser:
#   http://127.0.0.1:3100/apps/flowpad/

Manual control ​

Bring it up explicitly:

bash
matrix up @open-matrix/flowpad --serve \
  --runtime-id FLOWPAD \
  --env hivecast \
  --startup auto \
  --restart always \
  --home /tmp/matrix-home

The flags follow the host-service CLI conventions (projects/matrix-3/packages/host-service/):

FlagEffect
--serveTell the gateway to mount the package's dist/ at /apps/<appName>/
--port <N>Pin the per-runtime port (otherwise auto-allocated)
--runtime-id <id>Stable id used in <host-home>/runtimes/<id>.json
--env <env>Environment block (dev, hivecast, …)
--startup autoStart automatically when Host Service starts
--restart alwaysRestart on crash

To stop:

bash
matrix down FLOWPAD --home /tmp/matrix-home

What happens at runtime ​

  1. Supervisor. Host Service spawns a runner process for @open-matrix/flowpad. Because FlowPad has no headless components (matrix.json says "components": []), the runner registers itself in system.runtimes but does not mount any actor.
  2. Gateway route. system-gateway-http reads the runtime record's serve: true flag and adds a static route at /apps/flowpad/ pointing at <package>/dist/.
  3. Browser load. A browser hitting /apps/flowpad/ receives dist/index.html. The bundle imports src/index.ts (compiled), which calls customElements.define for every component name and instantiates <flowpad-app>.
  4. Bootstrap. The page reads its target authority root from URL parameters or host-element attributes, opens a same-origin WebSocket to /nats-ws, and creates the in-page MatrixRuntime.
  5. FlowpadApp.onBootstrap mounts the eleven service children (db, flow-runner, vlm-eval, etc.) and registers them with LispEval.

Two-runtime dev topology ​

Per the project CLAUDE.md, you can run two FlowPad-bearing shells side by side — matrix-web for the platform role on port 5001 and matrix-edge for the device role on port 5002 — both heartbeating to the same local system.devices. Both shells will list FlowPad among their available webapps. There is no FlowPad-specific config for this topology; the runtime is the same in both cases.

Overriding defaults ​

A common need: target a different authority root or catalog mount.

http://127.0.0.1:3100/apps/flowpad/?authorityRoot=COM.NIMBLETEC.RICHARD-SANTOMAURO&catalog=COM.NIMBLETEC.RICHARD-SANTOMAURO/system.catalog

URL parameters are read in src/config/defaults.ts priority order. See Settings and addressing for the full list.

Confirming a healthy run ​

bash
# Status reports FLOWPAD healthy
hivecast status --home /tmp/matrix-home | jq '.runtimes.FLOWPAD'

# HTTP responds
curl -sf http://127.0.0.1:3100/apps/flowpad/ | head -3

# Page mounts <flowpad-app> (visible in DevTools elements panel after load)

If the runtime record exists but the page returns 404, the gateway hasn't picked up the static route — restart Host Service or check logs/runtimes/FLOWPAD.log for "serve route registered".

See also ​

Source: projects/matrix-3/packages/hivecast/bin/hivecast.mjs (default-runtime list) and the host-service CLI under projects/matrix-3/packages/host-service/.