Hero Services

Service orchestrator for the Hero OS ecosystem. Manages the lifecycle of all Hero services — building, installing, starting, stopping, and monitoring via JSON-RPC over Unix sockets.

For Users (Quickstart)

Pull the image and run — no build tools required.

docker pull forge.ourworld.tf/lhumina_code/hero_zero:hero
docker run -d --name hero -p 8080:6666 forge.ourworld.tf/lhumina_code/hero_zero:hero

Open http://localhost:8080 in your browser:

1. Register — create your account through the UI
2. Settings — add API keys (OpenRouter, Groq, etc.) from the Settings page
3. Done — no terminal needed after the initial pull

For Developers

1. Bootstrap

Clone the full workspace (hero_services + all 18 service repos + hero_proc):

mkdir -p ~/hero/src/lhumina_code && cd ~/hero/src/lhumina_code
curl -sSfL https://forge.ourworld.tf/lhumina_code/hero_services/raw/branch/development/bootstrap.sh | bash

Re-running is safe — existing repos are pulled, not re-cloned.

2. Build & run locally

All builds compile inside Docker — no local Rust toolchain needed. Three build targets for different situations:

cd hero_services
source ~/hero/cfg/env/env.sh

# Full build (cached — fast when cache is warm)
make dist

# Server-only build (fastest — skip WASM shell + shrimp)
make dist-quick

# Clean WASM rebuild (nuke WASM cache — use when dock/island changes aren't picked up)
make dist-clean-wasm

Target	What rebuilds	When to use	Time
make dist	Everything (cached)	Default	~10 min
make dist-quick	Server binaries only	Backend changes (routes, RPC, templates, JS)	~5 min
make dist-clean-wasm	Everything + fresh WASM	Dock layout, island metadata, registry.rs	~25 min

Then pack and run:

TAG=0.1.0-dev make pack     # bundle dist/ into Docker image
docker stop herolocal; docker rm herolocal
docker run -d --name herolocal -p 8080:6666 \
  -e OPENROUTER_API_KEY="$OPENROUTER_API_KEY" \
  -e GROQ_API_KEY="$GROQ_API_KEY" \
  -e HERO_SECRET="dev-secret-change-in-production" \
  -e FORGEJO_TOKEN="$FORGEJO_TOKEN" \
  forge.ourworld.tf/lhumina_code/hero_zero:0.1.0-dev
# Wait ~120s, then open http://localhost:8080 — login: admin / admin123

make smoke              # run smoke tests against local container
make logs               # follow container logs
make stop               # stop and remove container

3. Ship to VM (no registry needed)

# Option A: via registry
make push                                          # push to forge.ourworld.tf
cd deploy/single-vm && make update ENV=herodev     # pull + restart on VM

# Option B: direct transfer (when registry is slow/down)
docker save forge.ourworld.tf/lhumina_code/hero_zero:herodev | gzip > /tmp/hero.tar.gz
scp /tmp/hero.tar.gz root@<vm>:/tmp/
ssh root@<vm> "docker load < /tmp/hero.tar.gz && /usr/local/bin/heroos-run.sh"

Environment Variables — 3 Ways

Method	When to use
UI Settings	Easiest — set API keys from the browser, no terminal needed
Source env files	source ~/hero/cfg/env/* before running locally
CLI params	Pass directly as arguments to binaries

If nothing is set, the UI prompts you to configure on first use.

Versioning & Releases

Follows semver 2.0. Version is defined in two places that must match:

• Cargo.toml → version = "0.1.0"
• buildenv.sh → export VERSION=0.1.0

Image tags

Tag	Purpose
hero_zero:0.1.0-dev	Development builds (deployed to herodev)
hero_zero:0.1.0-rc1	Release candidate, ready for testing
hero_zero:0.1.0	Stable release
hero_zero:herodev	Alias — always points to latest dev build

Override the tag when packing: make pack TAG=0.1.0-dev

Git tags & CI

Git tags trigger CI builds and package publishing:

git tag v0.1.0-dev
git push origin v0.1.0-dev    # triggers build-linux.yaml → package registry

Tag format: v{MAJOR}.{MINOR}.{PATCH}[-PRERELEASE]

Release workflow

1. Verify version matches in Cargo.toml and buildenv.sh
2. Tag and push: git tag v0.1.0-dev && git push origin v0.1.0-dev
3. CI publishes binaries to forge.ourworld.tf package registry
4. Create release page via forge API or UI with changelog

Crates

Crate	Type	Purpose
hero_services_sdk	library	Types, RPC client, shared protocol
hero_services_server	binary	Daemon, JSON-RPC over Unix socket
hero_services	binary	CLI client using SDK
hero_services_ui	binary	Axum admin panel using SDK
hero_services_examples	examples	Example programs demonstrating SDK usage

CLI

hero_services health                    # Check server health
hero_services list                      # List all services
hero_services start|stop|restart <name> # Control a service
hero_services logs [name] [-n LINES]    # View logs
hero_services config [name]             # Show configuration
hero_services install <name>            # Install a service
hero_services install-all               # Install all services
hero_services build-status              # Show build progress

Runtime Directories

~/hero/
├── bin/                          # Service binaries
├── src/                          # Source code (for build method)
├── var/
│   ├── sockets/                  # Unix domain sockets
│   └── hero_zero/
│       └── installed/            # Install tracking
└── cfg/
    ├── env/                      # Environment variable files
    └── hero_proc/                # hero_proc service configs

Requirements (developers only)

• Rust 1.93+ (edition 2024)
• Git, Make, hero_proc
• Docker (required — all builds run in containers)

Add ~/hero/bin to your $PATH:

export PATH="$HOME/hero/bin:$PATH"

License

Apache-2.0