Launching the meta-styles demo
Four processes make up the judged demo stack: a static/app surface on
:8000, the mock-ig-bot on :8904, the meta-api-proxy on :8905, and the
wardrobe-service on :8906 (the real prior-work Instagram bot on :8903 is a
separate, local-only service never started by this stack). There are three
launch modes — judged mock, mock-remote (tailnet link), and LIVE_IG — and
the single governing rule is: check what is already running and in which
mode before launching anything, because a listening port does not tell
you the mode. All launch/ops steps here are read-or-process operations;
any code change is governed by the compliance skill.
Check live state first (never assume a fresh setup)
ss -ltnp | grep -E ':(8000|8904|8905|8906)\b' — is the stack up?
(Port :8080 on this host is open-webui, not part of this project.)
ps -o pid,lstart,cmd on those PIDs. The cmd field decides the mode:
python3 -m http.server 8000 = plain mock static surface;
node live-proxy-server.js --port 8000 ... = live OR mock-remote.
ls app/ig-runtime-config.js (gitignored): it exists → the mode field
inside says live (generated by start.sh LIVE_IG=1) or mock-remote
(hand-written) — read it, never trust the port alone; absent → plain
python-static mock.
- Compare
mtimes of */server.js files against process start times: a
delegation that landed after launch means the running processes are
stale (Node requires once at startup) — restart before testing.
curl every endpoint before reporting anything as working.
Mode 1 — judged mock (local one-shot)
sh start.sh
Resolves the Meta API key from $MODEL_API_KEY or by parsing
.env/secrets (hyphenated keys — parse, never source, never print).
Serves http://localhost:8000/mock-dm.html via plain python static.
CORS rule: the mock bot trusts the exact origin http://localhost:8000
and rejects http://127.0.0.1:8000 (and every other origin) — test and
share links with localhost only, or the POSTs fail client-side with no
server-visible error.
Mode 2 — mock-remote (tailnet/second-device link)
start.sh cannot serve this mode; hand-launch. Prerequisites:
app/ig-runtime-config.js (gitignored, may already exist — do not
commit, never put real tokens in it) setting:
(function (g) { g.__IG_RUNTIME__ = {
mode: "mock-remote",
botBase: "/ig",
proxyBase: "/api",
statusBase: "/wardrobe"
}; })(typeof globalThis !== "undefined" ? globalThis : this);
All three upstreams bound (start the bot, proxy, wardrobe first), then:
MODEL_API_KEY=<from .env/secrets, exported silently> \
node live-proxy-server.js --port 8000 --bot http://127.0.0.1:8904 \
--proxy http://127.0.0.1:8905 --wardrobe http://127.0.0.1:8906 --dir app
The proxy rewrites the outbound Origin to the upstream's one trusted
value and strips /ig/mock/* to the bot's bare /mock/* routes; the
client pages gate liveness on the explicit mode field, not on
botBase shape (landed in chat.html and mock-dm.html — commit 6c2c77a).
Remote entry: https://<tailnet-host>:8446/mock-dm.html (tailscale serve
already maps :8446 → 127.0.0.1:8000; check tailscale serve status --json if the link does not resolve). The token field defaults to the
non-secret SYNTH_mock_token; the operator types nothing.
Mode 3 — live Instagram
LIVE_IG=1 sh start.sh
Requires the real bot already running on 127.0.0.1:8903 and read tokens
in .env/secrets; generates app/ig-runtime-config.js (removed on exit)
and serves the app through live-proxy-server.js same-origin. Anything
that can act on a real person (send, notify) stays gated by the
send-approval rule in the compliance skill — read section "A capability
that writes/sends to a real external user" before touching live mode.
Verify (read-only, before calling any mode "the demo")
- Four listeners:
ss -ltnp matches the table above.
curl http://127.0.0.1:8905/health → {"ok":true,...} (keyPresent
true means the Meta key loaded; keyless runs on labelled fallbacks are
expected, not an error, when no key is configured).
curl -H "Origin: <the origin you will actually use>" against
/ig/shares: 200 proves the proxy path for that origin.
- Pristine-thread check after a reset:
{"items":[],"next_cursor":null}.
curl http://127.0.0.1:8906/wardrobe/status → mode, bot_base,
pieces_count sane (no /health route there; 404s are fine).
- Page 200 at
http://localhost:8000/mock-dm.html (or the tailnet URL).
- For any UI change, verify in a real browser against the SERVED URL, not
the source file — a stale process or wrong-mode server passes greps.
Restart / clean slate
- Kill the whole stack (all four PIDs, or the tracked launcher job — one
SIGTERM to its PID cleans up the children via its trap).
- Only when a pristine demo is wanted:
rm mock-ig-bot/data/catalog/*.bin
(synthetic demo data only — never do this against a real account's
catalog), and wipe/restart so the share history and wardrobe cursor
reset.
- Relaunch in the wanted mode and re-verify read-only, never by issuing
fresh writes that pollute the demo thread again.
- server.js changes always need a process restart; static
.html/.js
served files are read fresh per request. After restarting the
wardrobe, its first poll re-walks shares and logs catch-up lines —
expected, not a bug.
Pitfalls
- A green health check does not prove the mode — the live-proxy on :8000
can be relaying the real Instagram bot; check
ps cmd +
ig-runtime-config.js before presenting anything as "the mock".
- Every hackathon-code change goes through the compliance skill's
delegation rules; a delegation landing after launch leaves stale
processes serving old code (restart the matching PIDs).
- If the connectivity banner or operator-button errors claim live
behavior in a mock-remote session, fix the
IS_LIVE mode gate — never
paper over it in the banner text.
- Secrets stay out of everything:
MODEL_API_KEY rides the process
environment only; live-mode runtime configs carry read tokens and are
gitignored — if one exists, verify .gitignore and git status before
any commit.
1---2name: demo-launch3description: "Use when launching, restarting, or verifying the meta-styles local demo stack (mock, live, or mock-remote)."4version: 1.0.05author: Bramble6license: MIT7metadata:8 source: https://skillmd.com/skills/codepilots/demo-launch9 hermes:10 tags: [meta-styles, demo, launch, mock-ig-bot, wardrobe-service]11 related_skills: [meta-hackathon-compliance]12---1314# Launching the meta-styles demo1516Four processes make up the judged demo stack: a static/app surface on17:8000, the mock-ig-bot on :8904, the meta-api-proxy on :8905, and the18wardrobe-service on :8906 (the real prior-work Instagram bot on :8903 is a19separate, local-only service never started by this stack). There are three20launch modes — judged mock, mock-remote (tailnet link), and LIVE_IG — and21the single governing rule is: **check what is already running and in which22mode before launching anything**, because a listening port does not tell23you the mode. All launch/ops steps here are read-or-process operations;24any code change is governed by the compliance skill.2526## Check live state first (never assume a fresh setup)27281. `ss -ltnp | grep -E ':(8000|8904|8905|8906)\b'` — is the stack up?29 (Port :8080 on this host is open-webui, not part of this project.)302. `ps -o pid,lstart,cmd` on those PIDs. The `cmd` field decides the mode:31 `python3 -m http.server 8000` = plain mock static surface;32 `node live-proxy-server.js --port 8000 ...` = live OR mock-remote.333. `ls app/ig-runtime-config.js` (gitignored): it exists → the mode field34 inside says `live` (generated by start.sh LIVE_IG=1) or `mock-remote`35 (hand-written) — read it, never trust the port alone; absent → plain36 python-static mock.374. Compare `mtimes` of `*/server.js` files against process start times: a38 delegation that landed after launch means the running processes are39 stale (Node requires once at startup) — restart before testing.405. `curl` every endpoint before reporting anything as working.4142## Mode 1 — judged mock (local one-shot)4344 sh start.sh4546Resolves the Meta API key from `$MODEL_API_KEY` or by parsing47`.env/secrets` (hyphenated keys — parse, never `source`, never print).48Serves `http://localhost:8000/mock-dm.html` via plain python static.4950CORS rule: the mock bot trusts the exact origin `http://localhost:8000`51and rejects `http://127.0.0.1:8000` (and every other origin) — test and52share links with `localhost` only, or the POSTs fail client-side with no53server-visible error.5455## Mode 2 — mock-remote (tailnet/second-device link)5657start.sh cannot serve this mode; hand-launch. Prerequisites:58591. `app/ig-runtime-config.js` (gitignored, may already exist — do not60 commit, never put real tokens in it) setting:6162 (function (g) { g.__IG_RUNTIME__ = {63 mode: "mock-remote",64 botBase: "/ig",65 proxyBase: "/api",66 statusBase: "/wardrobe"67 }; })(typeof globalThis !== "undefined" ? globalThis : this);68692. All three upstreams bound (start the bot, proxy, wardrobe first), then:7071 MODEL_API_KEY=<from .env/secrets, exported silently> \72 node live-proxy-server.js --port 8000 --bot http://127.0.0.1:8904 \73 --proxy http://127.0.0.1:8905 --wardrobe http://127.0.0.1:8906 --dir app7475The proxy rewrites the outbound `Origin` to the upstream's one trusted76value and strips `/ig/mock/*` to the bot's bare `/mock/*` routes; the77client pages gate liveness on the explicit `mode` field, not on78`botBase` shape (landed in chat.html and mock-dm.html — commit `6c2c77a`).79Remote entry: `https://<tailnet-host>:8446/mock-dm.html` (tailscale serve80already maps :8446 → 127.0.0.1:8000; check `tailscale serve status81--json` if the link does not resolve). The token field defaults to the82non-secret `SYNTH_mock_token`; the operator types nothing.8384## Mode 3 — live Instagram8586 LIVE_IG=1 sh start.sh8788Requires the real bot already running on 127.0.0.1:8903 and read tokens89in `.env/secrets`; generates `app/ig-runtime-config.js` (removed on exit)90and serves the app through live-proxy-server.js same-origin. Anything91that can act on a real person (send, notify) stays gated by the92send-approval rule in the compliance skill — read section "A capability93that writes/sends to a real external user" before touching live mode.9495## Verify (read-only, before calling any mode "the demo")9697- Four listeners: `ss -ltnp` matches the table above.98- `curl http://127.0.0.1:8905/health` → `{"ok":true,...}` (`keyPresent`99 true means the Meta key loaded; keyless runs on labelled fallbacks are100 expected, not an error, when no key is configured).101- `curl -H "Origin: <the origin you will actually use>"` against102 `/ig/shares`: 200 proves the proxy path for that origin.103- Pristine-thread check after a reset: `{"items":[],"next_cursor":null}`.104- `curl http://127.0.0.1:8906/wardrobe/status` → `mode`, `bot_base`,105 `pieces_count` sane (no `/health` route there; 404s are fine).106- Page 200 at `http://localhost:8000/mock-dm.html` (or the tailnet URL).107- For any UI change, verify in a real browser against the SERVED URL, not108 the source file — a stale process or wrong-mode server passes greps.109110## Restart / clean slate1111121. Kill the whole stack (all four PIDs, or the tracked launcher job — one113 SIGTERM to its PID cleans up the children via its trap).1142. Only when a pristine demo is wanted: `rm mock-ig-bot/data/catalog/*.bin`115 (synthetic demo data only — never do this against a real account's116 catalog), and wipe/restart so the share history and wardrobe cursor117 reset.1183. Relaunch in the wanted mode and re-verify read-only, never by issuing119 fresh writes that pollute the demo thread again.1204. server.js changes always need a process restart; static `.html`/`.js`121 served files are read fresh per request. After restarting the122 wardrobe, its first poll re-walks shares and logs catch-up lines —123 expected, not a bug.124125## Pitfalls126127- A green health check does not prove the mode — the live-proxy on :8000128 can be relaying the real Instagram bot; check `ps cmd` +129 `ig-runtime-config.js` before presenting anything as "the mock".130- Every hackathon-code change goes through the compliance skill's131 delegation rules; a delegation landing after launch leaves stale132 processes serving old code (restart the matching PIDs).133- If the connectivity banner or operator-button errors claim live134 behavior in a mock-remote session, fix the `IS_LIVE` mode gate — never135 paper over it in the banner text.136- Secrets stay out of everything: `MODEL_API_KEY` rides the process137 environment only; live-mode runtime configs carry read tokens and are138 gitignored — if one exists, verify `.gitignore` and `git status` before139 any commit.