hero_bundle

A single binary that runs the core Hero services in-process as independent tokio tasks. From the outside, every bundled service binds the same Unix sockets and exposes the same OpenRPC, REST, and admin/UI interfaces it would when launched standalone — clients cannot tell the difference.

New here? Start with concepts for what the bundle is and how it differs from running each service as its own OS process.

How It Works

hero_bundle links each service crate as a Rust library and spawns it on the shared tokio runtime. There is no IPC between bundled services for lifecycle purposes, no fork/exec, and no external supervisor. A single CancellationToken plus a SIGINT/SIGTERM watcher drives shutdown; each task is then joined with a 30-second timeout.

Bundled services and their library crates:

Service	Crate	Role
mycelium	mycelium_daemon	Local message bus (TUN forced off, not a node)
hero_db	hero_db_server	Encrypted Redis-compatible storage backend
hero_indexer	hero_indexer_server	Document/index service
hero_code	hero_code_server	Script and editor service
hero_proc	hero_proc_server	Process supervisor for external processes
hero_router	hero_router	TCP entry point and per-service router

hero_proc is bundled as one of the services and continues to supervise external processes via fork/exec exactly as it does standalone. It does not supervise its bundled siblings — the bundle owns those tasks directly.

Requirements

• Rust 1.95+
• Sibling repos checked out next to this one (../hero_proc, ../hero_db, ../hero_code, ../hero_indexer, ../hero_router, ../mycelium_network). All service crates are path dependencies.

Quick Start

cargo build --release --workspace
./target/release/hero_bundle

With a custom config:

./target/release/hero_bundle --config ~/hero/cfg/hero_bundle.toml

The default config path is ~/hero/cfg/hero_bundle.toml. If that file does not exist, the bundle starts with built-in defaults.

Service Architecture

Binary	Type	Description
hero_bundle	daemon	Single process hosting all bundled services in-proc

Each bundled service still binds its own Unix sockets under $HERO_SOCKET_DIR/<service>/... (default ~/hero/var/sockets) and writes to its own log target under ~/hero/var/logs/<service>/....

Configuration

See docs/configuration.md for the full TOML schema and the environment variables the bundle honours.

Test Mode

Run a second instance alongside a production one without any path or port conflicts:

hero_bundle --test

Everything is rooted under ~/hero_test/ instead of ~/hero/:

Resource	Standard	--test
Sockets	~/hero/var/sockets/	~/hero_test/var/sockets/
Data / DB	~/hero/var/	~/hero_test/var/
Mycelium state	~/hero/var/mycelium/	~/hero_test/var/mycelium/
Router port	9988	19988

All values are still individually overridable by the config file or HERO_SOCKET_DIR env var — --test only fills in defaults for anything not already set. The startup banner shows [TEST MODE] and prints the active paths.

Troubleshooting

A service refuses to bind its socket — another process (likely the standalone version of that service) already owns the path. Stop it before launching the bundle.

Slow startup — services start in order with a 200 ms stagger. Check the banner and per-service tracing output to see where startup is blocking.

Shutdown timed out after 30s — one of the bundled tasks did not honour the cancellation token within the join window. The bundle still exits; check the offending service's logs.

Documentation

• Architecture
• Concepts
• CLI Reference
• Setup
• Configuration
• Testing

License

Apache-2.0