Summary

The built-in Web Dashboard currently behaves as a single-profile UI bound to one HERMES_HOME per process. This makes profile switching awkward compared with CLI usage and creates friction for users running multiple profiles.

This issue proposes a design direction for safe multi-profile switching in Web Dashboard, including root-cause analysis, implementation options, and recommended best practices.

Current behavior (observed)

• Dashboard process is profile-bound at startup (--profile/-p -> HERMES_HOME set before imports).
• Backend APIs expose current profile paths (hermes_home, config_path, env_path) but do not expose profile list/switch endpoints.
• Frontend routes/pages do not include a profile selector.

As a result, users typically run one dashboard per profile on different ports.

Why this happens (root causes)

1. Process-level profile context

   • Profile is resolved early and materialized as HERMES_HOME, then reused across config/session/log/gateway helpers.
   • This is robust for isolation, but not designed for runtime context switching.

2. No profile-scoped API contract in Web layer

   • Existing dashboard APIs are implicitly “active profile only”.
   • No standardized request field/header for profile context.

3. Stateful resources are loaded from active home

   • Config/env/files/session DB/log paths/gateway status are all path-derived from current HERMES_HOME.
   • Runtime switching in a single process risks stale handles/caches and mixed state if not carefully re-scoped.

4. Safety concerns from prior multi-instance issues

   • Historical reports around cross-instance/session contamination and profile reauth loops indicate this area needs strict isolation guarantees.

Recommended design (best path)

Phase 1 (short-term, low risk)

Keep backend isolation model (one process == one profile), but improve UX:

• Add docs-first guidance and helper command for launching multi-profile dashboards:
  • hermes -p <profile> dashboard --port <port>
• Provide a small “profile launcher” view/script that opens known profile dashboards in tabs.

Phase 2 (product feature)

Add multi-profile awareness to dashboard with strict boundary control:

Option A (recommended): Supervisor + per-profile backend workers

• Dashboard UI talks to a lightweight supervisor API.
• Supervisor enumerates profiles and proxies requests to profile-specific workers.
• Each worker keeps strict HERMES_HOME isolation (same as today).

Pros: safest isolation model, minimal risk of cross-profile leakage, easy mental model.
Cons: more moving parts (worker lifecycle/proxying).

Option B: Single backend process with request-scoped profile context

• Introduce profile identifier in every API request.
• All path/config/session/log resolvers become request-scoped.

Pros: fewer processes.
Cons: high refactor risk; easier to introduce contamination bugs.

I recommend Option A.

Implementation principles

1. Isolation first

   • No shared mutable caches across profiles.
   • Session DB/log readers/config writers must be profile-bound.

2. Explicit profile context everywhere

   • API contract should always know target profile.
   • UI should visibly indicate active profile at all times.

3. Safe switching semantics

   • Switching profile should reset page-local state (search/filter/open session details) unless intentionally preserved per-profile.

4. Per-profile auth/session safety

   • If dashboard auth/session token is introduced/expanded, ensure token scope includes profile.

5. Observability

   • Include profile name in dashboard API logs/metrics for debugging.

Proposed UX

• Header profile dropdown with:
  • current profile badge
  • profile status (gateway running/stopped)
  • quick actions: open profile dashboard, restart profile gateway
• “Remember last profile” local setting
• warning modal before destructive actions if profile changed recently

Backward compatibility

• Existing hermes dashboard behavior should remain valid for default profile.
• Existing API paths can remain, while adding profile-aware variants or proxy routes.

Interim best practices (today)

Until native switching lands:

1. Run separate dashboards per profile (-p + different ports).
2. Keep one browser tab per profile with clear naming/bookmarks.
3. Avoid sharing the same dashboard tab for rapid profile task hopping.
4. Use profile-specific gateway/API ports for integrations (e.g., Open WebUI multi-connection setup).

Acceptance criteria

• User can switch profiles in one Web Dashboard entrypoint.
• All data shown (config/sessions/logs/env/cron/skills/status) is strictly profile-correct.
• No cross-profile session/memory/log leakage in tests.
• Existing single-profile workflows keep working unchanged.