hero_demo

Deployment scaffolding for a Hero OS demo VM on the ThreeFold Grid. Provisions the VM, bootstraps the OS, installs every Hero service from source, and brings the full ecosystem online under the nu-shell orchestration path.

This repo was renamed from hero_zero. Hero OS moved off docker-compose to a nu-shell-based orchestrator (hero_proc + hero_skills) in April 2026. The legacy docker flow is retained under docker/ and its Makefile for reference and as a fallback — it is no longer the active path.

---

What this repo does

1. Provisions a TF Grid VM via Terraform (deploy/single-vm/).
2. Bootstraps the VM: user, HOME on /data, swap, ONNX runtime, Chrome, uv, nu-shell.
3. Installs all Hero services from source via hero_skills/install/ (clones each lhumina_code/hero_* repo, builds with cargo, registers a hero_proc action + service).
4. Defines service groups via hero_proc JSON-RPC.
5. Seeds sample content (Office PDFs, hero_books libraries, OSIS schemas).
6. Verifies the deployment via smoke scripts.

Everything is reproducible end-to-end from the deployment runbook.

---

Architecture (nu-shell path)

                  ┌───────────────────────────────────────┐
                  │        hero_proc  (supervisor)        │
                  │   JSON-RPC over /var/sockets/*.sock   │
                  └──────────────┬────────────────────────┘
                                 │ spawns + monitors
                 ┌───────────────┴───────────────┐
                 ▼                               ▼
     hero_<svc>_server binary            hero_<svc>_ui binary
     (RPC backend: rpc.sock)             (HTTP: ui.sock)
                 │                               │
                 └──────────┬────────────────────┘
                            ▼
                       hero_router
                (reverse-proxies /hero_<svc>/<sock_type>)
                            │
                            ▼
                   hero_os_app (Dioxus WASM shell)
                   — loaded by browser —

• Supervisor: hero_proc — Rust daemon, nu-shell service modules, action/service two-layer model.
• Installers: hero_skills/install/*.nu — clone → build → register.
• Routing: hero_router — reverse-proxies the browser-facing paths /hero_<name>/rpc and /hero_<name>/ui to the matching per-service socket.
• Browser shell: hero_os_app — Dioxus 0.7 WASM, with per-archipelago native islands (or iframe fallback for _ui admin panels).

---

Quickstart — deploy a new demo VM

Full procedure in docs/ops/DEPLOYMENT_NU_HERO_OS.md. Summary of the happy path:

# 1. Workstation env
source ~/hero/cfg/env/env.sh   # FORGEJO_TOKEN, OPENROUTER_API_KEY, ...

# 2. Pick an env overlay under deploy/single-vm/envs/ and edit its tfvars
cd deploy/single-vm
cp envs/herodemo/tf/credentials.auto.tfvars.example \
   envs/<NAME>/tf/credentials.auto.tfvars
# Edit node_id, gateway_node, cpu, memory, disk_size, rootfs_size, publicip

# 3. Apply Terraform
terraform -chdir=envs/<NAME>/tf init
terraform -chdir=envs/<NAME>/tf apply -auto-approve

# 4. Bootstrap the VM (see runbook §2)
ssh root@<ipv4>
# ...create driver user, /data symlink, swap, apt deps, ONNX, Chrome, uv, nu

# 5. Install all services (runbook §4)
su - driver -c '
  source ~/hero/cfg/init.sh
  cd ~/code/hero_skills/install
  nu -c "use service_install_all.nu *; service_install_all"
'
# ~45 min

# 6. Set services + patch action envs + restore data (runbook §4.3–§5)
# 7. Build WASM shell + apply theme overlay (runbook §6)
# 8. Verify (runbook §8) + snapshot (runbook §9)

---

Recommended VM shape

Learned the hard way from heronu OOM and TF Grid default-rootfs pain (home#161):

Resource	Value	Why
CPU	16	Headroom for concurrent LLM + embedder + WASM build
Memory	32 GB	heronu OOM-killed hero_embedderd at 7.6 GB
Disk	200 GB	Library corpora + cargo cache + backups
rootfs	16 GB	2 GB default is the source of most build pain
Public IPv4	yes	Mycelium route propagation on fresh nodes is slow
Swap	8 GB	On /data (btrfs needs chattr +C before dd)

---

Repository layout

hero_demo/
├── README.md                          ← this file
├── deploy/single-vm/
│   ├── tf/                            ← Terraform modules (grid_deployment, gateway, network)
│   ├── envs/<NAME>/                   ← per-demo overlay (tfvars, app.env)
│   ├── scripts/                       ← setup.sh, update.sh
│   └── Makefile                       ← convenience wrappers (update, info, test)
├── services/*.toml                    ← canonical service TOML references
├── profiles/*.toml                    ← profile bundles (user, system, all)
├── docs/
│   ├── ops/
│   │   ├── DEPLOYMENT_NU_HERO_OS.md   ← the runbook (start here)
│   │   ├── deploy.md                  ← legacy docker deploy flow
│   │   ├── runbook.md                 ← legacy ops runbook
│   │   └── secrets.md
│   ├── service.md, profile.md, TOML_FORMAT_REFERENCE.md
│   └── dev/
├── docker/                            ← [LEGACY] docker-compose build path
├── Dockerfile.pack                    ← [LEGACY] used by docker path only
└── Makefile                           ← [LEGACY] docker-path targets (make dist/pack/push)

What is actively used by nu-shell deploys:

• deploy/single-vm/** — all of it
• services/*.toml — consumed by hero_skills installers as references
• profiles/*.toml — service-group profiles
• docs/ops/DEPLOYMENT_NU_HERO_OS.md — the runbook

What is NOT used by nu-shell deploys (retained for reference):

• docker/, Dockerfile.pack, top-level Makefile — docker-era container build and packaging. Kept for historical context and as a fallback build path. Do not rely on for new work.
• crates/ — the old hero_services_* CLI/SDK. Superseded by hero_proc.
• bootstrap.sh — old developer bootstrap. Superseded by the runbook.

---

Legacy docker path (reference only)

Kept so the docker build is not lost, in case it is needed for CI, local smoke testing, or a future pivot. Not the way production/demo runs today.

# Full workspace bootstrap (legacy)
curl -sSfL https://forge.ourworld.tf/lhumina_code/hero_demo/raw/branch/development/bootstrap.sh | bash

# Build + run a local container (legacy)
source ~/hero/cfg/env/env.sh
make dist            # full build (~10 min)
TAG=0.1.0-dev make pack
docker run -d --name herolocal -p 8080:6666 \
  -e OPENROUTER_API_KEY="$OPENROUTER_API_KEY" \
  -e GROQ_API_KEY="$GROQ_API_KEY" \
  forge.ourworld.tf/lhumina_code/hero_demo:0.1.0-dev

Full docker-path docs in docs/ops/deploy.md.

---

Deployment targets

Each env overlay under deploy/single-vm/envs/ is an independent VM:

Env	Purpose	Gateway
herodemo	Active demo VM (nu-shell)	herodemo.gent01.grid.tf
heronu	[retired 2026-04-24]	—
heroprod	Future prod slot	heroprod.gent01.grid.tf
hero	Official public demo	hero.gent04.grid.tf — do not touch
herodev*	Legacy docker dev VMs	[docker path, kept for CI]
herozero*	Legacy single-VM	[superseded]

New demo deploys go through envs/herodemo/ (or a new env cloned from it).

---

Related

• docs_hero — user-facing docs (architecture, services, getting started)
• hero_skills — the installers that this repo drives
• hero_proc — the supervisor (lives under hero_os)
• home — the issue tracker: https://forge.ourworld.tf/lhumina_code/home/issues

License

Apache-2.0