hero_livekit

LiveKit SFU orchestrator for the Hero OS Suite. Downloads, configures, and supervises the upstream livekit-server and lk-backend binaries, and exposes a typed OpenRPC surface plus an admin + meeting UI.

HERO_SOCKET_DIR defaults to ~/hero/var/sockets when unset. All socket paths below resolve to $HERO_SOCKET_DIR/hero_livekit/<sock>.

                 ┌───────────────────────────────────────────────────┐
                 │   hero_livekit_admin  (Askama/Bootstrap dashboard)   │
                 │   - Server lifecycle tab                          │
                 │   - Rooms / Tokens / Join                         │
                 │   - /join/{room}  (livekit-client meeting page)   │
                 └───────────────┬────────────────┬──────────────────┘
                                 │ JSON-RPC       │ ws://host:7880
                                 ▼                │
            ┌────────────────────────────────┐    │
            │    hero_livekit_server         │    │
            │    (OServer, OSchema-based)    │    │
            │    rpc.sock + admin.sock          │    │
            │    spawns & supervises:        │    │
            │      livekit-server            │────┘
            │      lk-backend                │
            └────────────────────────────────┘
                    │              │
                    ▼              ▼
             ~/hero/bin/      Redis (127.0.0.1:6379)
             livekit-server
             lk-backend

Crates

Crate	Purpose
hero_livekit_server	OServer-backed supervisor. Generates types + CRUD + OpenRPC spec from schemas/livekit/livekit.oschema.
hero_livekit_admin	Axum-based admin dashboard + meeting page (embeds livekit-client).
hero_livekit_examples	Tiny CLI programs that call the generated OpenRPC client.

Quickstart

Prerequisites on the host: Redis running at 127.0.0.1:6379.

# Build and install both binaries to ~/hero/bin/
make install

# Start the supervisor (foreground — hero_proc can also manage it via --start)
~/hero/bin/hero_livekit_server &

# Start the admin UI (binds to $HERO_SOCKET_DIR/hero_livekit/ui.sock)
~/hero/bin/hero_livekit_admin &

Then open the hero_router dashboard (usually http://127.0.0.1:9988/) and click Hero LiveKit Admin, or go directly to http://127.0.0.1:9988/hero_livekit/ui/.

In the UI, run the Server tab flow once:

1. Install — downloads livekit-server + lk-backend to ~/hero/bin/
2. Configure — generates livekit.yaml + backend.env with a random API secret, persists to runtime.json
3. Start — spawns both processes

Then go to Join and click Start a new meeting to open a browser meeting page backed by livekit-client.

Documentation

• docs/architecture.md — processes, sockets, port layout
• docs/configuration.md — where state lives on disk
• docs/api.md — RPC method reference
• docs/ui.md — admin dashboard + meeting page

Service lifecycle via hero_proc

scripts/nu_service.nu is a Nushell module that registers and supervises hero_livekit_server and hero_livekit_admin under hero_proc. It provides four subcommands: install, start, stop, status.

use scripts/nu_service.nu
nu_service install         # cargo-install the binaries into ~/hero/bin
nu_service start           # register + start actions and service in hero_proc
nu_service status          # show current state
nu_service stop            # tear down the registrations

Add --root to any subcommand when hero_proc is running as root. Prerequisite: the hero_skills tools/modules/ directory must be reachable via NU_LIB_DIRS, and hero_proc must be running.

Scripting (Rhai)

crates/hero_livekit_rhai ships a hero_do_hero_livekit binary that exposes the full LiveKitService OpenRPC surface to Rhai scripts. Build and install it with:

make install-rhai

then run one of the bundled examples:

hero_do_hero_livekit crates/hero_livekit_rhai/examples/rhai/01_status.rhai
hero_do_hero_livekit crates/hero_livekit_rhai/examples/rhai/02_list_rooms.rhai

The binary auto-injects SCRIPT_DIR, SCRIPT_FILE, and ARGS into the Rhai scope. See the files under crates/hero_livekit_rhai/examples/rhai/ for patterns:

• 01_status.rhai — connect + print the current service state
• 02_list_rooms.rhai — enumerate active rooms
• 03_create_delete_room.rhai — room CRUD round-trip
• 04_issue_token.rhai — mint a JWT with grants
• 05_full_lifecycle.rhai — install → configure → start → create → token → stop

Scripts default to $HERO_SOCKET_DIR/hero_livekit/rpc.sock (falling back to ~/hero/var/sockets/hero_livekit/rpc.sock); pass an explicit path to livekit_client("/custom/path/rpc.sock") to override.

License

See individual crates.