#163 - [ops] Single `make demo` target — provision + install + seed + verify a fresh Hero OS demo VM in one command - lhumina_code/home

mik-tf commented

2026-04-24 03:33:33 +00:00

Owner

Why

Today spinning up a Hero OS demo from scratch requires: provisioning a TF Grid VM (Terraform), base install (hero_skills install-all + manual deps for what the nu-shell installers miss — #128), patching hero_proc action envs to add AIBROKER_API_ENDPOINT / ROUTING_MODE / etc., copying FORGEJO_TOKEN into hero_books env, re-running seeds with schema migrations, cloning doc libraries, verifying grounding. Each step is its own troubleshooting adventure.

Once the prerequisites from #160's §Reproducibility-Path land — upstream fixes merged, hero_zero_seed formalized (#XYZ), rootfs sized right — the whole flow should collapse to a single command.

Target UX

On an operator's laptop, with TFGRID_MNEMONIC + FORGEJO_TOKEN in env:

cd lhumina_code/hero_zero/deploy/single-vm
make demo ENV=heronu         # ~30-45 min on fresh VM, zero prompts

Successful exit means: VM exists, all services running, all libraries indexed, OSIS seeded across 5 contexts, AI Assistant answers a grounded test query, dashboard accessible via TF Grid gateway.

Failed exit means: one numbered step failed, with the log tailed and pointer to troubleshooting. No half-finished state.

Implementation sketch

deploy/single-vm/Makefile gains:

demo: tf-apply ssh-wait bootstrap install start seed libraries verify

tf-apply:
	cd tf && terraform init && terraform apply -auto-approve

ssh-wait:
	scripts/wait_for_ssh.sh $(shell terraform output -raw mycelium_ip)

bootstrap:
	scripts/bootstrap_vm.sh $(IP)         # apt deps, nu install, user setup

install:
	ssh driver@$(IP) 'cd ~/hero/code/hero_skills/tools && nu -c "use modules/*; service_install_all"'

start:
	ssh driver@$(IP) 'hero_proc start hero_router hero_osis ... hero_agent ...'

seed:
	ssh driver@$(IP) 'hero_zero_seed --all-contexts --all-domains'

libraries:
	ssh driver@$(IP) 'echo "$$LIBRARIES" > ~/hero/var/books/libraries.txt && hero_proc restart hero_books'

verify:
	scripts/verify_demo.sh $(IP)          # health checks + smoke grounding query

Each script is small, idempotent, and has a --resume mode so a failure at step 5 can restart from step 5.

Pre-requisite checklist

Before make demo can ship, these blockers need closure:

#135 — service_agent.nu missing
#136 — OPENROUTER_API_KEYS plural
#128 — installer apt deps
#129 — service_osis.nu context population
#130 — hero_osis_ai domain registered
#131 — hero_os Makefile honors CARGO_TARGET_DIR
#140 — WASM release+brotli (done on development_mik_nu_demo)
#152 — triage classifier routes Hero questions to Tools
#153 — tools payload sanitization
#157 — Books island URL
#158 — Q&A cache alignment
hero_zero_seed formalized (sibling issue)
Rootfs sized to 8 GB by default

Until those land, make demo is building on quicksand.

Verify_demo.sh — the acceptance-test script

Must exit 0 only if:

All 22 services running (hero_proc list | grep -c running == 22).
curl .../hero_books/ui/rpc libraries.list returns 4 libraries.
Embedder namespace.list shows hero with ≥163 docs.
curl .../hero_agent/rpc agent.chat message="Call search_hero_docs with query=Hero OS" returns content containing hero_os_guide.
OSIS business.list in threefold context returns ≥3 items.
Office docs listable in geomind context.

Fail fast with diff of expected vs actual.

#160 — consolidated demo state + reproducibility path
#148 — nu-demo architecture index

Signed-off-by: mik-tf

## Why Today spinning up a Hero OS demo from scratch requires: provisioning a TF Grid VM (Terraform), base install (`hero_skills install-all` + manual deps for what the nu-shell installers miss — [#128](https://forge.ourworld.tf/lhumina_code/home/issues/128)), patching `hero_proc` action envs to add AIBROKER_API_ENDPOINT / ROUTING_MODE / etc., copying FORGEJO_TOKEN into hero_books env, re-running seeds with schema migrations, cloning doc libraries, verifying grounding. Each step is its own troubleshooting adventure. Once the prerequisites from [#160](https://forge.ourworld.tf/lhumina_code/home/issues/160)'s §Reproducibility-Path land — upstream fixes merged, `hero_zero_seed` formalized ([#XYZ](#)), rootfs sized right — the whole flow should collapse to a single command. ## Target UX On an operator's laptop, with `TFGRID_MNEMONIC` + `FORGEJO_TOKEN` in env: ``` cd lhumina_code/hero_zero/deploy/single-vm make demo ENV=heronu # ~30-45 min on fresh VM, zero prompts ``` Successful exit means: VM exists, all services running, all libraries indexed, OSIS seeded across 5 contexts, AI Assistant answers a grounded test query, dashboard accessible via TF Grid gateway. Failed exit means: one numbered step failed, with the log tailed and pointer to troubleshooting. No half-finished state. ## Implementation sketch `deploy/single-vm/Makefile` gains: ```make demo: tf-apply ssh-wait bootstrap install start seed libraries verify tf-apply: cd tf && terraform init && terraform apply -auto-approve ssh-wait: scripts/wait_for_ssh.sh $(shell terraform output -raw mycelium_ip) bootstrap: scripts/bootstrap_vm.sh $(IP) # apt deps, nu install, user setup install: ssh driver@$(IP) 'cd ~/hero/code/hero_skills/tools && nu -c "use modules/*; service_install_all"' start: ssh driver@$(IP) 'hero_proc start hero_router hero_osis ... hero_agent ...' seed: ssh driver@$(IP) 'hero_zero_seed --all-contexts --all-domains' libraries: ssh driver@$(IP) 'echo "$$LIBRARIES" > ~/hero/var/books/libraries.txt && hero_proc restart hero_books' verify: scripts/verify_demo.sh $(IP) # health checks + smoke grounding query ``` Each script is small, idempotent, and has a `--resume` mode so a failure at step 5 can restart from step 5. ## Pre-requisite checklist Before `make demo` can ship, these blockers need closure: - [ ] [#135](https://forge.ourworld.tf/lhumina_code/home/issues/135) — service_agent.nu missing - [ ] [#136](https://forge.ourworld.tf/lhumina_code/home/issues/136) — OPENROUTER_API_KEYS plural - [ ] [#128](https://forge.ourworld.tf/lhumina_code/home/issues/128) — installer apt deps - [ ] [#129](https://forge.ourworld.tf/lhumina_code/home/issues/129) — service_osis.nu context population - [ ] [#130](https://forge.ourworld.tf/lhumina_code/home/issues/130) — hero_osis_ai domain registered - [ ] [#131](https://forge.ourworld.tf/lhumina_code/home/issues/131) — hero_os Makefile honors CARGO_TARGET_DIR - [ ] [#140](https://forge.ourworld.tf/lhumina_code/home/issues/140) — WASM release+brotli (done on `development_mik_nu_demo`) - [ ] [#152](https://forge.ourworld.tf/lhumina_code/home/issues/152) — triage classifier routes Hero questions to Tools - [ ] [#153](https://forge.ourworld.tf/lhumina_code/home/issues/153) — tools payload sanitization - [ ] [#157](https://forge.ourworld.tf/lhumina_code/home/issues/157) — Books island URL - [ ] [#158](https://forge.ourworld.tf/lhumina_code/home/issues/158) — Q&A cache alignment - [ ] `hero_zero_seed` formalized (sibling issue) - [ ] Rootfs sized to 8 GB by default Until those land, `make demo` is building on quicksand. ## Verify_demo.sh — the acceptance-test script Must exit 0 only if: 1. All 22 services running (`hero_proc list | grep -c running == 22`). 2. `curl .../hero_books/ui/rpc libraries.list` returns 4 libraries. 3. Embedder `namespace.list` shows `hero` with ≥163 docs. 4. `curl .../hero_agent/rpc agent.chat message="Call search_hero_docs with query=Hero OS"` returns content containing `hero_os_guide`. 5. OSIS `business.list` in `threefold` context returns ≥3 items. 6. Office docs listable in `geomind` context. Fail fast with diff of expected vs actual. ## Related - [#160](https://forge.ourworld.tf/lhumina_code/home/issues/160) — consolidated demo state + reproducibility path - [#148](https://forge.ourworld.tf/lhumina_code/home/issues/148) — nu-demo architecture index Signed-off-by: mik-tf