[Feature]: add --profile flag to hermes gateway start/restart for profile-specific gateway instances

[tanghzuk188]

Problem or Use Case

The global -p / --profile flag works for some gateway commands (hermes -p stock gateway status) but hermes -p stock gateway start fails with "service not installed" unless the profile has been separately registered as a systemd service.

The only way to run the gateway under a non-default profile today is:

1. Change the active default profile: hermes profile use stock
2. Restart the gateway: hermes gateway restart

This is inconvenient when a user wants different profiles for different use cases (e.g., stock research on WeChat vs coding via CLI), because changing the default profile affects all future CLI sessions too.

Also, restarting the gateway while keeping a running profile (e.g., the WeChat gateway on stock) should be possible without switching the user's default profile for CLI sessions.

Proposed Solution

Add a --profile <name> argument to the hermes gateway subcommand group:

hermes gateway start --profile stock
hermes gateway restart --profile dev
hermes gateway status --profile stock

When --profile is supplied, the gateway process should:

1. Set HERMES_HOME to ~/.hermes/profiles/<name>/ at startup
2. Load config, .env, skills, and memory from that profile
3. Register as a separate service instance (if using systemd) so multiple gateway instances can coexist

The implementation can reuse the existing _apply_profile_override() mechanism in hermes_cli/main.py which already resolves --profile and sets HERMES_HOME before module imports — the main work would be threading it through to the gateway subcommand parser.

For systemd users, each profile's gateway should get a distinct service name (e.g., hermes-gateway@stock, hermes-gateway@dev) to allow independent lifecycle management.

Alternatives Considered

1. Use the global -p flag: Already exists but incomplete — hermes -p stock gateway start fails with "service not installed" and there's no clean way to manage per-profile gateway lifecycle.

2. Manually switch default profile: hermes profile use stock && hermes gateway restart works but is disruptive — it changes the default for ALL future CLI sessions, not just the gateway.

3. Run separate Hermes installations: Install Hermes in different locations for each profile. Works but is heavy, duplicates the entire codebase, and loses the unified state management that profiles provide.

4. Use wrapper scripts: Create shell aliases that set HERMES_HOME before calling gateway commands. Fragile and doesn't integrate with the service management system.

The proposed --profile flag is the most native, discoverable, and maintainable solution that builds on Hermes' existing profile infrastructure.

Feature Type

Gateway / messaging improvement

Scope

None

Contribution

• I'd like to implement this myself and submit a PR

Debug Report (optional)

[AIalliAI]

Good news: per-profile gateway instances are already implemented — including everything in the proposed solution. The piece that's missing is discoverability, and I think I found the exact trap that led you here.

The supported workflow today:

hermes -p stock gateway install   # one-time per profile: registers a separate service
hermes -p stock gateway start
hermes -p stock gateway status
hermes -p stock gateway restart

This does exactly what the issue proposes:

1. Separate service per profile — get_service_name() (gateway.py#L1462) derives hermes-gateway-stock for HERMES_HOME=~/.hermes/profiles/stock (your hermes-gateway@stock idea, just with - instead of @). The launchd label/plist on macOS are suffixed the same way.
2. Profile-pinned process — the generated systemd unit sets Environment="HERMES_HOME=~/.hermes/profiles/stock" and ExecStart=... --profile stock gateway run, so the gateway loads that profile's config/.env/skills/memory regardless of your default profile.
3. Independent lifecycle — multiple profile gateways run concurrently (see docs/kanban/multi-gateway.md); your default CLI profile is never touched.

Why it looked broken: hermes -p stock gateway start before the one-time install fails with:

✗ Gateway service is not installed
  Run: hermes gateway install

The hint drops the profile flag — following it installs the default profile's service, hermes -p stock gateway start still fails, and it reasonably looks like profiles aren't supported by the gateway lifecycle at all. (On macOS this doesn't reproduce because launchd_start self-heals a missing plist — it's specific to the systemd path.)

I've opened #44459 to fix the hint so it preserves the profile flag (Run: hermes --profile stock gateway install).

That leaves only the literal flag-position sugar from the proposal (hermes gateway start --profile stock with the flag after the subcommand) unimplemented — the global form hermes -p stock gateway start is the supported spelling, since _apply_profile_override() must set HERMES_HOME before module imports, exactly as you noted. A subcommand-level alias would need to be parsed pre-import too, so I'd leave that design call to the maintainers — but functionally everything requested works today.

[teknium1]

Implemented on current main; this is an automated hermes-sweeper review.

• hermes_cli/main.py:407-435 accepts --profile / -p anywhere in normal Hermes argv, including after gateway subcommands, and hermes_cli/main.py:500-525 resolves it into HERMES_HOME before imports.
• hermes_cli/gateway.py:1778-1788 derives independent hermes-gateway-<profile> service names, while generated service definitions include both --profile <name> and the profile HERMES_HOME.
• The supported lifecycle is documented in website/docs/user-guide/multi-profile-gateways.md:252-275; profile wrapper commands and hermes -p <name> gateway <action> are equivalent.
• The remaining unscoped “service not installed” install hint is separately tracked by open PR fix(gateway): preserve profile flag in 'service not installed' hint #44459.