Skip to content

The agent that grows with you

fix(terminal): key a named profile's unnamed chats by its name too

kshitijk4poore10765f7c309
diff --git a/gateway/platforms/docker_media_paths.py b/gateway/platforms/docker_media_paths.py
index cb2f523ef4b..0d6416880f4 100644
--- a/gateway/platforms/docker_media_paths.py
+++ b/gateway/platforms/docker_media_paths.py
@@ -41,23 +41,19 @@ def _docker_sandbox_dir_candidates(session_key: str = "", workspace_key: str = "
tenv, _persistent = _scope()
try:
from tools.environments.path_utils import sanitize_task_id_for_path
+ from tools.terminal_tool_config import home_profile_name, profile_container_key
+ base = profile_container_key(home_profile_name())
except Exception: # health: allow BLE001 -- path translation fails closed; a miss is a 404, not a 500
return ["default"]
- try:
- from hermes_cli.profiles import get_active_profile_name
- profile = get_active_profile_name() or "default"
- except Exception: # health: allow BLE001 -- path translation fails closed; a miss is a 404, not a 500
- profile = "default"
candidates: list[str] = []
# Explicit trusted-profiles opt-in: one shared container identity. That
# key is not a per-workspace container, so a :ws: digest does not apply.
if shared := tenv("TERMINAL_DOCKER_SHARED_CONTAINER_KEY", "").strip():
candidates.append(sanitize_task_id_for_path(f"shared:{shared}"))
elif _WORKSPACE_KEY_RE.fullmatch(workspace_key or "") and _cwd_mount_enabled():
- base = "default" if profile == "default" else f"profile:{profile}"
candidates.append(sanitize_task_id_for_path(f"{base}:ws:{workspace_key}"))
- if profile != "default":
- candidates.append(sanitize_task_id_for_path(f"profile:{profile}"))
+ if base != "default":
+ candidates.append(sanitize_task_id_for_path(base))
candidates.append("default")
if session_key: # bug-window legacy layout: per-session sandboxes
candidates.append(sanitize_task_id_for_path(f"session:{session_key}"))
diff --git a/tests/tools/test_docker_session_isolation.py b/tests/tools/test_docker_session_isolation.py
index 51e565ffc6d..c8710c770d9 100644
--- a/tests/tools/test_docker_session_isolation.py
+++ b/tests/tools/test_docker_session_isolation.py
@@ -69,13 +69,13 @@ def _disable_isolation(monkeypatch):
class TestSessionIsolationKeying:
- def test_persistent_true_keeps_shared_default(self, monkeypatch):
+ def test_persistent_true_keeps_shared_default(self, monkeypatch, tmp_path):
_disable_isolation(monkeypatch)
- # Default profile stays on the shared "default" key. Pin the name so a
- # named-profile test runner does not take the session-less profile path.
- monkeypatch.setattr(
- "hermes_cli.profiles.get_active_profile_name", lambda: "default"
- )
+ # The default profile's home stays on the shared "default" key (a named-profile
+ # home would take the profile path, so run from a real default root).
+ monkeypatch.setenv("HOME", str(tmp_path))
+ (tmp_path / ".hermes").mkdir()
+ monkeypatch.setenv("HERMES_HOME", str(tmp_path / ".hermes"))
assert terminal_tool._resolve_container_task_id("tui:sess-1") == "default"
def test_persistent_false_keys_by_session(self, monkeypatch):
diff --git a/tests/tools/test_shared_container_task_id.py b/tests/tools/test_shared_container_task_id.py
index 7c040211989..b2ee314d742 100644
--- a/tests/tools/test_shared_container_task_id.py
+++ b/tests/tools/test_shared_container_task_id.py
@@ -302,13 +302,17 @@ def test_shared_key_ignored_outside_persistent_docker(monkeypatch):
clear_session_vars(tokens)
-def _pin_profile(monkeypatch, name: str) -> None:
- monkeypatch.setattr(
- "hermes_cli.profiles.get_active_profile_name", lambda: name
- )
+def _use_home(monkeypatch, tmp_path, name):
+ """Run as a real home: ``"default"`` = the Hermes root, ``None`` = a home outside the root (which
+ is then its own root), anything else = ``<root>/profiles/<name>``."""
+ monkeypatch.setenv("HOME", str(tmp_path))
+ root = tmp_path / ".hermes"
+ home = root if name == "default" else tmp_path / "elsewhere" if name is None else root / "profiles" / name
+ home.mkdir(parents=True, exist_ok=True)
+ monkeypatch.setenv("HERMES_HOME", str(home))
-def test_sessionless_default_profile_stays_default(monkeypatch):
+def test_sessionless_default_profile_stays_default(monkeypatch, tmp_path):
"""Default profile, no session: CLI and workers still share "default"."""
from gateway.session_context import reset_session_vars
@@ -316,12 +320,12 @@ def test_sessionless_default_profile_stays_default(monkeypatch):
monkeypatch.delenv("HERMES_SESSION_KEY", raising=False)
monkeypatch.delenv("HERMES_SESSION_PROFILE", raising=False)
reset_session_vars()
- _pin_profile(monkeypatch, "default")
+ _use_home(monkeypatch, tmp_path, "default")
assert terminal_tool._resolve_container_task_id(None) == "default"
assert terminal_tool._resolve_container_task_id("kanban-task") == "default"
-def test_sessionless_named_profile_reuses_profile_container(monkeypatch):
+def test_sessionless_named_profile_reuses_profile_container(monkeypatch, tmp_path):
"""Named-profile process, no session: reuse profile:<name>, not "default"."""
from gateway.session_context import reset_session_vars
@@ -330,18 +334,18 @@ def test_sessionless_named_profile_reuses_profile_container(monkeypatch):
monkeypatch.delenv("HERMES_SESSION_PROFILE", raising=False)
monkeypatch.delenv("TERMINAL_DOCKER_SHARED_CONTAINER_KEY", raising=False)
reset_session_vars()
- _pin_profile(monkeypatch, "tenant-a")
+ _use_home(monkeypatch, tmp_path, "tenant-a")
assert terminal_tool._resolve_container_task_id(None) == "profile:tenant-a"
assert terminal_tool._resolve_container_task_id("t_b865ceb0") == "profile:tenant-a"
-def test_explicit_session_profile_wins_over_process_home(monkeypatch):
+def test_explicit_session_profile_wins_over_process_home(monkeypatch, tmp_path):
"""A bound session profile is authoritative, even if the process home differs."""
from gateway.session_context import clear_session_vars, set_session_vars
_persistent_docker(monkeypatch)
monkeypatch.delenv("HERMES_SESSION_KEY", raising=False)
- _pin_profile(monkeypatch, "tenant-a")
+ _use_home(monkeypatch, tmp_path, "tenant-a")
tokens = set_session_vars(session_key="agent:main:desktop:1", profile="work")
try:
assert terminal_tool._resolve_container_task_id(None) == "profile:work"
@@ -354,23 +358,166 @@ def test_explicit_session_profile_wins_over_process_home(monkeypatch):
clear_session_vars(tokens)
-def test_sessionless_named_profile_ignored_when_not_persistent_docker(monkeypatch):
+def test_sessionless_named_profile_ignored_when_not_persistent_docker(monkeypatch, tmp_path):
"""The profile key is a persistent-Docker rule. Local stays "default"."""
from gateway.session_context import reset_session_vars
monkeypatch.setenv("TERMINAL_ENV", "local")
monkeypatch.delenv("HERMES_SESSION_KEY", raising=False)
reset_session_vars()
- _pin_profile(monkeypatch, "tenant-a")
+ _use_home(monkeypatch, tmp_path, "tenant-a")
assert terminal_tool._resolve_container_task_id(None) == "default"
-def test_sessionless_custom_home_stays_default(monkeypatch):
- """A home that is not a named profile must not invent profile:custom."""
+def test_sessionless_home_outside_the_root_stays_default(monkeypatch, tmp_path):
+ """A home outside the Hermes root is its own root: it keys "default", never profile:custom."""
from gateway.session_context import reset_session_vars
_persistent_docker(monkeypatch)
monkeypatch.delenv("HERMES_SESSION_KEY", raising=False)
reset_session_vars()
- _pin_profile(monkeypatch, "custom")
+ _use_home(monkeypatch, tmp_path, None)
assert terminal_tool._resolve_container_task_id(None) == "default"
+
+
+def test_named_launch_profile_chats_desktop_and_workers_share_one_container(monkeypatch, tmp_path):
+ """A gateway launched as a named profile stamps no profile on its own chats; those chats, the
+ profile's Desktop sessions and its session-less cron/kanban work must all key one container."""
+ from gateway.session_context import clear_session_vars, reset_session_vars, set_session_vars
+
+ _persistent_docker(monkeypatch)
+ monkeypatch.delenv("HERMES_SESSION_KEY", raising=False)
+ monkeypatch.delenv("HERMES_SESSION_PROFILE", raising=False)
+ monkeypatch.delenv("TERMINAL_DOCKER_SHARED_CONTAINER_KEY", raising=False)
+ reset_session_vars()
+ _use_home(monkeypatch, tmp_path, "tenant-a")
+ keys = {"worker": terminal_tool._resolve_container_task_id("t_kanban")}
+ for label, profile in (("chat", ""), ("desktop", "tenant-a")):
+ tokens = set_session_vars(session_key=f"agent:main:{label}:1", profile=profile)
+ try:
+ keys[label] = terminal_tool._resolve_container_task_id("x")
+ finally:
+ clear_session_vars(tokens)
+ assert keys == dict.fromkeys(keys, "profile:tenant-a")
+
+
+def test_unnamed_session_in_default_or_outside_root_home_stays_default(monkeypatch, tmp_path):
+ """The default root and a home outside the root keep the shared default key."""
+ from gateway.session_context import clear_session_vars, set_session_vars
+
+ _persistent_docker(monkeypatch)
+ monkeypatch.delenv("TERMINAL_DOCKER_SHARED_CONTAINER_KEY", raising=False)
+ for home_profile in ("default", None):
+ _use_home(monkeypatch, tmp_path, home_profile)
+ tokens = set_session_vars(session_key="agent:main:telegram:dm:1", profile="")
+ try:
+ assert terminal_tool._resolve_container_task_id("x") == "default"
+ finally:
+ clear_session_vars(tokens)
+
+
+def test_file_panel_mirror_names_the_unnamed_chat_sandbox(monkeypatch, tmp_path):
+ """The file panel's best candidate must be the sandbox an unnamed chat of a named launch
+ profile actually uses, with and without a mounted workspace."""
+ from gateway.platforms.docker_media_paths import _docker_sandbox_dir_candidates
+ from gateway.session_context import clear_session_vars, set_session_vars
+ from tools.environments.path_utils import sanitize_task_id_for_path
+
+ _persistent_docker(monkeypatch)
+ monkeypatch.delenv("TERMINAL_DOCKER_SHARED_CONTAINER_KEY", raising=False)
+ monkeypatch.setenv("TERMINAL_DOCKER_MOUNT_CWD_TO_WORKSPACE", "true")
+ digest = "0123456789abcdef"
+ terminal_tool._task_env_overrides["ws"] = {
+ "cwd": "/host/proj", "cwd_source": "session", "workspace_key": digest}
+ for home_profile in ("tenant-a", "custom", None):
+ _use_home(monkeypatch, tmp_path, home_profile)
+ tokens = set_session_vars(session_key="agent:main:telegram:dm:1", profile="")
+ try:
+ plain = terminal_tool._resolve_container_task_id("plain")
+ mounted = terminal_tool._resolve_container_task_id("ws")
+ finally:
+ clear_session_vars(tokens)
+ assert _docker_sandbox_dir_candidates("agent:main:telegram:dm:1")[0] == sanitize_task_id_for_path(plain)
+ assert _docker_sandbox_dir_candidates(
+ "agent:main:telegram:dm:1", digest)[0] == sanitize_task_id_for_path(mounted)
+
+
+def test_a_profile_literally_named_custom_keys_its_own_container(monkeypatch, tmp_path):
+ """``custom`` is a valid profile name: its chats and workers key ``profile:custom`` like its
+ Desktop sessions, never ``default``."""
+ from gateway.session_context import clear_session_vars, reset_session_vars, set_session_vars
+
+ _persistent_docker(monkeypatch)
+ monkeypatch.delenv("HERMES_SESSION_KEY", raising=False)
+ monkeypatch.delenv("HERMES_SESSION_PROFILE", raising=False)
+ monkeypatch.delenv("TERMINAL_DOCKER_SHARED_CONTAINER_KEY", raising=False)
+ reset_session_vars()
+ _use_home(monkeypatch, tmp_path, "custom")
+ assert terminal_tool._resolve_container_task_id(None) == "profile:custom"
+ for profile in ("", "custom"):
+ tokens = set_session_vars(session_key="agent:main:telegram:dm:1", profile=profile)
+ try:
+ assert terminal_tool._resolve_container_task_id("x") == "profile:custom"
+ finally:
+ clear_session_vars(tokens)
+
+
[email protected]("home_parts", [("profiles", "work", "nested"), ("profiles", ".hidden"), ("loose",)])
+def test_a_home_the_tui_stamps_custom_keys_one_container_for_every_path(monkeypatch, tmp_path, home_parts):
+ """Inside the Hermes root but not a ``profiles/<name>`` home, the TUI stamps Desktop sessions
+ ``custom``; that home's chats and session-less work key the same container, and it is the file
+ panel's first candidate (the one a Save may write to), plain and mounted."""
+ from gateway.platforms.docker_media_paths import _docker_sandbox_dir_candidates
+ from gateway.session_context import clear_session_vars, reset_session_vars, set_session_vars
+ from tools.environments.path_utils import sanitize_task_id_for_path
+
+ monkeypatch.setenv("HOME", str(tmp_path))
+ home = tmp_path.joinpath(".hermes", *home_parts)
+ home.mkdir(parents=True)
+ monkeypatch.setenv("HERMES_HOME", str(home))
+ _persistent_docker(monkeypatch)
+ monkeypatch.delenv("HERMES_SESSION_KEY", raising=False)
+ monkeypatch.delenv("HERMES_SESSION_PROFILE", raising=False)
+ monkeypatch.delenv("TERMINAL_DOCKER_SHARED_CONTAINER_KEY", raising=False)
+ monkeypatch.setenv("TERMINAL_DOCKER_MOUNT_CWD_TO_WORKSPACE", "true")
+ from tui_gateway.server import _current_profile_name
+ assert _current_profile_name() == "custom"
+ reset_session_vars()
+ keys = {"worker": terminal_tool._resolve_container_task_id(None)}
+ digest = "0123456789abcdef"
+ terminal_tool._task_env_overrides["ws"] = {
+ "cwd": "/host/proj", "cwd_source": "session", "workspace_key": digest}
+ for label, profile in (("chat", ""), ("desktop", "custom")):
+ tokens = set_session_vars(session_key=f"agent:main:{label}:1", profile=profile)
+ try:
+ keys[label] = terminal_tool._resolve_container_task_id("x")
+ keys[f"{label}-ws"] = terminal_tool._resolve_container_task_id("ws")
+ finally:
+ clear_session_vars(tokens)
+ assert {k: v for k, v in keys.items() if not k.endswith("-ws")} == dict.fromkeys(
+ ("worker", "chat", "desktop"), "profile:custom")
+ assert keys["chat-ws"] == keys["desktop-ws"] == f"profile:custom:ws:{digest}"
+ assert _docker_sandbox_dir_candidates("agent:main:chat:1")[0] == sanitize_task_id_for_path(keys["chat"])
+ assert _docker_sandbox_dir_candidates(
+ "agent:main:chat:1", digest)[0] == sanitize_task_id_for_path(keys["chat-ws"])
+
+
+def test_home_profile_name_is_cached_per_home_never_across_homes(monkeypatch, tmp_path):
+ from tools.terminal_tool_config import home_profile_name
+
+ for name in ("tenant-a", "tenant-b", "default", "tenant-a"):
+ _use_home(monkeypatch, tmp_path, name)
+ assert home_profile_name() == name
+
+
+def test_an_unresolvable_home_keeps_the_shared_default_key(monkeypatch):
+ import hermes_constants
+ from gateway.platforms.docker_media_paths import _docker_sandbox_dir_candidates
+ from tools.terminal_tool_config import home_profile_name
+
+ def _boom():
+ raise RuntimeError("no home")
+
+ monkeypatch.setattr(hermes_constants, "get_hermes_home", _boom)
+ assert home_profile_name() == "default"
+ assert _docker_sandbox_dir_candidates()[0] == "default"
diff --git a/tools/environments/docker.py b/tools/environments/docker.py
index 89c22bcc7d0..4246028eff0 100644
--- a/tools/environments/docker.py
+++ b/tools/environments/docker.py
@@ -25,7 +25,7 @@ from typing import Optional
from hermes_constants import get_hermes_home
from tools.environments.base import BaseEnvironment, EnvironmentConnectionError, _SHELL_ENV_NAME_RE, get_sandbox_dir
from tools.terminal_tool_config import (
- _host_path_key, _is_windows_drive_path, cwd_follows_host_mount,
+ _host_path_key, _is_windows_drive_path, cwd_follows_host_mount, home_profile_name,
)
from tools.environments.base_output import _popen_bash
from tools.environments.docker_egress import (
@@ -115,13 +115,10 @@ _sandbox_dir_name = sanitize_task_id_for_path
def _get_active_profile_name() -> str:
- """Active Hermes profile name, or ``"default"`` on any error. Resolved at container-create
- time so a container stays tagged with its creator even if the process switches profiles."""
- try:
- from hermes_cli.profiles import get_active_profile_name
- return get_active_profile_name() or "default"
- except Exception:
- return "default"
+ """Active Hermes profile name (the container key's own lookup), or ``"default"`` on error. Resolved
+ at container-create time so a container stays tagged with its creator even if the process switches
+ profiles."""
+ return home_profile_name()
def _container_identity(shared_key: str = "") -> str:
diff --git a/tools/terminal_tool.py b/tools/terminal_tool.py
index 81ebce8e870..e88972a41e5 100644
--- a/tools/terminal_tool.py
+++ b/tools/terminal_tool.py
@@ -47,7 +47,8 @@ from tools.terminal_tool_lifecycle import (
from tools.terminal_tool_config import (
_is_container_backend, _is_host_cwd, _is_mounted_host_cwd, _is_unusable_container_cwd,
_is_windows_drive_path, _parse_env_var, _plugin_env_flag, _quiet, _safe_getcwd, _tenv, _tenv_bool,
- _in_sandbox_home, coerce_ssh_remote_cwd, translate_mounted_host_path,
+ _in_sandbox_home, coerce_ssh_remote_cwd, home_profile_name, profile_container_key,
+ translate_mounted_host_path,
)
from tools.terminal_tool_backends import (
_REQUIREMENT_CHECKERS, _VERCEL_SANDBOX_DEFAULT_CWD, _check_plugin_requirements,
@@ -122,8 +123,9 @@ def _container_profile() -> str:
"""Profile whose persistent container a session-bound command uses: the bound home's profile when it is not
the session's own (a profile-routed subagent runs in its target's home while the session, and the delivery
identity HERMES_SESSION_PROFILE carries, stay the parent's; that target may be the launch profile, reached
- from a routed profile's chat), else the session's. A session with no profile name is the launch profile's,
- so the launch home's own work keeps the session's key whatever the launch profile is named."""
+ from a routed profile's chat), else the session's. A session with no profile name (a gateway launched as a
+ named profile stamps none on its own chats) is the launch profile's, so it keys that profile by name, like
+ the profile's Desktop sessions and its session-less work (:func:`_sessionless_container_key`)."""
from hermes_constants import get_hermes_home_override, profile_name_for_home
from tools.environments.local import _is_routed_home
@@ -132,7 +134,7 @@ def _container_profile() -> str:
bound = profile_name_for_home(override) if override else None
if bound and (bound != session if session else _is_routed_home(override)):
return bound
- return session or "default"
+ return session or home_profile_name()
from tools.approval import (
@@ -474,7 +476,7 @@ def _routed_home_task_key(profile_scoped: bool) -> Optional[str]:
return None
profile = profile_name_for_home(override) if profile_scoped else None
if profile:
- return "default" if profile == "default" else f"profile:{profile}"
+ return profile_container_key(profile)
try:
return f"home:{os.path.realpath(override)}"
except OSError:
@@ -489,22 +491,13 @@ def _sessionless_container_key(profile_scoped: bool) -> str:
session-bound work of that profile uses. Dispatcher workers set
``HERMES_HOME`` and clear session vars, so they are not a routed override;
without this they collapsed onto ``default`` and missed the profile sandbox.
- The default profile, non-persistent backends, and a home that is not a
- named profile stay ``default``.
+ The default profile, non-persistent backends, and a home outside the Hermes
+ root stay ``default`` (:func:`~tools.terminal_tool_config.home_profile_name` names the profile).
"""
routed = _routed_home_task_key(profile_scoped)
if routed:
return routed
- if not profile_scoped:
- return "default"
- try:
- from hermes_cli.profiles import get_active_profile_name
- profile = (get_active_profile_name() or "").strip()
- except Exception:
- return "default"
- if not profile or profile in {"default", "custom"}:
- return "default"
- return f"profile:{profile}"
+ return profile_container_key(home_profile_name()) if profile_scoped else "default"
def _qualify_task_key(key: str) -> str:
@@ -532,8 +525,9 @@ def _resolve_container_task_id(task_id: Optional[str]) -> str:
ITS mounts); delegate_task children follow the alias registry to the parent.
Routed profiles qualify the key (:func:`_qualify_task_key`, #123989).
3. Session key present (WebUI per-session, gateway per-message): persistent
- Docker is PROFILE-scoped — ``shared:<key>`` opt-in, else ``profile:<name>``,
- with the default profile staying literally ``"default"`` so CLI and
+ Docker is PROFILE-scoped — ``shared:<key>`` opt-in, else ``profile:<name>``
+ (a session naming no profile takes the process home's), with the default
+ profile staying literally ``"default"`` so CLI and
default-profile gateway sessions share ONE container; other backends key
``session:<key>`` so switching profiles can't reuse another profile's
SSHEnvironment on the wrong host.
@@ -568,9 +562,7 @@ def _resolve_container_task_id(task_id: Optional[str]) -> str:
return _sessionless_container_key(scope.docker_profile_scoped)
if not scope.docker_profile_scoped:
return _qualify_task_key(f"session:{session_key}")
- profile = _container_profile()
- base = "default" if profile == "default" else f"profile:{profile}"
- return _workspace_container_key(base, task_id)
+ return _workspace_container_key(profile_container_key(_container_profile()), task_id)
def workspace_key_for(cwd: str) -> str:
diff --git a/tools/terminal_tool_config.py b/tools/terminal_tool_config.py
index 5f938b1c8d7..0c89a159589 100644
--- a/tools/terminal_tool_config.py
+++ b/tools/terminal_tool_config.py
@@ -43,6 +43,40 @@ def _parse_env_var(name: str, default: str, converter: Any = int, type_label: st
)
+# (current home, Hermes root) -> profile name; only homes that exist are stored (see home_profile_name).
+_HOME_PROFILE_NAMES: dict[tuple[str, str], str] = {}
+
+
+def home_profile_name() -> str:
+ """Profile name of the current Hermes home (the process home, or a routed turn's bound home);
+ ``"default"`` when it cannot be resolved. One lookup for every reader that must agree: the
+ persistent-Docker container key, the container's profile label, the name the TUI stamps on its
+ sessions (``get_active_profile_name``, so ``custom`` for a home inside the root that is not a
+ ``profiles/<name>`` home), and the file panel's sandbox names.
+
+ Memoized per (home, root) path pair: the lookup resolves three paths and runs on every
+ container-key resolution, several times per tool call."""
+ try:
+ from hermes_cli.profiles import get_active_profile_name
+ from hermes_constants import get_default_hermes_root, get_hermes_home
+
+ home = get_hermes_home()
+ key = (str(home), str(get_default_hermes_root()))
+ if (cached := _HOME_PROFILE_NAMES.get(key)) is not None:
+ return cached
+ name = get_active_profile_name() or "default"
+ if home.exists(): # a home created later may resolve differently
+ _HOME_PROFILE_NAMES[key] = name
+ return name
+ except (ImportError, OSError, RuntimeError, ValueError): # an unresolvable home keeps the shared default key
+ return "default"
+
+
+def profile_container_key(profile: str) -> str:
+ """Persistent-Docker container key of a profile: the default profile stays literally ``"default"``."""
+ return "default" if profile == "default" else f"profile:{profile}"
+
+
def _safe_getcwd() -> str:
"""``os.getcwd()`` tolerant of a deleted cwd (FileNotFoundError) or a macOS
TCC-protected one without Full Disk Access (PermissionError); falls back
diff --git a/website/docs/user-guide/configuration.md b/website/docs/user-guide/configuration.md
index bac17a9b104..4fc9743e639 100644
--- a/website/docs/user-guide/configuration.md
+++ b/website/docs/user-guide/configuration.md
@@ -371,6 +371,8 @@ Runs commands inside a Docker container with security hardening (all capabilitie
Earlier builds gave each Desktop folder its own sandbox even with mounting off. Those directories (`*_ws_*` under `TERMINAL_SANDBOX_DIR/docker`, default `sandboxes/docker` in the profile's Hermes home) are kept but no longer used by the terminal or the file panel: copy anything you still need into the profile sandbox's `workspace` or `home`.
+In a named profile, its gateway chats, Desktop sessions, cron jobs and Kanban workers all use the profile's one sandbox (`profile_<name>-*` under `TERMINAL_SANDBOX_DIR/docker`). Earlier builds kept a gateway launched as that profile (`hermes -p <name> gateway`) and its cron and Kanban work in a separate `default` sandbox under the profile's home. That directory is kept but no longer used: copy anything you still need from it the same way.
+
Terminal, file, and `execute_code` calls use `docker exec` in the selected container. Installed packages, files in `/workspace`, and **background processes** carry over between calls and Hermes processes using that container. Closing a TUI session, running `/quit`, or starting a new `hermes` invocation does not itself remove it; the next process can reuse it through its labels. See **Container lifecycle** below for the exact teardown rules.
**Per-session isolation mode (`container_persistent: false`).** Setting `container_persistent: false` on the Docker backend switches to one container **per session**: every chat (desktop app session, gateway conversation, TUI session) gets its own fresh sandbox, created on its first terminal/file call and removed when the session closes or goes idle past `lifetime_seconds`. Nothing carries over between sessions — no filesystem state, no mounts, no background processes. With `docker_mount_cwd_to_workspace: true`, only the workspace **attached to that session** is mounted at `/workspace`; a fresh session with no attached directory gets an empty workspace instead of inheriting the previous session's mount. `delegate_task` subagents still share their parent session's container. Use this mode when the sandbox is a security boundary between conversations; keep the default `true` when you want the long-lived shared container described above.