docs(desktop): explain multi-source session scoping

This commit is contained in:
David Dudok de Wit
2026-08-17 11:05:23 +02:00
committed by Teknium
parent fa73b45d34
commit 4ea516b8d4
3 changed files with 60 additions and 24 deletions
+3 -1
View File
@@ -182,7 +182,9 @@ Changing profiles or connection modes is a soft workspace switch, not another
cold boot. The shell and current management overlay remain mounted while
gateway-bound nanostores are wiped, query-backed data is invalidated, and the
new connection repopulates skeletons. This prevents rows or transcripts from
the previous gateway bleeding into the next one.
the previous gateway bleeding into the next one. Switching changes only the
foreground view and request route: it does not cancel turns or stop a backend,
and retained background sockets continue receiving events from running jobs.
### Verification
+2
View File
@@ -302,9 +302,11 @@ Gateway connections are **machine-level**: the Gateways page manages which gatew
Further down the same **Settings → Gateways** page, the connections registry manages a named list of every agent source the app knows about — the local runtime, any number of remote gateways (LAN, Tailscale, internet), Hermes Cloud instances, and SSH hosts — all persisted together in one place. You can jump there from the plug button at the right end of the sidebar profile rail (**Connect another Hermes gateway…**) or via **⌘K → Gateways**. The full guide, including the union agent roster, `@name-device` handles, fleet-wide updates, and the plugin SDK surface, is at [Connecting Desktop to Many Hermes Instances](./multi-connection-desktop.md).
- **Every connection needs a unique name** (a device name such as "Homelab" or "Work laptop"). When the same profile name exists on several registered sources, surfaces disambiguate it as `@profile-device` (e.g. `@research-homelab`).
- **Switch sources from the Sessions sidebar.** The named selector appears when more than one source is registered; the adjacent profile rail then shows only that source's agents and remembers the last profile used there.
- **Add / edit / remove / test** connections from the panel. The **Add** flow offers all four kinds — **Local**, **Hermes Cloud**, **Remote gateway**, and **SSH** (the Local button is disabled while the app-managed local entry exists, and a hint points cloud adds at the sign-in/discovery flow above). The local entry is managed by the app and cannot be removed. **Test** probes the connection's own HTTP and WebSocket legs directly.
- **Duplicates are rejected at save time**: only one **local** entry ever; remote and cloud entries are deduplicated on the normalized URL (trimmed, trailing slashes stripped, lowercased — across both kinds); SSH entries on the normalized `user@host:port` plus remote profile.
- Existing settings are **imported automatically** the first time you run a build with the registry: your current global connection and any legacy per-profile overrides become named entries. The legacy settings file is left untouched, so older builds keep working.
- Cloud entries come from the Hermes Cloud sign-in/discovery flow above, not from a hand-typed URL.
- Tokens are stored encrypted with the OS keyring (with an explicit plain-text opt-in on keyring-less Linux).
Side-by-side routing is live: each registered source dials its own backends and sockets on demand (keyed per connection + profile), the plugin SDK exposes the union agent roster (`host.agents()` / `host.ensureAgent()`), and **Update all instances** on the Gateways page dispatches `hermes update` to every eligible source at once — Hermes Cloud entries are skipped (the platform updates them), and each instance reports its own result.
@@ -55,10 +55,10 @@ Rules worth knowing:
- The **local** entry is managed by the app (it wears a **This device** pill)
and cannot be removed. Removing any other connection tears down its live
backends and tunnels; the instance itself is untouched.
- One connection is always the **Primary** (pill on its row): it owns the
app-managed window backend — boot overlay and install/update machinery.
**Make primary** on any row retargets that; removing the primary falls back
to the local entry.
- One connection is always the **Primary** (pill on its row): it is the
registry fallback for multi-source calls that do not name a source.
**Make primary** does not switch the current Sessions workspace; removing
the primary falls back to the local entry.
- **Test** probes the connection's own HTTP *and* WebSocket legs, so a pass
(the *"Reachable"* toast) means chat will actually work — not just that the
host pinged.
@@ -72,9 +72,10 @@ Rules worth knowing:
the top of the Gateways page — the **Hermes Cloud** kind in the add-connection
editor points you there.
As the pane's own caption notes: *"Chats and the agent roster follow the
source you pick; the app-managed window backend is still chosen by the
connection-mode controls above."*
Switch sources from the **Sessions** sidebar. Profiles, chats, messaging, and
cron stay scoped to that source; the app-managed window backend is still chosen
by the connection-mode controls above. **Primary** is the registry fallback and
does not switch the current workspace.
## Adding a connection, step by step
@@ -154,27 +155,58 @@ keep streaming while you look at another source.
### Switching and scoping
Switching agents is the same gesture as switching profiles:
The sidebar foot follows one hierarchy: **source → profile → sessions**.
Sources are machines or hosted backends; profiles are isolated Hermes agents
that live on one source.
- **The profile rail** at the sidebar foot switches the active profile; the
home pill returns to the default profile and the layers pill shows the
**All profiles** view. **Cmd/Ctrl+1–9** switch profiles from the keyboard.
- The sidebar's session list, cron jobs, and messaging status are **scoped to
the active profile** — and, for agents on another source, to that source's
machine. Sessions you see under `@research-homelab` live on the Homelab;
its cron jobs run there; its messaging channels are the ones its gateway
hosts. The **All profiles** view merges every profile's sessions into one
list, with per-profile tags.
- With one registered source, no source control is added. Local-only Desktop
keeps the same profile rail and keyboard flow as before.
- With up to five sources, the sidebar shows direct source glyphs: a home for
**This device**, then stable initials for named sources. Larger registries
collapse into one source menu so profiles and actions are not crowded out.
- Selecting a source restores the last profile used there. The profile rail
then shows only that source's profiles; the home pill returns to its default
profile and the layers pill shows **All profiles on this source**.
**Cmd/Ctrl+1–9** continue to switch profiles within the active source.
- **This device** remains a first-class source even when a remote connection is
Primary. It can keep local sessions available during a remote outage, but the
app does not call it "offline mode": the selected model or tools may still
require internet access.
- The session list, messaging channels, cron jobs, settings, files, and memory
are all scoped to the active `(source, profile)`. Switching from a Telegram
source to a Signal source cannot leave the previous source's channel groups
or sessions in the sidebar.
- Merely displaying the switcher reads Electron's local connection registry.
Remote gateways are opened only when selected; there is no periodic fleet
polling.
- Hovering an agent pre-warms its backend so the switch doesn't pay a cold
boot.
- The **Capabilities** page (Skills / Tools / MCP) grows a matching scope: its
- The **Capabilities** page (Skills / Tools / MCP) has a matching scope: its
**Configuring** selector lists every `(profile, device)` agent from the
union roster, and picking one reads and writes **that machine's** skills,
toolsets, and MCP servers — no gateway switch. Hub installs, env keys, and
MCP setup all land on the selected agent's backend. (One caveat: the MCP
tab's *hot-reload into a live session* button only appears for agents on
the gateway your window is connected to; edits on other machines apply on
their next session.)
toolsets, and MCP servers without switching the Sessions workspace. Hub
installs, env keys, and MCP setup all land on the selected agent's backend.
The MCP tab's *hot-reload into a live session* button appears only for agents
on the gateway the window is connected to; edits on other machines apply on
their next session.
Add, test, rename, or remove sources in **Settings → Connections**. The plug
button beside the profile actions is a shortcut to that single management
home, not a second add flow.
### Sessions and Bot Mode
Sessions intentionally show one active source at a time: this keeps files,
tools, channels, cron, and session history in one understandable execution
context. Bot Mode serves a different job and may present the union roster,
grouped by source, so a user can open one agent on a NAS and another on a VPS
from one surface. Opening a bot still activates its exact `(source, profile)`
route.
Direct bot mentions and delegation remain source-local by default. Crossing a
backend boundary changes filesystem, credentials, tools, and trust context, so
cross-source execution should be an explicit bridge rather than an accidental
side effect of sharing one Desktop window.
## Updating every instance at once