lhumina_code/home
22
0
Fork 0
Code Issues 16 Pull requests Projects Releases Packages Wiki Activity Actions

Hero OS Self-Documenting Platform — Built-in Book, Settings UI, AI-Guided Configuration #31

New issue
Closed
opened 2026-03-18 00:00:56 +00:00 by mik-tf · 2 comments
mik-tf commented 2026-03-18 00:00:56 +00:00
Owner
Copy link

Vision

Hero OS should be self-documenting and self-configuring. A user launches the container and can understand, configure, and operate the entire system without leaving it — through documentation (hero_books), visual configuration (Settings), or AI conversation (hero_shrimp). All three share one source of truth: a built-in book that ships with every hero_zero container.

Architecture

┌─────────────────────────────────────────────────┐
│                   hero_zero                      │
│                                                  │
│   ┌──────────┐    MCP     ┌──────────────┐      │
│   │  hero_    │◄─────────►│ hero_shrimp  │      │
│   │  books    │           │ (AI assist)  │      │
│   │          │           │              │      │
│   │ Built-in │           │ Suggested    │      │
│   │ Hero OS  │           │ questions    │      │
│   │ Guide    │           │ + context    │      │
│   └────┬─────┘           └──────┬───────┘      │
│        │                        │               │
│        │ same source of truth   │               │
│        │                        │               │
│   ┌────▼────────────────────────▼───────┐       │
│   │        Settings (⚙ gear icon)       │       │
│   │                                      │       │
│   │  Env vars tab: view/set all config  │       │
│   │  Simple mode ←→ Advanced mode       │       │
│   │  Categories: AI, Grid, DB, etc.     │       │
│   └──────────────────────────────────────┘       │
│                      │                           │
│              reads / writes                      │
│                      │                           │
│   ┌──────────────────▼───────────────────┐      │
│   │     Canonical env vars (Layer 1)     │      │
│   │  source ~/hero/cfg/env/* at launch   │      │
│   │  docker run -e KEY=val               │      │
│   └──────────────────────────────────────┘      │
└─────────────────────────────────────────────────┘

Two-Layer Configuration Model

Layer How Who When
1. Runtime env vars docker run -e GROQ_API_KEY=... or source ~/hero/cfg/env/* Sysadmin / DevOps / scripts At container launch
2. Settings UI Gear icon (⚙) → Settings → Env Vars tab End user At runtime, live in browser

Both layers coexist. Layer 1 provides defaults at boot. Layer 2 reads those values and lets users view, modify, or add new ones. If everything is set via env vars, Settings shows "all configured." If launched bare, Settings guides the user through setup.

What Already Exists

Component Status Details
Built-in book ✅ Done lhumina_code/docs_hero repo with hero_os_guide collection (7 chapters). Already seeded into hero_books at container startup alongside mycelium, geomind, ourworld books.
hero_books MCP ✅ Done MCP endpoint at /hero_books_ui/mcp (hero_books/crates/hero_books_server/src/web/mcp.rs)
hero_shrimp MCP ✅ Done MCP integration framework with mcp_servers.json
Settings page ✅ Partial Exists in hero_os (gear icon → Appearance: theme, borders, background). Needs Env Vars tab.
Auth SSO ✅ Done /sso-login auto-creates admin account with JWT, generates real credentials
Redis SSO ✅ Done /sso-login with form POST + 303 redirect

Remaining Tasks

1. Settings UI — Env Vars Tab (hero_os)

Extend the existing Settings page (Dioxus WASM) with an "Environment Variables" section.

Design:

  • Categories: Identity, AI (Primary + Optional), Infrastructure, Grid, Communication, Search, Auth
  • Each var row: Category icon | Friendly label | Status indicator | Value field | Actions
  • Sensitive values show •••••••• by default, eye icon button to reveal
  • "Test" button next to API keys — validates by pinging the provider
  • Status: ✅ set+valid, ⚠ set untested, ❌ required missing, — optional unset
  • Simple mode (default): friendly labels, grouped by category
  • Advanced mode toggle: raw var names, custom entries

Key file: hero_os/crates/hero_os_app/src/components/mobile_settings.rs

2. Settings Backend — Env Var RPC (hero_osis)

RPC methods for reading/writing env vars:

  • config.env_list → all known vars with current values (masked for sensitive), status, metadata
  • config.env_get { name } → single var value (requires auth)
  • config.env_set { name, value } → persist override to ~/hero/cfg/env/overrides.env, reload into process
  • config.env_test { name } → validate API key by test call to provider

Storage: Overrides saved to ~/hero/cfg/env/overrides.env. Entrypoint sources this at startup → persists across restarts.

Key file: hero_osis/crates/hero_osis_ui/src/

3. Wire hero_books MCP into hero_shrimp

Add hero_books as MCP source in hero_shrimp config so AI can search/read the built-in Hero OS guide.

Key files: hero_shrimp/mcp_servers.json, hero_books/crates/hero_books_server/src/web/mcp.rs

4. Suggested Questions in AI Island (hero_archipelagos)

When AI assistant has no conversation, show clickable starter prompts:

  • "What is Hero OS and what can it do?"
  • "Help me set up my AI provider keys"
  • "What services are running right now?"
  • "What can I do without any API keys?"
  • "Show me how to use voice transcription"
  • "How do I deploy to the ThreeFold Grid?"

Key files: hero_archipelagos/ — intelligence/AI chat component

5. Show SSO Credentials in Settings (hero_os + hero_auth)

Auth SSO auto-created admin credentials (client_id, client_secret) should appear in Settings under Auth category. May need a new endpoint in hero_auth to retrieve admin info.

Key files: hero_auth/src/handlers.rs, Settings UI from Task 1

Env Var Registry

Category Variable Sensitive Required Label Service
Identity GIT_NAME No No Git Author Name books, foundry
Identity GIT_EMAIL No No Git Author Email books, foundry
AI Primary OPENROUTER_API_KEY Yes Yes OpenRouter API Key shrimp, aibroker
AI Primary GROQ_API_KEY Yes Yes Groq API Key shrimp, voice
AI Optional ANTHROPIC_API_KEY Yes No Anthropic API Key aibroker
AI Optional GEMINI_API_KEY_FREE Yes No Gemini API Key aibroker
AI Optional MISTRAL_API_KEY_FREE Yes No Mistral API Key aibroker
AI Optional CEREBRAS_API_KEY_FREE Yes No Cerebras API Key aibroker
AI Optional RUNPOD_API_KEY Yes No RunPod API Key aibroker
AI Optional HF_TOKEN Yes No HuggingFace Token embedder
Infrastructure FORGEJO_TOKEN Yes Yes Forgejo Token books, foundry
Infrastructure GITHUB_TOKEN Yes No GitHub Token foundry
Infrastructure HERO_SECRET Yes Yes Hero Auth Secret auth
Grid TF_VAR_mnemonic Yes No TFGrid Mnemonic compute
Search SERPER_API_KEYS Yes No Serper Search Key shrimp
Search EXA_API_KEYS Yes No Exa Search Key shrimp
Communication LIVEKIT_URL No No LiveKit Server URL voice
Communication LIVEKIT_API_KEY Yes No LiveKit API Key voice
Communication LIVEKIT_API_SECRET Yes No LiveKit Secret voice
Auth (Auth Admin Client ID) No Auto SSO Admin Client ID auth
Auth (Auth Admin Secret) Yes Auto SSO Admin Secret auth

Workspace & Deploy Model

Repos & Branch

  • Working dir: /home/pctwo/Documents/temp/hero_work/lhumina_code/hero_services/
  • Layout: hero_work/lhumina_code/ (20 repos + docs_hero) + hero_work/geomind_code/zinit/
  • Branch: development_mik across all repos that need changes (branched from development)
  • Never merge development into development_mik — keep the feature branch clean

Two-Tag Deploy Model

Environment Docker Tag URL Purpose
Dev :herodev herodev.gent04.grid.tf Active development — iterate here
Stable :hero hero.gent04.grid.tf Verified demo — do NOT touch during dev

Set up herodev environment (create envs/herodev/ from envs/hero/, deploy VM) when ready to test.

Promotion: When herodev is verified →

docker tag forge.ourworld.tf/lhumina_code/hero_zero:herodev forge.ourworld.tf/lhumina_code/hero_zero:hero
docker push forge.ourworld.tf/lhumina_code/hero_zero:hero
cd deploy/single-vm && make update ENV=hero

Build Flow (all binaries inside Docker, never bare metal)

source ~/hero/cfg/env/env.sh
LHUMINA_DIR="/home/pctwo/Documents/temp/hero_work/lhumina_code"
BUILD_IMAGE="forge.ourworld.tf/lhumina_code/hero_zero:base"
NPROC="$(nproc)"

# Build a Rust binary (example: hero_osis_ui)
docker volume create hero-osis-target >/dev/null 2>&1
docker run --rm \
  -v "$LHUMINA_DIR:/src/lhumina_code" \
  -v hero-osis-target:/build/target \
  -v hero-cargo-registry:/usr/local/cargo/registry \
  -v hero-cargo-git:/usr/local/cargo/git \
  -w "/src/lhumina_code/hero_osis" \
  -e CARGO_TARGET_DIR=/build/target \
  -e CARGO_JOBS="$NPROC" \
  "$BUILD_IMAGE" \
  sh -c "cargo build --release -j$NPROC -p hero_osis_ui && \
    cp /build/target/release/hero_osis_ui /src/lhumina_code/hero_services/dist/bin/hero_osis_ui"

# Build WASM (if hero_os changed)
cd $LHUMINA_DIR/hero_os
dx build --package hero_os_app --web --release --features web --no-default-features
cd $LHUMINA_DIR/hero_services
cp -r ../hero_os/target/dx/hero_os_app/release/web/public/assets dist/share/hero_os/public/
cp ../hero_os/target/dx/hero_os_app/release/web/public/index.html dist/share/hero_os/public/

# Pack + deploy to dev
cd $LHUMINA_DIR/hero_services
make pack TAG=herodev && docker push forge.ourworld.tf/lhumina_code/hero_zero:herodev
cd deploy/single-vm && make update ENV=herodev

Critical Rules

  • Build first, verify compilation succeeds, THEN commit and push
  • Auth uses Askama (compile-time templates) — binary rebuild required
  • Redis uses runtime templates — sync to dist/templates/hero_redis/
  • hero_os is Dioxus WASM — needs dx build, copy to dist/share/hero_os/public/
  • wasm-bindgen-cli must be 0.2.114
  • Cargo.lock is committed
  • Mycelium IP (SSH): 506:c9a7:e600:fdef:ff0f:1c6f:3d3e:fdba
## Vision Hero OS should be self-documenting and self-configuring. A user launches the container and can understand, configure, and operate the entire system without leaving it — through documentation (hero_books), visual configuration (Settings), or AI conversation (hero_shrimp). All three share one source of truth: a built-in book that ships with every hero_zero container. --- ## Architecture ``` ┌─────────────────────────────────────────────────┐ │ hero_zero │ │ │ │ ┌──────────┐ MCP ┌──────────────┐ │ │ │ hero_ │◄─────────►│ hero_shrimp │ │ │ │ books │ │ (AI assist) │ │ │ │ │ │ │ │ │ │ Built-in │ │ Suggested │ │ │ │ Hero OS │ │ questions │ │ │ │ Guide │ │ + context │ │ │ └────┬─────┘ └──────┬───────┘ │ │ │ │ │ │ │ same source of truth │ │ │ │ │ │ │ ┌────▼────────────────────────▼───────┐ │ │ │ Settings (⚙ gear icon) │ │ │ │ │ │ │ │ Env vars tab: view/set all config │ │ │ │ Simple mode ←→ Advanced mode │ │ │ │ Categories: AI, Grid, DB, etc. │ │ │ └──────────────────────────────────────┘ │ │ │ │ │ reads / writes │ │ │ │ │ ┌──────────────────▼───────────────────┐ │ │ │ Canonical env vars (Layer 1) │ │ │ │ source ~/hero/cfg/env/* at launch │ │ │ │ docker run -e KEY=val │ │ │ └──────────────────────────────────────┘ │ └─────────────────────────────────────────────────┘ ``` --- ## Two-Layer Configuration Model | Layer | How | Who | When | |-------|-----|-----|------| | **1. Runtime env vars** | `docker run -e GROQ_API_KEY=...` or `source ~/hero/cfg/env/*` | Sysadmin / DevOps / scripts | At container launch | | **2. Settings UI** | Gear icon (⚙) → Settings → Env Vars tab | End user | At runtime, live in browser | Both layers coexist. Layer 1 provides defaults at boot. Layer 2 reads those values and lets users view, modify, or add new ones. If everything is set via env vars, Settings shows "all configured." If launched bare, Settings guides the user through setup. --- ## What Already Exists | Component | Status | Details | |-----------|--------|---------| | **Built-in book** | ✅ Done | `lhumina_code/docs_hero` repo with `hero_os_guide` collection (7 chapters). Already seeded into hero_books at container startup alongside mycelium, geomind, ourworld books. | | **hero_books MCP** | ✅ Done | MCP endpoint at `/hero_books_ui/mcp` (`hero_books/crates/hero_books_server/src/web/mcp.rs`) | | **hero_shrimp MCP** | ✅ Done | MCP integration framework with `mcp_servers.json` | | **Settings page** | ✅ Partial | Exists in hero_os (gear icon → Appearance: theme, borders, background). Needs Env Vars tab. | | **Auth SSO** | ✅ Done | `/sso-login` auto-creates admin account with JWT, generates real credentials | | **Redis SSO** | ✅ Done | `/sso-login` with form POST + 303 redirect | --- ## Remaining Tasks ### 1. Settings UI — Env Vars Tab (`hero_os`) Extend the existing Settings page (Dioxus WASM) with an "Environment Variables" section. **Design**: - Categories: Identity, AI (Primary + Optional), Infrastructure, Grid, Communication, Search, Auth - Each var row: Category icon | Friendly label | Status indicator | Value field | Actions - Sensitive values show `••••••••` by default, eye icon button to reveal - "Test" button next to API keys — validates by pinging the provider - Status: ✅ set+valid, ⚠ set untested, ❌ required missing, — optional unset - Simple mode (default): friendly labels, grouped by category - Advanced mode toggle: raw var names, custom entries **Key file**: `hero_os/crates/hero_os_app/src/components/mobile_settings.rs` ### 2. Settings Backend — Env Var RPC (`hero_osis`) RPC methods for reading/writing env vars: - `config.env_list` → all known vars with current values (masked for sensitive), status, metadata - `config.env_get { name }` → single var value (requires auth) - `config.env_set { name, value }` → persist override to `~/hero/cfg/env/overrides.env`, reload into process - `config.env_test { name }` → validate API key by test call to provider **Storage**: Overrides saved to `~/hero/cfg/env/overrides.env`. Entrypoint sources this at startup → persists across restarts. **Key file**: `hero_osis/crates/hero_osis_ui/src/` ### 3. Wire hero_books MCP into hero_shrimp Add hero_books as MCP source in hero_shrimp config so AI can search/read the built-in Hero OS guide. **Key files**: `hero_shrimp/mcp_servers.json`, `hero_books/crates/hero_books_server/src/web/mcp.rs` ### 4. Suggested Questions in AI Island (`hero_archipelagos`) When AI assistant has no conversation, show clickable starter prompts: - "What is Hero OS and what can it do?" - "Help me set up my AI provider keys" - "What services are running right now?" - "What can I do without any API keys?" - "Show me how to use voice transcription" - "How do I deploy to the ThreeFold Grid?" **Key files**: `hero_archipelagos/` — intelligence/AI chat component ### 5. Show SSO Credentials in Settings (`hero_os` + `hero_auth`) Auth SSO auto-created admin credentials (client_id, client_secret) should appear in Settings under Auth category. May need a new endpoint in hero_auth to retrieve admin info. **Key files**: `hero_auth/src/handlers.rs`, Settings UI from Task 1 --- ## Env Var Registry | Category | Variable | Sensitive | Required | Label | Service | |----------|----------|-----------|----------|-------|---------| | Identity | `GIT_NAME` | No | No | Git Author Name | books, foundry | | Identity | `GIT_EMAIL` | No | No | Git Author Email | books, foundry | | AI Primary | `OPENROUTER_API_KEY` | Yes | Yes | OpenRouter API Key | shrimp, aibroker | | AI Primary | `GROQ_API_KEY` | Yes | Yes | Groq API Key | shrimp, voice | | AI Optional | `ANTHROPIC_API_KEY` | Yes | No | Anthropic API Key | aibroker | | AI Optional | `GEMINI_API_KEY_FREE` | Yes | No | Gemini API Key | aibroker | | AI Optional | `MISTRAL_API_KEY_FREE` | Yes | No | Mistral API Key | aibroker | | AI Optional | `CEREBRAS_API_KEY_FREE` | Yes | No | Cerebras API Key | aibroker | | AI Optional | `RUNPOD_API_KEY` | Yes | No | RunPod API Key | aibroker | | AI Optional | `HF_TOKEN` | Yes | No | HuggingFace Token | embedder | | Infrastructure | `FORGEJO_TOKEN` | Yes | Yes | Forgejo Token | books, foundry | | Infrastructure | `GITHUB_TOKEN` | Yes | No | GitHub Token | foundry | | Infrastructure | `HERO_SECRET` | Yes | Yes | Hero Auth Secret | auth | | Grid | `TF_VAR_mnemonic` | Yes | No | TFGrid Mnemonic | compute | | Search | `SERPER_API_KEYS` | Yes | No | Serper Search Key | shrimp | | Search | `EXA_API_KEYS` | Yes | No | Exa Search Key | shrimp | | Communication | `LIVEKIT_URL` | No | No | LiveKit Server URL | voice | | Communication | `LIVEKIT_API_KEY` | Yes | No | LiveKit API Key | voice | | Communication | `LIVEKIT_API_SECRET` | Yes | No | LiveKit Secret | voice | | Auth | _(Auth Admin Client ID)_ | No | Auto | SSO Admin Client ID | auth | | Auth | _(Auth Admin Secret)_ | Yes | Auto | SSO Admin Secret | auth | --- ## Workspace & Deploy Model ### Repos & Branch - **Working dir**: `/home/pctwo/Documents/temp/hero_work/lhumina_code/hero_services/` - **Layout**: `hero_work/lhumina_code/` (20 repos + `docs_hero`) + `hero_work/geomind_code/zinit/` - **Branch**: `development_mik` across all repos that need changes (branched from `development`) - **Never merge `development` into `development_mik`** — keep the feature branch clean ### Two-Tag Deploy Model | Environment | Docker Tag | URL | Purpose | |-------------|-----------|-----|---------| | **Dev** | `:herodev` | `herodev.gent04.grid.tf` | Active development — iterate here | | **Stable** | `:hero` | `hero.gent04.grid.tf` | Verified demo — do NOT touch during dev | Set up `herodev` environment (create `envs/herodev/` from `envs/hero/`, deploy VM) when ready to test. **Promotion**: When herodev is verified → ```bash docker tag forge.ourworld.tf/lhumina_code/hero_zero:herodev forge.ourworld.tf/lhumina_code/hero_zero:hero docker push forge.ourworld.tf/lhumina_code/hero_zero:hero cd deploy/single-vm && make update ENV=hero ``` ### Build Flow (all binaries inside Docker, never bare metal) ```bash source ~/hero/cfg/env/env.sh LHUMINA_DIR="/home/pctwo/Documents/temp/hero_work/lhumina_code" BUILD_IMAGE="forge.ourworld.tf/lhumina_code/hero_zero:base" NPROC="$(nproc)" # Build a Rust binary (example: hero_osis_ui) docker volume create hero-osis-target >/dev/null 2>&1 docker run --rm \ -v "$LHUMINA_DIR:/src/lhumina_code" \ -v hero-osis-target:/build/target \ -v hero-cargo-registry:/usr/local/cargo/registry \ -v hero-cargo-git:/usr/local/cargo/git \ -w "/src/lhumina_code/hero_osis" \ -e CARGO_TARGET_DIR=/build/target \ -e CARGO_JOBS="$NPROC" \ "$BUILD_IMAGE" \ sh -c "cargo build --release -j$NPROC -p hero_osis_ui && \ cp /build/target/release/hero_osis_ui /src/lhumina_code/hero_services/dist/bin/hero_osis_ui" # Build WASM (if hero_os changed) cd $LHUMINA_DIR/hero_os dx build --package hero_os_app --web --release --features web --no-default-features cd $LHUMINA_DIR/hero_services cp -r ../hero_os/target/dx/hero_os_app/release/web/public/assets dist/share/hero_os/public/ cp ../hero_os/target/dx/hero_os_app/release/web/public/index.html dist/share/hero_os/public/ # Pack + deploy to dev cd $LHUMINA_DIR/hero_services make pack TAG=herodev && docker push forge.ourworld.tf/lhumina_code/hero_zero:herodev cd deploy/single-vm && make update ENV=herodev ``` ### Critical Rules - Build first, verify compilation succeeds, THEN commit and push - Auth uses Askama (compile-time templates) — binary rebuild required - Redis uses runtime templates — sync to `dist/templates/hero_redis/` - hero_os is Dioxus WASM — needs `dx build`, copy to `dist/share/hero_os/public/` - wasm-bindgen-cli must be 0.2.114 - Cargo.lock is committed - Mycelium IP (SSH): `506:c9a7:e600:fdef:ff0f:1c6f:3d3e:fdba`
mik-tf commented 2026-03-18 14:14:05 +00:00
Author
Owner
Copy link

Session 14 — Complete

All 5 deliverables implemented, deployed, and verified on herodev.gent04.grid.tf:

Done

  • Settings UI — Env Vars Tab: Appearance/Environment tabs, 21 vars across 8 categories (Identity, AI Primary/Optional, Infrastructure, Grid, Search, Communication, Auth), status indicators, mask/reveal, test, edit, simple/advanced mode
  • Settings Backend RPC: config.env_list/get/set/test via POST /config/env, overrides persisted to ~/hero/cfg/env/overrides.env, sourced on container start
  • Wire hero_books MCP → hero_shrimp: mcp_books stdio-to-HTTP bridge, 6 MCP tools exposed (libraries_list, books_list, book_pages, page_read, search, ask)
  • Suggested Questions in AI Island: 6 clickable starter prompts in empty state, sends as user message on click
  • SSO Credentials in Settings: Auto-persisted to overrides.env on SSO admin creation, displayed in Auth category with mask/reveal

Repos touched

Repo Branch Merged to development
hero_os development_mik Yes
hero_archipelagos development_mik Yes
hero_osis development_mik Yes
hero_auth development_mik Yes
hero_services development_mik Yes
hero_indexer development_mik Yes
hero_aibroker development_mik_6_1 PR #621

Known limitations

  • AI error on some queries: "Help me set up my AI provider keys" returns an error — this is a pre-existing hero_shrimp/LLM backend issue (timeout or provider error), not caused by session 14 changes. First question ("What is Hero OS?") works fine.
  • hero_indexer build: Cargo.lock updated but hero_rpc upstream has breaking changes. Working binary extracted from :hero image.

Follow-up

See new issue for wiring all Hero services to the AI assistant via MCP.

## Session 14 — Complete All 5 deliverables implemented, deployed, and verified on `herodev.gent04.grid.tf`: ### Done - [x] **Settings UI — Env Vars Tab**: Appearance/Environment tabs, 21 vars across 8 categories (Identity, AI Primary/Optional, Infrastructure, Grid, Search, Communication, Auth), status indicators, mask/reveal, test, edit, simple/advanced mode - [x] **Settings Backend RPC**: `config.env_list/get/set/test` via `POST /config/env`, overrides persisted to `~/hero/cfg/env/overrides.env`, sourced on container start - [x] **Wire hero_books MCP → hero_shrimp**: `mcp_books` stdio-to-HTTP bridge, 6 MCP tools exposed (libraries_list, books_list, book_pages, page_read, search, ask) - [x] **Suggested Questions in AI Island**: 6 clickable starter prompts in empty state, sends as user message on click - [x] **SSO Credentials in Settings**: Auto-persisted to `overrides.env` on SSO admin creation, displayed in Auth category with mask/reveal ### Repos touched | Repo | Branch | Merged to development | |------|--------|----------------------| | hero_os | `development_mik` | Yes | | hero_archipelagos | `development_mik` | Yes | | hero_osis | `development_mik` | Yes | | hero_auth | `development_mik` | Yes | | hero_services | `development_mik` | Yes | | hero_indexer | `development_mik` | Yes | | hero_aibroker | `development_mik_6_1` | PR #621 | ### Known limitations - **AI error on some queries**: "Help me set up my AI provider keys" returns an error — this is a pre-existing hero_shrimp/LLM backend issue (timeout or provider error), not caused by session 14 changes. First question ("What is Hero OS?") works fine. - **hero_indexer build**: Cargo.lock updated but hero_rpc upstream has breaking changes. Working binary extracted from `:hero` image. ### Follow-up See new issue for wiring all Hero services to the AI assistant via MCP.
mik-tf commented 2026-03-18 20:12:12 +00:00
Author
Owner
Copy link

Additional requirement: Initial user setup

Problem

Currently there's no way to set the initial Hero OS admin user/password without manually seeding the database.

Proposed solution (3 modes)

Mode 1 — Env var seeding:
Set HERO_ADMIN_USER and HERO_ADMIN_PASSWORD env vars. On first boot, hero_auth creates this user automatically. No manual setup needed for automated deployments.

Mode 2 — First-user setup (no env vars set):
If no users exist and no env vars are set, the login page shows a "Create Admin Account" form instead of the login form. First person to fill it becomes admin. After creation, the form disappears and normal login resumes.

Mode 3 — Password management in Settings:
Once logged in, users can view/change their password in Hero OS Settings UI (the Settings tab from #31's deliverables).

Implementation touches

  • hero_auth backend: check for env vars on startup, password update RPC method
  • hero_os_ui: first-user setup form on login page
  • Settings UI: password change form in user section
  • Docker entrypoint: pass through HERO_ADMIN_USER / HERO_ADMIN_PASSWORD env vars
## Additional requirement: Initial user setup ### Problem Currently there's no way to set the initial Hero OS admin user/password without manually seeding the database. ### Proposed solution (3 modes) **Mode 1 — Env var seeding:** Set `HERO_ADMIN_USER` and `HERO_ADMIN_PASSWORD` env vars. On first boot, hero_auth creates this user automatically. No manual setup needed for automated deployments. **Mode 2 — First-user setup (no env vars set):** If no users exist and no env vars are set, the login page shows a "Create Admin Account" form instead of the login form. First person to fill it becomes admin. After creation, the form disappears and normal login resumes. **Mode 3 — Password management in Settings:** Once logged in, users can view/change their password in Hero OS Settings UI (the Settings tab from #31's deliverables). ### Implementation touches - `hero_auth` backend: check for env vars on startup, password update RPC method - `hero_os_ui`: first-user setup form on login page - Settings UI: password change form in user section - Docker entrypoint: pass through `HERO_ADMIN_USER` / `HERO_ADMIN_PASSWORD` env vars
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
development
development_home27
No results found.
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
lhumina_code/home#31
No description provided.