hero_team

Configuration management service for Kimi Code within Hero OS. Manages agent roles and skill allocation — generating the config files that Kimi reads at startup.

hero_team does not run, spawn, or monitor Kimi processes. It owns the config. hero_proc owns the lifecycle.

What it does

Kimi Code reads ~/.kimi/config.toml on startup. Without tooling, managing multiple named configurations (one per role or project) is manual. hero_team provides:

• Role management — named configuration presets (backend, frontend, researcher, etc.) each with its own model, provider, context limits, and thinking settings. Generates one config.toml per role under ~/.kimi/roles/<role>/.
• Skill management — per-role whitelists against the Hero skills registry (~/hero/code/hero_skills/skills/). Syncs the selected skills into ~/.kimi/roles/<role>/skills/ and updates extra_skill_dirs in the generated config.
• MCP wiring — generates ~/.kimi/roles/<role>/mcp.json from the live hero_router service list so each role's Kimi instance has the right tools available.

Architecture

hero_router
 │ (prefix /kimi)
 ▼
hero_team_server ← OpenRPC daemon (UDS: $PATH_SOCKET/hero_team/rpc.sock)
 │
 └── hero_team_admin ← Axum admin dashboard (UDS: admin.sock)
 │
 ├── Roles tab — create/edit/delete roles; model + provider config
 ├── Skills tab — enable/disable Hero skills per role; sync status
 ├── Config tab — live view of generated config.toml per role
 └── API docs tab — live OpenRPC spec

Crate structure

crates/
├── hero_team/ Core types + OSchema codegen (lib)
├── hero_team_server/ OpenRPC daemon + UDS listener (bin)
├── hero_team_sdk/ Typed async client for other services (lib)
└── hero_team_admin/ Axum admin dashboard — Askama templates (bin)

Key concepts

Role

A role is a named Kimi configuration preset stored in hero_team's database and rendered to disk when saved or synced:

# ~/.kimi/roles/backend/config.toml (generated — do not edit by hand)
default_model = "kimi-code/kimi-for-coding"
default_thinking = true
default_yolo = true
merge_all_available_skills = false # false per-role; hero_team controls skill dirs explicitly
extra_skill_dirs = ["/Users/<user>/.kimi/roles/backend/skills"]

The global ~/.kimi/config.toml (the "master" config Kimi reads when no role override is set) has merge_all_available_skills = true. Per-role configs set it to false and point extra_skill_dirs at the role's synced skill directory so only whitelisted skills are loaded.

Roles are stored in hero_team's OSIS-backed store. The admin dashboard is the write surface; the generated files under ~/.kimi/roles/ are outputs.

Skill allocation

Hero skills live in ~/hero/code/hero_skills/skills/. Each role carries a whitelist of skill names. On sync:

1. Load the full Hero skills registry (same loader as lab skills sync).
2. Filter to the whitelisted skills for the role.
3. Write selected skill Markdown to ~/.kimi/roles/<role>/skills/.
4. Set extra_skill_dirs in the generated config.toml to that path.
5. Record the md5 hash per skill so staleness is detectable without a full resync.

Config generation

KimiConfig (the strongly-typed schema from lab's kimi_config.rs) is the source model. For each role, hero_team_server renders:

~/.kimi/roles/<role>/
 config.toml ← generated from role settings + provider keys from hero_proc secrets
 mcp.json ← generated from hero_router service discovery
 skills/ ← synced from the Hero skills registry

The three providers that must be configured are:

Provider key	Type	API endpoint
managed:kimi-code	kimi	https://api.kimi.com/coding/v1
managed:groq	openai_legacy	https://api.groq.com/openai/v1
managed:sambanova	openai_legacy	https://api.sambanova.ai/v1

Two services are also required in every generated config — moonshot_search and moonshot_fetch — both pointing at https://api.kimi.com/coding/v1/{search,fetch} and using the same Kimi API key as the managed:kimi-code provider.

The generated configs are read-only artifacts. All edits happen through the hero_team admin dashboard or OpenRPC API.

OpenRPC methods

Method	Description
role_list	All defined roles with their current config
role_upsert(role)	Create or update a role; regenerates config files
role_delete(name)	Remove a role and its generated config tree
skill_list(role)	Enabled skills for a role
skill_sync(role?)	Resync Hero skills into role config(s)
config_render(role)	Return the generated config.toml for a role as a string
config_write(role)	Write the generated config to ~/.kimi/roles/<role>/

Admin dashboard tabs

Roles

• List all roles with model, provider, and skill count.
• Create / edit role: model picker, provider selector, skill whitelist, context limit, thinking toggle.
• "Render Config" — show the TOML that would be generated without writing it.
• "Write Config" — generate and write config.toml + mcp.json for the role.

Skills

• Full Hero skills registry: name, description, tags, last-synced hash.
• Per-role checkboxes for enabling/disabling skills.
• Stale indicator per skill (md5 mismatch since last write).
• "Sync" button — regenerates skill directories for selected roles.

Config

• Read-only view of the generated config.toml for each role.
• Diff between what is on disk and what would be generated now.

API docs

• Live OpenRPC spec rendered via the shared hero_ui_api_docs pattern.

Secrets

Required in hero_proc (context core):

Key	Purpose
GROQ_API_KEY	Groq provider (managed:groq)
SAMBANOVA_API_KEY	SambaNova provider (managed:sambanova)
KIMI_API_KEY	Kimi Code + moonshot_search/fetch (managed:kimi-code)

The managed:kimi-code provider uses api_key in the generated config (not OAuth, despite what lab's kimi_config.rs documents — the real config uses a plain bearer key). moonshot_search and moonshot_fetch services share the same key.

Set with:

lab secrets set GROQ_API_KEY gsk_... --context core
lab secrets set SAMBANOVA_API_KEY ... --context core
lab secrets set KIMI_API_KEY sk-kimi-... --context core

Install and start

lab service hero_team --install
lab service hero_team --start
lab service hero_team --status

Dependencies

• herolib_ai — provider config types, model registry
• hero_proc_sdk — secrets access
• hero_admin_lib — shared admin dashboard assets and middleware
• hero_rpc_derive / hero_rpc_openrpc — OpenRPC client/server
• hero_osis_sdk — role and skill state persistence
• lab (internal) — KimiConfig, skill loader, ProviderKeys

Socket layout

$PATH_SOCKET/hero_team/
 rpc.sock ← OpenRPC server (JSON-RPC 2.0)
 admin.sock ← HTTP admin dashboard

Registered with hero_router under prefix /kimi.

Status

Not yet implemented. This README is the specification. See PURPOSE.md for the component breakdown.

Implementation order:

1. OSchema domain — roles and skills config entities
2. hero_team — core types + codegen (lib)
3. hero_team_sdk — typed async client
4. hero_team_server — OpenRPC daemon, config generation, skill sync
5. hero_team_admin — Axum dashboard, Askama templates, all tabs