Merge branch 'main' into feat/web-ui

migrate_model_config() was writing `config["model"] = model_str` which
replaces the entire model dict (default, provider, base_url) with a
bare string. This causes 'str' object has no attribute 'get' errors
throughout Hermes when any code does model_cfg.get("default").

Now preserves the existing model dict and only updates the "default"
key, keeping provider/base_url intact.

.gitignore

@@ -38,7 +38,7 @@ agent-browser/
 privvy*
 images/
 __pycache__/
-hermes_agent.egg-info/
+*.egg-info/
 wandb/
 testlogs
 
@@ -51,6 +51,9 @@ ignored/
 .worktrees/
 environments/benchmarks/evals/
 
+# Web UI build output
+hermes_cli/web_dist/
+
 # Release script temp files
 .release_notes.md
 mini-swe-agent/

.python-version

@@ -0,0 +1 @@
+3.11

cli-config.yaml.example

@@ -324,6 +324,9 @@ compression:
 #   vision:
 #     provider: "auto"
 #     model: ""              # e.g. "google/gemini-2.5-flash", "openai/gpt-4o"
+#     timeout: 30            # LLM API call timeout (seconds)
+#     download_timeout: 30   # Image HTTP download timeout (seconds)
+#                            # Increase for slow connections or self-hosted image servers
 #
 #   # Web page scraping / summarization + browser page text extraction
 #   web_extract:

cli.py

@@ -2789,22 +2789,12 @@ class HermesCLI:
             print(f"  MCP tool:          /tools {subcommand} github:create_issue")
             return
 
-        # Confirm session reset before applying
-        verb = "Disable" if subcommand == "disable" else "Enable"
+        # Apply the change directly — the user typing the command is implicit
+        # consent.  Do NOT use input() here; it hangs inside prompt_toolkit's
+        # TUI event loop (known pitfall).
+        verb = "Disabling" if subcommand == "disable" else "Enabling"
         label = ", ".join(names)
-        _cprint(f"{_GOLD}{verb} {label}?{_RST}")
-        _cprint(f"{_DIM}This will save to config and reset your session so the "
-                f"change takes effect cleanly.{_RST}")
-        try:
-            answer = input("  Continue? [y/N] ").strip().lower()
-        except (EOFError, KeyboardInterrupt):
-            print()
-            _cprint(f"{_DIM}Cancelled.{_RST}")
-            return
-
-        if answer not in ("y", "yes"):
-            _cprint(f"{_DIM}Cancelled.{_RST}")
-            return
+        _cprint(f"{_GOLD}{verb} {label}...{_RST}")
 
         tools_disable_enable_command(
             Namespace(tools_action=subcommand, names=names, platform="cli"))
@@ -3856,6 +3846,10 @@ class HermesCLI:
             self._show_insights(cmd_original)
         elif canonical == "paste":
             self._handle_paste_command()
+        elif canonical == "reload":
+            from hermes_cli.config import reload_env
+            count = reload_env()
+            print(f"  Reloaded .env ({count} var(s) updated)")
         elif canonical == "reload-mcp":
             with self._busy_command(self._slow_command_status(cmd_original)):
                 self._reload_mcp()
@@ -6210,6 +6204,11 @@ class HermesCLI:
         self._interrupt_queue = queue.Queue()   # For messages typed while agent is running
         self._should_exit = False
         self._last_ctrl_c_time = 0  # Track double Ctrl+C for force exit
+
+        # Give plugin manager a CLI reference so plugins can inject messages
+        from hermes_cli.plugins import get_plugin_manager
+        get_plugin_manager()._cli_ref = self
+
         # Config file watcher — detect mcp_servers changes and auto-reload
         from hermes_cli.config import get_config_path as _get_config_path
         _cfg_path = _get_config_path()

cron/scheduler.py

@@ -236,11 +236,12 @@ def _build_job_prompt(job: dict) -> str:
     # Always prepend [SILENT] guidance so the cron agent can suppress
     # delivery when it has nothing new or noteworthy to report.
     silent_hint = (
-        "[SYSTEM: If you have nothing new or noteworthy to report, respond "
-        "with exactly \"[SILENT]\" (optionally followed by a brief internal "
-        "note). This suppresses delivery to the user while still saving "
-        "output locally. Only use [SILENT] when there are genuinely no "
-        "changes worth reporting.]\n\n"
+        "[SYSTEM: If you have a meaningful status report or findings, "
+        "send them — that is the whole point of this job. Only respond "
+        "with exactly \"[SILENT]\" (nothing else) when there is genuinely "
+        "nothing new to report. [SILENT] suppresses delivery to the user. "
+        "Never combine [SILENT] with content — either report your "
+        "findings normally, or say [SILENT] and nothing more.]\n\n"
     )
     prompt = silent_hint + prompt
     if skills is None:

gateway/platforms/slack.py

@@ -9,6 +9,7 @@ Uses slack-bolt (Python) with Socket Mode for:
 """
 
 import asyncio
+import json
 import logging
 import os
 import re
@@ -73,6 +74,10 @@ class SlackAdapter(BasePlatformAdapter):
         self._bot_user_id: Optional[str] = None
         self._user_name_cache: Dict[str, str] = {}  # user_id → display name
         self._socket_mode_task: Optional[asyncio.Task] = None
+        # Multi-workspace support
+        self._team_clients: Dict[str, AsyncWebClient] = {}   # team_id → WebClient
+        self._team_bot_user_ids: Dict[str, str] = {}          # team_id → bot_user_id
+        self._channel_team: Dict[str, str] = {}                # channel_id → team_id
 
     async def connect(self) -> bool:
         """Connect to Slack via Socket Mode."""
@@ -82,16 +87,34 @@ class SlackAdapter(BasePlatformAdapter):
             )
             return False
 
-        bot_token = self.config.token
+        raw_token = self.config.token
         app_token = os.getenv("SLACK_APP_TOKEN")
 
-        if not bot_token:
+        if not raw_token:
             logger.error("[Slack] SLACK_BOT_TOKEN not set")
             return False
         if not app_token:
             logger.error("[Slack] SLACK_APP_TOKEN not set")
             return False
 
+        # Support comma-separated bot tokens for multi-workspace
+        bot_tokens = [t.strip() for t in raw_token.split(",") if t.strip()]
+
+        # Also load tokens from OAuth token file
+        from hermes_constants import get_hermes_home
+        tokens_file = get_hermes_home() / "slack_tokens.json"
+        if tokens_file.exists():
+            try:
+                saved = json.loads(tokens_file.read_text(encoding="utf-8"))
+                for team_id, entry in saved.items():
+                    tok = entry.get("token", "") if isinstance(entry, dict) else ""
+                    if tok and tok not in bot_tokens:
+                        bot_tokens.append(tok)
+                        team_label = entry.get("team_name", team_id) if isinstance(entry, dict) else team_id
+                        logger.info("[Slack] Loaded saved token for workspace %s", team_label)
+            except Exception as e:
+                logger.warning("[Slack] Failed to read %s: %s", tokens_file, e)
+
         try:
             # Acquire scoped lock to prevent duplicate app token usage
             from gateway.status import acquire_scoped_lock
@@ -104,12 +127,30 @@ class SlackAdapter(BasePlatformAdapter):
                 self._set_fatal_error('slack_token_lock', message, retryable=False)
                 return False
 
-            self._app = AsyncApp(token=bot_token)
+            # First token is the primary — used for AsyncApp / Socket Mode
+            primary_token = bot_tokens[0]
+            self._app = AsyncApp(token=primary_token)
 
-            # Get our own bot user ID for mention detection
-            auth_response = await self._app.client.auth_test()
-            self._bot_user_id = auth_response.get("user_id")
-            bot_name = auth_response.get("user", "unknown")
+            # Register each bot token and map team_id → client
+            for token in bot_tokens:
+                client = AsyncWebClient(token=token)
+                auth_response = await client.auth_test()
+                team_id = auth_response.get("team_id", "")
+                bot_user_id = auth_response.get("user_id", "")
+                bot_name = auth_response.get("user", "unknown")
+                team_name = auth_response.get("team", "unknown")
+
+                self._team_clients[team_id] = client
+                self._team_bot_user_ids[team_id] = bot_user_id
+
+                # First token sets the primary bot_user_id (backward compat)
+                if self._bot_user_id is None:
+                    self._bot_user_id = bot_user_id
+
+                logger.info(
+                    "[Slack] Authenticated as @%s in workspace %s (team: %s)",
+                    bot_name, team_name, team_id,
+                )
 
             # Register message event handler
             @self._app.event("message")
@@ -134,7 +175,10 @@ class SlackAdapter(BasePlatformAdapter):
             self._socket_mode_task = asyncio.create_task(self._handler.start_async())
 
             self._running = True
-            logger.info("[Slack] Connected as @%s (Socket Mode)", bot_name)
+            logger.info(
+                "[Slack] Socket Mode connected (%d workspace(s))",
+                len(self._team_clients),
+            )
             return True
 
         except Exception as e:  # pragma: no cover - defensive logging
@@ -161,6 +205,13 @@ class SlackAdapter(BasePlatformAdapter):
 
         logger.info("[Slack] Disconnected")
 
+    def _get_client(self, chat_id: str) -> AsyncWebClient:
+        """Return the workspace-specific WebClient for a channel."""
+        team_id = self._channel_team.get(chat_id)
+        if team_id and team_id in self._team_clients:
+            return self._team_clients[team_id]
+        return self._app.client  # fallback to primary
+
     async def send(
         self,
         chat_id: str,
@@ -197,7 +248,7 @@ class SlackAdapter(BasePlatformAdapter):
                     if broadcast and i == 0:
                         kwargs["reply_broadcast"] = True
 
-                last_result = await self._app.client.chat_postMessage(**kwargs)
+                last_result = await self._get_client(chat_id).chat_postMessage(**kwargs)
 
             return SendResult(
                 success=True,
@@ -219,7 +270,7 @@ class SlackAdapter(BasePlatformAdapter):
         if not self._app:
             return SendResult(success=False, error="Not connected")
         try:
-            await self._app.client.chat_update(
+            await self._get_client(chat_id).chat_update(
                 channel=chat_id,
                 ts=message_id,
                 text=content,
@@ -253,7 +304,7 @@ class SlackAdapter(BasePlatformAdapter):
             return  # Can only set status in a thread context
 
         try:
-            await self._app.client.assistant_threads_setStatus(
+            await self._get_client(chat_id).assistant_threads_setStatus(
                 channel_id=chat_id,
                 thread_ts=thread_ts,
                 status="is thinking...",
@@ -295,7 +346,7 @@ class SlackAdapter(BasePlatformAdapter):
         if not os.path.exists(file_path):
             raise FileNotFoundError(f"File not found: {file_path}")
 
-        result = await self._app.client.files_upload_v2(
+        result = await self._get_client(chat_id).files_upload_v2(
             channel=chat_id,
             file=file_path,
             filename=os.path.basename(file_path),
@@ -397,7 +448,7 @@ class SlackAdapter(BasePlatformAdapter):
         if not self._app:
             return False
         try:
-            await self._app.client.reactions_add(
+            await self._get_client(channel).reactions_add(
                 channel=channel, timestamp=timestamp, name=emoji
             )
             return True
@@ -413,7 +464,7 @@ class SlackAdapter(BasePlatformAdapter):
         if not self._app:
             return False
         try:
-            await self._app.client.reactions_remove(
+            await self._get_client(channel).reactions_remove(
                 channel=channel, timestamp=timestamp, name=emoji
             )
             return True
@@ -423,7 +474,7 @@ class SlackAdapter(BasePlatformAdapter):
 
     # ----- User identity resolution -----
 
-    async def _resolve_user_name(self, user_id: str) -> str:
+    async def _resolve_user_name(self, user_id: str, chat_id: str = "") -> str:
         """Resolve a Slack user ID to a display name, with caching."""
         if not user_id:
             return ""
@@ -434,7 +485,8 @@ class SlackAdapter(BasePlatformAdapter):
             return user_id
 
         try:
-            result = await self._app.client.users_info(user=user_id)
+            client = self._get_client(chat_id) if chat_id else self._app.client
+            result = await client.users_info(user=user_id)
             user = result.get("user", {})
             # Prefer display_name → real_name → user_id
             profile = user.get("profile", {})
@@ -498,7 +550,7 @@ class SlackAdapter(BasePlatformAdapter):
                 response = await client.get(image_url)
                 response.raise_for_status()
 
-            result = await self._app.client.files_upload_v2(
+            result = await self._get_client(chat_id).files_upload_v2(
                 channel=chat_id,
                 content=response.content,
                 filename="image.png",
@@ -558,7 +610,7 @@ class SlackAdapter(BasePlatformAdapter):
             return SendResult(success=False, error=f"Video file not found: {video_path}")
 
         try:
-            result = await self._app.client.files_upload_v2(
+            result = await self._get_client(chat_id).files_upload_v2(
                 channel=chat_id,
                 file=video_path,
                 filename=os.path.basename(video_path),
@@ -599,7 +651,7 @@ class SlackAdapter(BasePlatformAdapter):
         display_name = file_name or os.path.basename(file_path)
 
         try:
-            result = await self._app.client.files_upload_v2(
+            result = await self._get_client(chat_id).files_upload_v2(
                 channel=chat_id,
                 file=file_path,
                 filename=display_name,
@@ -627,7 +679,7 @@ class SlackAdapter(BasePlatformAdapter):
             return {"name": chat_id, "type": "unknown"}
 
         try:
-            result = await self._app.client.conversations_info(channel=chat_id)
+            result = await self._get_client(chat_id).conversations_info(channel=chat_id)
             channel = result.get("channel", {})
             is_dm = channel.get("is_im", False)
             return {
@@ -660,6 +712,11 @@ class SlackAdapter(BasePlatformAdapter):
         user_id = event.get("user", "")
         channel_id = event.get("channel", "")
         ts = event.get("ts", "")
+        team_id = event.get("team", "")
+
+        # Track which workspace owns this channel
+        if team_id and channel_id:
+            self._channel_team[channel_id] = team_id
 
         # Determine if this is a DM or channel message
         channel_type = event.get("channel_type", "")
@@ -676,11 +733,12 @@ class SlackAdapter(BasePlatformAdapter):
             thread_ts = event.get("thread_ts") or ts  # ts fallback for channels
 
         # In channels, only respond if bot is mentioned
-        if not is_dm and self._bot_user_id:
-            if f"<@{self._bot_user_id}>" not in text:
+        bot_uid = self._team_bot_user_ids.get(team_id, self._bot_user_id)
+        if not is_dm and bot_uid:
+            if f"<@{bot_uid}>" not in text:
                 return
             # Strip the bot mention from the text
-            text = text.replace(f"<@{self._bot_user_id}>", "").strip()
+            text = text.replace(f"<@{bot_uid}>", "").strip()
 
         # Determine message type
         msg_type = MessageType.TEXT
@@ -700,7 +758,7 @@ class SlackAdapter(BasePlatformAdapter):
                     if ext not in (".jpg", ".jpeg", ".png", ".gif", ".webp"):
                         ext = ".jpg"
                     # Slack private URLs require the bot token as auth header
-                    cached = await self._download_slack_file(url, ext)
+                    cached = await self._download_slack_file(url, ext, team_id=team_id)
                     media_urls.append(cached)
                     media_types.append(mimetype)
                     msg_type = MessageType.PHOTO
@@ -711,7 +769,7 @@ class SlackAdapter(BasePlatformAdapter):
                     ext = "." + mimetype.split("/")[-1].split(";")[0]
                     if ext not in (".ogg", ".mp3", ".wav", ".webm", ".m4a"):
                         ext = ".ogg"
-                    cached = await self._download_slack_file(url, ext, audio=True)
+                    cached = await self._download_slack_file(url, ext, audio=True, team_id=team_id)
                     media_urls.append(cached)
                     media_types.append(mimetype)
                     msg_type = MessageType.VOICE
@@ -742,7 +800,7 @@ class SlackAdapter(BasePlatformAdapter):
                         continue
 
                     # Download and cache
-                    raw_bytes = await self._download_slack_file_bytes(url)
+                    raw_bytes = await self._download_slack_file_bytes(url, team_id=team_id)
                     cached_path = cache_document_from_bytes(
                         raw_bytes, original_filename or f"document{ext}"
                     )
@@ -771,7 +829,7 @@ class SlackAdapter(BasePlatformAdapter):
                     logger.warning("[Slack] Failed to cache document from %s: %s", url, e, exc_info=True)
 
         # Resolve user display name (cached after first lookup)
-        user_name = await self._resolve_user_name(user_id)
+        user_name = await self._resolve_user_name(user_id, chat_id=channel_id)
 
         # Build source
         source = self.build_source(
@@ -808,6 +866,11 @@ class SlackAdapter(BasePlatformAdapter):
         text = command.get("text", "").strip()
         user_id = command.get("user_id", "")
         channel_id = command.get("channel_id", "")
+        team_id = command.get("team_id", "")
+
+        # Track which workspace owns this channel
+        if team_id and channel_id:
+            self._channel_team[channel_id] = team_id
 
         # Map subcommands to gateway commands — derived from central registry.
         # Also keep "compact" as a Slack-specific alias for /compress.
@@ -839,12 +902,12 @@ class SlackAdapter(BasePlatformAdapter):
 
         await self.handle_message(event)
 
-    async def _download_slack_file(self, url: str, ext: str, audio: bool = False) -> str:
+    async def _download_slack_file(self, url: str, ext: str, audio: bool = False, team_id: str = "") -> str:
         """Download a Slack file using the bot token for auth, with retry."""
         import asyncio
         import httpx
 
-        bot_token = self.config.token
+        bot_token = self._team_clients[team_id].token if team_id and team_id in self._team_clients else self.config.token
         last_exc = None
 
         async with httpx.AsyncClient(timeout=30.0, follow_redirects=True) as client:
@@ -874,12 +937,12 @@ class SlackAdapter(BasePlatformAdapter):
                     raise
         raise last_exc
 
-    async def _download_slack_file_bytes(self, url: str) -> bytes:
+    async def _download_slack_file_bytes(self, url: str, team_id: str = "") -> bytes:
         """Download a Slack file and return raw bytes, with retry."""
         import asyncio
         import httpx
 
-        bot_token = self.config.token
+        bot_token = self._team_clients[team_id].token if team_id and team_id in self._team_clients else self.config.token
         last_exc = None
 
         async with httpx.AsyncClient(timeout=30.0, follow_redirects=True) as client:

gateway/run.py

@@ -3891,7 +3891,7 @@ class GatewayRunner:
                 # Send media files
                 for media_path in (media_files or []):
                     try:
-                        await adapter.send_file(
+                        await adapter.send_document(
                             chat_id=source.chat_id,
                             file_path=media_path,
                         )

hermes_cli/commands.py

@@ -109,6 +109,7 @@ COMMAND_REGISTRY: list[CommandDef] = [
     CommandDef("cron", "Manage scheduled tasks", "Tools & Skills",
                cli_only=True, args_hint="[subcommand]",
                subcommands=("list", "add", "create", "edit", "pause", "resume", "run", "remove")),
+    CommandDef("reload", "Reload .env variables into the running session", "Tools & Skills"),
     CommandDef("reload-mcp", "Reload MCP servers from config", "Tools & Skills",
                aliases=("reload_mcp",)),
     CommandDef("browser", "Connect browser tools to your live Chrome via CDP", "Tools & Skills",

hermes_cli/config.py

@@ -223,7 +223,8 @@ DEFAULT_CONFIG = {
             "model": "",           # e.g. "google/gemini-2.5-flash", "gpt-4o"
             "base_url": "",        # direct OpenAI-compatible endpoint (takes precedence over provider)
             "api_key": "",         # API key for base_url (falls back to OPENAI_API_KEY)
-            "timeout": 30,         # seconds — increase for slow local vision models
+            "timeout": 30,         # seconds — LLM API call timeout; increase for slow local vision models
+            "download_timeout": 30,  # seconds — image HTTP download timeout; increase for slow connections
         },
         "web_extract": {
             "provider": "auto",
@@ -1671,6 +1672,51 @@ def save_env_value_secure(key: str, value: str) -> Dict[str, Any]:
     }
 
 
+def delete_env_value(key: str) -> bool:
+    """Remove a key from ~/.hermes/.env. Returns True if the key was found and removed."""
+    env_path = get_env_path()
+    if not env_path.exists():
+        return False
+
+    read_kw = {"encoding": "utf-8", "errors": "replace"} if _IS_WINDOWS else {}
+    write_kw = {"encoding": "utf-8"} if _IS_WINDOWS else {}
+
+    with open(env_path, **read_kw) as f:
+        lines = f.readlines()
+
+    new_lines = [l for l in lines if not l.strip().startswith(f"{key}=")]
+    if len(new_lines) == len(lines):
+        return False
+
+    fd, tmp_path = tempfile.mkstemp(dir=str(env_path.parent), suffix='.tmp', prefix='.env_')
+    try:
+        with os.fdopen(fd, 'w', **write_kw) as f:
+            f.writelines(new_lines)
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(tmp_path, env_path)
+    except BaseException:
+        try:
+            os.unlink(tmp_path)
+        except OSError:
+            pass
+        raise
+    _secure_file(env_path)
+
+    os.environ.pop(key, None)
+    return True
+
+
+def reload_env() -> int:
+    """Re-read ~/.hermes/.env into os.environ. Returns count of vars updated."""
+    env_vars = load_env()
+    count = 0
+    for key, value in env_vars.items():
+        if os.environ.get(key) != value:
+            os.environ[key] = value
+            count += 1
+    return count
+
 
 def get_env_value(key: str) -> Optional[str]:
     """Get a value from ~/.hermes/.env or environment."""

hermes_cli/main.py

@@ -41,6 +41,7 @@ Usage:
     hermes sessions browse     Interactive session picker with search
 
     hermes claw migrate --dry-run  # Preview migration without changes
+    hermes web                 # Start web UI dashboard
 """
 
 import argparse
@@ -2489,6 +2490,48 @@ def _clear_bytecode_cache(root: Path) -> int:
                 pass
             dirnames.clear()  # nothing left to recurse into
     return removed
+def cmd_web(args):
+    """Start the web UI server."""
+    try:
+        import fastapi  # noqa: F401
+        import uvicorn  # noqa: F401
+    except ImportError:
+        print("Web UI dependencies not installed.")
+        print("Install them with:  pip install hermes-agent[web]")
+        sys.exit(1)
+
+    web_dist = PROJECT_ROOT / "hermes_cli" / "web_dist"
+    web_src = PROJECT_ROOT / "web"
+    if not web_dist.exists() and (web_src / "package.json").exists():
+        import shutil
+        npm = shutil.which("npm")
+        if npm:
+            import subprocess
+            print("→ Web UI not built yet — building now...")
+            r1 = subprocess.run([npm, "install", "--silent"], cwd=web_src, capture_output=True)
+            if r1.returncode == 0:
+                r2 = subprocess.run([npm, "run", "build"], cwd=web_src, capture_output=True)
+                if r2.returncode == 0:
+                    print("  ✓ Web UI built")
+                else:
+                    print("  ✗ Web UI build failed")
+                    print("  Run manually:  cd web && npm install && npm run build")
+                    sys.exit(1)
+            else:
+                print("  ✗ npm install failed")
+                print("  Run manually:  cd web && npm install && npm run build")
+                sys.exit(1)
+        else:
+            print("Web UI frontend not built and npm is not available.")
+            print("Install Node.js, then run:  cd web && npm install && npm run build")
+            sys.exit(1)
+
+    from hermes_cli.web_server import start_server
+    start_server(
+        host=args.host,
+        port=args.port,
+        open_browser=not args.no_open,
+    )
 
 
 def _update_via_zip(args):
@@ -2599,6 +2642,20 @@ def _update_via_zip(args):
             print("  ⚠ Optional extras failed, installing base dependencies...")
             subprocess.run(pip_cmd + ["install", "-e", ".", "--quiet"], cwd=PROJECT_ROOT, check=True)
     
+    # Build web UI frontend
+    web_dir = PROJECT_ROOT / "web"
+    if (web_dir / "package.json").exists() and shutil.which("npm"):
+        print("→ Building web UI...")
+        r1 = subprocess.run(["npm", "install", "--silent"], cwd=web_dir, capture_output=True)
+        if r1.returncode == 0:
+            r2 = subprocess.run(["npm", "run", "build"], cwd=web_dir, capture_output=True)
+            if r2.returncode == 0:
+                print("  ✓ Web UI built")
+            else:
+                print("  ⚠ Web UI build failed (hermes web will not be available)")
+        else:
+            print("  ⚠ Web UI npm install failed (hermes web will not be available)")
+    
     # Sync skills
     try:
         from tools.skills_sync import sync_skills
@@ -3010,6 +3067,22 @@ def cmd_update(args):
                 print("→ Updating Node.js dependencies...")
                 subprocess.run(["npm", "install", "--silent"], cwd=PROJECT_ROOT, check=False)
         
+        # Build web UI frontend
+        web_dir = PROJECT_ROOT / "web"
+        if (web_dir / "package.json").exists():
+            import shutil
+            if shutil.which("npm"):
+                print("→ Building web UI...")
+                r1 = subprocess.run(["npm", "install", "--silent"], cwd=web_dir, capture_output=True)
+                if r1.returncode == 0:
+                    r2 = subprocess.run(["npm", "run", "build"], cwd=web_dir, capture_output=True)
+                    if r2.returncode == 0:
+                        print("  ✓ Web UI built")
+                    else:
+                        print("  ⚠ Web UI build failed (hermes web will not be available)")
+                else:
+                    print("  ⚠ Web UI npm install failed (hermes web will not be available)")
+        
         print()
         print("✓ Code updated!")
         
@@ -3268,7 +3341,7 @@ def _coalesce_session_name_args(argv: list) -> list:
         "chat", "model", "gateway", "setup", "whatsapp", "login", "logout",
         "status", "cron", "doctor", "config", "pairing", "skills", "tools",
         "mcp", "sessions", "insights", "version", "update", "uninstall",
-        "profile",
+        "profile", "web",
     }
     _SESSION_FLAGS = {"-c", "--continue", "-r", "--resume"}
 
@@ -4813,6 +4886,17 @@ For more help on a command:
         help="Shell type (default: bash)",
     )
     completion_parser.set_defaults(func=cmd_completion)
+    # web command
+    # =========================================================================
+    web_parser = subparsers.add_parser(
+        "web",
+        help="Start the web UI",
+        description="Launch the Hermes Agent web dashboard"
+    )
+    web_parser.add_argument("--port", type=int, default=9119, help="Port (default 9119)")
+    web_parser.add_argument("--host", default="127.0.0.1", help="Host (default 127.0.0.1)")
+    web_parser.add_argument("--no-open", action="store_true", help="Don't open browser automatically")
+    web_parser.set_defaults(func=cmd_web)
 
     # =========================================================================
     # Parse and execute

hermes_cli/plugins.py

@@ -152,6 +152,34 @@ class PluginContext:
         self._manager._plugin_tool_names.add(name)
         logger.debug("Plugin %s registered tool: %s", self.manifest.name, name)
 
+    # -- message injection --------------------------------------------------
+
+    def inject_message(self, content: str, role: str = "user") -> bool:
+        """Inject a message into the active conversation.
+
+        If the agent is idle (waiting for user input), this starts a new turn.
+        If the agent is running, this interrupts and injects the message.
+
+        This enables plugins (e.g. remote control viewers, messaging bridges)
+        to send messages into the conversation from external sources.
+
+        Returns True if the message was queued successfully.
+        """
+        cli = self._manager._cli_ref
+        if cli is None:
+            logger.warning("inject_message: no CLI reference (not available in gateway mode)")
+            return False
+
+        msg = content if role == "user" else f"[{role}] {content}"
+
+        if getattr(cli, "_agent_running", False):
+            # Agent is mid-turn — interrupt with the message
+            cli._interrupt_queue.put(msg)
+        else:
+            # Agent is idle — queue as next input
+            cli._pending_input.put(msg)
+        return True
+
     # -- hook registration --------------------------------------------------
 
     def register_hook(self, hook_name: str, callback: Callable) -> None:
@@ -184,6 +212,7 @@ class PluginManager:
         self._hooks: Dict[str, List[Callable]] = {}
         self._plugin_tool_names: Set[str] = set()
         self._discovered: bool = False
+        self._cli_ref = None  # Set by CLI after plugin discovery
 
     # -----------------------------------------------------------------------
     # Public

hermes_cli/web_server.py

@@ -0,0 +1,346 @@
+"""
+Hermes Agent — Web UI server.
+
+Provides a FastAPI backend serving the Vite/React frontend and REST API
+endpoints for managing configuration, environment variables, and sessions.
+
+Usage:
+    python -m hermes_cli.main web          # Start on http://127.0.0.1:9119
+    python -m hermes_cli.main web --port 8080
+"""
+
+import os
+import sys
+import time
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).parent.parent.resolve()
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+from hermes_cli import __version__, __release_date__
+from hermes_cli.config import (
+    DEFAULT_CONFIG,
+    OPTIONAL_ENV_VARS,
+    get_config_path,
+    get_env_path,
+    get_hermes_home,
+    load_config,
+    load_env,
+    save_config,
+    save_env_value,
+    delete_env_value,
+    check_config_version,
+    redact_key,
+)
+from gateway.status import get_running_pid, read_runtime_status
+
+try:
+    from fastapi import FastAPI, HTTPException
+    from fastapi.middleware.cors import CORSMiddleware
+    from fastapi.responses import FileResponse, JSONResponse
+    from fastapi.staticfiles import StaticFiles
+    from pydantic import BaseModel
+except ImportError:
+    raise SystemExit(
+        "Web UI requires fastapi and uvicorn.\n"
+        "Run 'hermes web' to auto-install, or: pip install hermes-agent[web]"
+    )
+
+WEB_DIST = Path(__file__).parent / "web_dist"
+
+app = FastAPI(title="Hermes Agent", version=__version__)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+CONFIG_SCHEMA = {
+    "model": {
+        "type": "string",
+        "description": "Default model for chat",
+        "category": "general",
+    },
+    "provider": {
+        "type": "select",
+        "description": "LLM provider",
+        "options": ["auto", "openrouter", "nous", "anthropic", "openai", "codex", "custom"],
+        "category": "general",
+    },
+    "system_prompt": {
+        "type": "text",
+        "description": "System prompt prepended to every conversation",
+        "category": "general",
+    },
+    "toolsets": {
+        "type": "list",
+        "description": "Enabled toolsets",
+        "category": "general",
+    },
+    "agent.max_turns": {
+        "type": "number",
+        "description": "Maximum agent turns per conversation",
+        "category": "agent",
+    },
+    "terminal.backend": {
+        "type": "select",
+        "description": "Terminal execution backend",
+        "options": ["local", "docker", "ssh", "modal", "daytona", "singularity"],
+        "category": "terminal",
+    },
+    "terminal.timeout": {
+        "type": "number",
+        "description": "Command timeout (seconds)",
+        "category": "terminal",
+    },
+    "terminal.cwd": {
+        "type": "string",
+        "description": "Working directory for terminal commands",
+        "category": "terminal",
+    },
+    "browser.inactivity_timeout": {
+        "type": "number",
+        "description": "Browser inactivity timeout (seconds)",
+        "category": "browser",
+    },
+    "compression.enabled": {
+        "type": "boolean",
+        "description": "Enable context compression",
+        "category": "compression",
+    },
+    "compression.threshold": {
+        "type": "number",
+        "description": "Context window usage threshold to trigger compression (0-1)",
+        "category": "compression",
+    },
+    "display.compact": {
+        "type": "boolean",
+        "description": "Compact display mode",
+        "category": "display",
+    },
+    "display.personality": {
+        "type": "select",
+        "description": "Agent personality",
+        "options": ["kawaii", "professional", "minimal", "hacker"],
+        "category": "display",
+    },
+    "display.show_reasoning": {
+        "type": "boolean",
+        "description": "Show model reasoning/thinking",
+        "category": "display",
+    },
+    "display.bell_on_complete": {
+        "type": "boolean",
+        "description": "Ring terminal bell when agent finishes",
+        "category": "display",
+    },
+    "tts.provider": {
+        "type": "select",
+        "description": "Text-to-speech provider",
+        "options": ["edge", "elevenlabs", "openai"],
+        "category": "tts",
+    },
+    "checkpoints.enabled": {
+        "type": "boolean",
+        "description": "Enable filesystem checkpoints before destructive ops",
+        "category": "checkpoints",
+    },
+    "checkpoints.max_snapshots": {
+        "type": "number",
+        "description": "Max checkpoint snapshots per directory",
+        "category": "checkpoints",
+    },
+}
+
+
+class ConfigUpdate(BaseModel):
+    config: dict
+
+
+class EnvVarUpdate(BaseModel):
+    key: str
+    value: str
+
+
+class EnvVarDelete(BaseModel):
+    key: str
+
+
+@app.get("/api/status")
+async def get_status():
+    current_ver, latest_ver = check_config_version()
+
+    gateway_pid = get_running_pid()
+    gateway_running = gateway_pid is not None
+
+    gateway_state = None
+    gateway_platforms: dict = {}
+    gateway_exit_reason = None
+    gateway_updated_at = None
+    runtime = read_runtime_status()
+    if runtime:
+        gateway_state = runtime.get("gateway_state")
+        gateway_platforms = runtime.get("platforms") or {}
+        gateway_exit_reason = runtime.get("exit_reason")
+        gateway_updated_at = runtime.get("updated_at")
+        if not gateway_running:
+            gateway_state = gateway_state if gateway_state in ("stopped", "startup_failed") else "stopped"
+
+    active_sessions = 0
+    try:
+        from hermes_state import SessionDB
+        db = SessionDB()
+        sessions = db.list_sessions_rich(limit=50)
+        now = time.time()
+        active_sessions = sum(
+            1 for s in sessions
+            if s.get("ended_at") is None
+            and (now - s.get("last_active", s.get("started_at", 0))) < 300
+        )
+    except Exception:
+        pass
+
+    return {
+        "version": __version__,
+        "release_date": __release_date__,
+        "hermes_home": str(get_hermes_home()),
+        "config_path": str(get_config_path()),
+        "env_path": str(get_env_path()),
+        "config_version": current_ver,
+        "latest_config_version": latest_ver,
+        "gateway_running": gateway_running,
+        "gateway_pid": gateway_pid,
+        "gateway_state": gateway_state,
+        "gateway_platforms": gateway_platforms,
+        "gateway_exit_reason": gateway_exit_reason,
+        "gateway_updated_at": gateway_updated_at,
+        "active_sessions": active_sessions,
+    }
+
+
+@app.get("/api/sessions")
+async def get_sessions():
+    try:
+        from hermes_state import SessionDB
+        db = SessionDB()
+        sessions = db.list_sessions_rich(limit=20)
+        now = time.time()
+        for s in sessions:
+            s["is_active"] = (
+                s.get("ended_at") is None
+                and (now - s.get("last_active", s.get("started_at", 0))) < 300
+            )
+        return sessions
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get("/api/config")
+async def get_config():
+    return load_config()
+
+
+@app.get("/api/config/defaults")
+async def get_defaults():
+    return DEFAULT_CONFIG
+
+
+@app.get("/api/config/schema")
+async def get_schema():
+    return CONFIG_SCHEMA
+
+
+@app.put("/api/config")
+async def update_config(body: ConfigUpdate):
+    try:
+        save_config(body.config)
+        return {"ok": True}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get("/api/env")
+async def get_env_vars():
+    env_on_disk = load_env()
+    result = {}
+    for var_name, info in OPTIONAL_ENV_VARS.items():
+        value = env_on_disk.get(var_name)
+        result[var_name] = {
+            "is_set": bool(value),
+            "redacted_value": redact_key(value) if value else None,
+            "description": info.get("description", ""),
+            "url": info.get("url"),
+            "category": info.get("category", ""),
+            "is_password": info.get("password", False),
+            "tools": info.get("tools", []),
+            "advanced": info.get("advanced", False),
+        }
+    return result
+
+
+@app.put("/api/env")
+async def set_env_var(body: EnvVarUpdate):
+    try:
+        save_env_value(body.key, body.value)
+        return {"ok": True, "key": body.key}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.delete("/api/env")
+async def remove_env_var(body: EnvVarDelete):
+    try:
+        removed = delete_env_value(body.key)
+        if not removed:
+            raise HTTPException(status_code=404, detail=f"{body.key} not found in .env")
+        return {"ok": True, "key": body.key}
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+def mount_spa(application: FastAPI):
+    """Mount the built SPA. Falls back to index.html for client-side routing."""
+    if not WEB_DIST.exists():
+        @application.get("/{full_path:path}")
+        async def no_frontend(full_path: str):
+            return JSONResponse(
+                {"error": "Frontend not built. Run: cd web && npm run build"},
+                status_code=404,
+            )
+        return
+
+    application.mount("/assets", StaticFiles(directory=WEB_DIST / "assets"), name="assets")
+
+    @application.get("/{full_path:path}")
+    async def serve_spa(full_path: str):
+        file_path = WEB_DIST / full_path
+        if full_path and file_path.exists() and file_path.is_file():
+            return FileResponse(file_path)
+        return FileResponse(WEB_DIST / "index.html")
+
+
+mount_spa(app)
+
+
+def start_server(host: str = "127.0.0.1", port: int = 9119, open_browser: bool = True):
+    """Start the web UI server."""
+    import uvicorn
+
+    if open_browser:
+        import threading
+        import webbrowser
+
+        def _open():
+            import time as _t
+            _t.sleep(1.0)
+            webbrowser.open(f"http://{host}:{port}")
+
+        threading.Thread(target=_open, daemon=True).start()
+
+    print(f"  Hermes Web UI → http://{host}:{port}")
+    uvicorn.run(app, host=host, port=port, log_level="warning")

model_tools.py

@@ -22,6 +22,8 @@ Public API (signatures preserved from the original 2,400-line version):
 
 import json
 import asyncio
+import os
+import time
 import logging
 import threading
 from typing import Dict, Any, List, Optional, Tuple
@@ -364,6 +366,32 @@ def get_tool_definitions(
 _AGENT_LOOP_TOOLS = {"todo", "memory", "session_search", "delegate_task"}
 _READ_SEARCH_TOOLS = {"read_file", "search_files"}
 
+# Auto-reload .env: check file mtime at most every 5 seconds so new API keys
+# take effect without manual /reload or session restart.
+_env_last_check: float = 0.0
+_env_last_mtime: float = 0.0
+_ENV_CHECK_INTERVAL = 5.0
+
+
+def _maybe_reload_env() -> None:
+    """Stat ~/.hermes/.env and reload into os.environ if it changed."""
+    global _env_last_check, _env_last_mtime
+    now = time.monotonic()
+    if now - _env_last_check < _ENV_CHECK_INTERVAL:
+        return
+    _env_last_check = now
+    try:
+        env_path = os.path.join(os.path.expanduser("~"), ".hermes", ".env")
+        mtime = os.path.getmtime(env_path)
+        if mtime != _env_last_mtime:
+            _env_last_mtime = mtime
+            from hermes_cli.config import reload_env
+            reload_env()
+    except FileNotFoundError:
+        pass
+    except Exception:
+        pass
+
 
 def handle_function_call(
     function_name: str,
@@ -390,6 +418,8 @@ def handle_function_call(
     Returns:
         Function result as a JSON string.
     """
+    _maybe_reload_env()
+
     # Notify the read-loop tracker when a non-read/search tool runs,
     # so the *consecutive* counter resets (reads after other work are fine).
     if function_name not in _READ_SEARCH_TOOLS:

optional-skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py

@@ -1297,7 +1297,11 @@ class Migrator:
 
         if self.execute:
             backup_path = self.maybe_backup(destination)
-            hermes_config["model"] = model_str
+            existing_model = hermes_config.get("model")
+            if isinstance(existing_model, dict):
+                existing_model["default"] = model_str
+            else:
+                hermes_config["model"] = {"default": model_str}
             dump_yaml_file(destination, hermes_config)
             self.record("model-config", source_path, destination, "migrated", backup=str(backup_path) if backup_path else "", model=model_str)
         else:

pyproject.toml

@@ -67,6 +67,7 @@ rl = [
   "wandb>=0.15.0,<1",
 ]
 yc-bench = ["yc-bench @ git+https://github.com/collinear-ai/yc-bench.git ; python_version >= '3.12'"]
+web = ["fastapi>=0.115.0", "uvicorn>=0.34.0"]
 all = [
   "hermes-agent[modal]",
   "hermes-agent[daytona]",
@@ -85,6 +86,7 @@ all = [
   "hermes-agent[acp]",
   "hermes-agent[voice]",
   "hermes-agent[dingtalk]",
+  "hermes-agent[web]",
   "hermes-agent[feishu]",
 ]
 
@@ -96,6 +98,9 @@ hermes-acp = "acp_adapter.entry:main"
 [tool.setuptools]
 py-modules = ["run_agent", "model_tools", "toolsets", "batch_runner", "trajectory_compressor", "toolset_distributions", "cli", "hermes_constants", "hermes_state", "hermes_time", "rl_cli", "utils"]
 
+[tool.setuptools.package-data]
+hermes_cli = ["web_dist/**/*"]
+
 [tool.setuptools.packages.find]
 include = ["agent", "tools", "tools.*", "hermes_cli", "gateway", "gateway.*", "cron", "honcho_integration", "acp_adapter"]
 

scripts/install.sh

@@ -920,6 +920,15 @@ install_node_deps() {
         }
         log_success "WhatsApp bridge dependencies installed"
     fi
+
+    # Build web UI frontend
+    if [ -f "$INSTALL_DIR/web/package.json" ]; then
+        log_info "Building web UI..."
+        cd "$INSTALL_DIR/web"
+        npm install --silent 2>/dev/null && npm run build 2>/dev/null && \
+            log_success "Web UI built" || \
+            log_warn "Web UI build failed (hermes web will not be available)"
+    fi
 }
 
 run_setup_wizard() {

scripts/whatsapp-bridge/bridge.js

@@ -55,6 +55,10 @@ const REPLY_PREFIX = process.env.WHATSAPP_REPLY_PREFIX === undefined
   : process.env.WHATSAPP_REPLY_PREFIX.replace(/\\n/g, '\n');
 
 function formatOutgoingMessage(message) {
+  // In bot mode, messages come from a different number so the prefix is
+  // redundant — the sender identity is already clear.  Only prepend in
+  // self-chat mode where bot and user share the same number.
+  if (WHATSAPP_MODE !== 'self-chat') return message;
   return REPLY_PREFIX ? `${REPLY_PREFIX}${message}` : message;
 }
 

tests/tools/test_credential_files.py

@@ -1,13 +1,17 @@
-"""Tests for credential file passthrough registry (tools/credential_files.py)."""
+"""Tests for credential file passthrough and skills directory mounting."""
 
+import json
 import os
 from pathlib import Path
+from unittest.mock import patch
 
 import pytest
 
 from tools.credential_files import (
     clear_credential_files,
     get_credential_file_mounts,
+    get_skills_directory_mount,
+    iter_skills_files,
     register_credential_file,
     register_credential_files,
     reset_config_cache,
@@ -15,8 +19,8 @@ from tools.credential_files import (
 
 
 @pytest.fixture(autouse=True)
-def _clean_registry():
-    """Reset registry between tests."""
+def _clean_state():
+    """Reset module state between tests."""
     clear_credential_files()
     reset_config_cache()
     yield
@@ -24,135 +28,172 @@ def _clean_registry():
     reset_config_cache()
 
 
-class TestRegisterCredentialFile:
-    def test_registers_existing_file(self, tmp_path, monkeypatch):
-        monkeypatch.setenv("HERMES_HOME", str(tmp_path))
-        (tmp_path / "token.json").write_text('{"token": "abc"}')
+class TestRegisterCredentialFiles:
+    def test_dict_with_path_key(self, tmp_path):
+        hermes_home = tmp_path / ".hermes"
+        hermes_home.mkdir()
+        (hermes_home / "token.json").write_text("{}")
 
-        result = register_credential_file("token.json")
+        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
+            missing = register_credential_files([{"path": "token.json"}])
 
-        assert result is True
+        assert missing == []
         mounts = get_credential_file_mounts()
         assert len(mounts) == 1
-        assert mounts[0]["host_path"] == str(tmp_path / "token.json")
+        assert mounts[0]["host_path"] == str(hermes_home / "token.json")
         assert mounts[0]["container_path"] == "/root/.hermes/token.json"
 
-    def test_skips_missing_file(self, tmp_path, monkeypatch):
-        monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+    def test_dict_with_name_key_fallback(self, tmp_path):
+        """Skills use 'name' instead of 'path' — both should work."""
+        hermes_home = tmp_path / ".hermes"
+        hermes_home.mkdir()
+        (hermes_home / "google_token.json").write_text("{}")
 
-        result = register_credential_file("nonexistent.json")
-
-        assert result is False
-        assert get_credential_file_mounts() == []
-
-    def test_custom_container_base(self, tmp_path, monkeypatch):
-        monkeypatch.setenv("HERMES_HOME", str(tmp_path))
-        (tmp_path / "cred.json").write_text("{}")
-
-        register_credential_file("cred.json", container_base="/home/user/.hermes")
+        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
+            missing = register_credential_files([
+                {"name": "google_token.json", "description": "OAuth token"},
+            ])
 
+        assert missing == []
         mounts = get_credential_file_mounts()
-        assert mounts[0]["container_path"] == "/home/user/.hermes/cred.json"
+        assert len(mounts) == 1
+        assert "google_token.json" in mounts[0]["container_path"]
 
-    def test_deduplicates_by_container_path(self, tmp_path, monkeypatch):
-        monkeypatch.setenv("HERMES_HOME", str(tmp_path))
-        (tmp_path / "token.json").write_text("{}")
+    def test_string_entry(self, tmp_path):
+        hermes_home = tmp_path / ".hermes"
+        hermes_home.mkdir()
+        (hermes_home / "secret.key").write_text("key")
 
-        register_credential_file("token.json")
-        register_credential_file("token.json")
+        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
+            missing = register_credential_files(["secret.key"])
 
+        assert missing == []
         mounts = get_credential_file_mounts()
         assert len(mounts) == 1
 
+    def test_missing_file_reported(self, tmp_path):
+        hermes_home = tmp_path / ".hermes"
+        hermes_home.mkdir()
 
-class TestRegisterCredentialFiles:
-    def test_string_entries(self, tmp_path, monkeypatch):
-        monkeypatch.setenv("HERMES_HOME", str(tmp_path))
-        (tmp_path / "a.json").write_text("{}")
-        (tmp_path / "b.json").write_text("{}")
+        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
+            missing = register_credential_files([
+                {"name": "does_not_exist.json"},
+            ])
 
-        missing = register_credential_files(["a.json", "b.json"])
-
-        assert missing == []
-        assert len(get_credential_file_mounts()) == 2
-
-    def test_dict_entries(self, tmp_path, monkeypatch):
-        monkeypatch.setenv("HERMES_HOME", str(tmp_path))
-        (tmp_path / "token.json").write_text("{}")
-
-        missing = register_credential_files([
-            {"path": "token.json", "description": "OAuth token"},
-        ])
-
-        assert missing == []
-        assert len(get_credential_file_mounts()) == 1
-
-    def test_returns_missing_files(self, tmp_path, monkeypatch):
-        monkeypatch.setenv("HERMES_HOME", str(tmp_path))
-        (tmp_path / "exists.json").write_text("{}")
-
-        missing = register_credential_files([
-            "exists.json",
-            "missing.json",
-            {"path": "also_missing.json"},
-        ])
-
-        assert missing == ["missing.json", "also_missing.json"]
-        assert len(get_credential_file_mounts()) == 1
-
-    def test_empty_list(self, tmp_path, monkeypatch):
-        monkeypatch.setenv("HERMES_HOME", str(tmp_path))
-        assert register_credential_files([]) == []
-
-
-class TestConfigCredentialFiles:
-    def test_loads_from_config(self, tmp_path, monkeypatch):
-        monkeypatch.setenv("HERMES_HOME", str(tmp_path))
-        (tmp_path / "oauth.json").write_text("{}")
-        (tmp_path / "config.yaml").write_text(
-            "terminal:\n  credential_files:\n    - oauth.json\n"
-        )
-
-        mounts = get_credential_file_mounts()
-
-        assert len(mounts) == 1
-        assert mounts[0]["host_path"] == str(tmp_path / "oauth.json")
-
-    def test_config_skips_missing_files(self, tmp_path, monkeypatch):
-        monkeypatch.setenv("HERMES_HOME", str(tmp_path))
-        (tmp_path / "config.yaml").write_text(
-            "terminal:\n  credential_files:\n    - nonexistent.json\n"
-        )
-
-        mounts = get_credential_file_mounts()
-        assert mounts == []
-
-    def test_combines_skill_and_config(self, tmp_path, monkeypatch):
-        monkeypatch.setenv("HERMES_HOME", str(tmp_path))
-        (tmp_path / "skill_token.json").write_text("{}")
-        (tmp_path / "config_token.json").write_text("{}")
-        (tmp_path / "config.yaml").write_text(
-            "terminal:\n  credential_files:\n    - config_token.json\n"
-        )
-
-        register_credential_file("skill_token.json")
-        mounts = get_credential_file_mounts()
-
-        assert len(mounts) == 2
-        paths = {m["container_path"] for m in mounts}
-        assert "/root/.hermes/skill_token.json" in paths
-        assert "/root/.hermes/config_token.json" in paths
-
-
-class TestGetMountsRechecksExistence:
-    def test_removed_file_excluded_from_mounts(self, tmp_path, monkeypatch):
-        monkeypatch.setenv("HERMES_HOME", str(tmp_path))
-        token = tmp_path / "token.json"
-        token.write_text("{}")
-
-        register_credential_file("token.json")
-        assert len(get_credential_file_mounts()) == 1
-
-        # Delete the file after registration
-        token.unlink()
+        assert "does_not_exist.json" in missing
         assert get_credential_file_mounts() == []
+
+    def test_path_takes_precedence_over_name(self, tmp_path):
+        """When both path and name are present, path wins."""
+        hermes_home = tmp_path / ".hermes"
+        hermes_home.mkdir()
+        (hermes_home / "real.json").write_text("{}")
+
+        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
+            missing = register_credential_files([
+                {"path": "real.json", "name": "wrong.json"},
+            ])
+
+        assert missing == []
+        mounts = get_credential_file_mounts()
+        assert "real.json" in mounts[0]["container_path"]
+
+
+class TestSkillsDirectoryMount:
+    def test_returns_mount_when_skills_dir_exists(self, tmp_path):
+        hermes_home = tmp_path / ".hermes"
+        skills_dir = hermes_home / "skills"
+        skills_dir.mkdir(parents=True)
+        (skills_dir / "test-skill").mkdir()
+        (skills_dir / "test-skill" / "SKILL.md").write_text("# test")
+
+        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
+            mount = get_skills_directory_mount()
+
+        assert mount is not None
+        assert mount["host_path"] == str(skills_dir)
+        assert mount["container_path"] == "/root/.hermes/skills"
+
+    def test_returns_none_when_no_skills_dir(self, tmp_path):
+        hermes_home = tmp_path / ".hermes"
+        hermes_home.mkdir()
+
+        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
+            mount = get_skills_directory_mount()
+
+        assert mount is None
+
+    def test_custom_container_base(self, tmp_path):
+        hermes_home = tmp_path / ".hermes"
+        (hermes_home / "skills").mkdir(parents=True)
+
+        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
+            mount = get_skills_directory_mount(container_base="/home/user/.hermes")
+
+        assert mount["container_path"] == "/home/user/.hermes/skills"
+
+    def test_symlinks_are_sanitized(self, tmp_path):
+        """Symlinks in skills dir should be excluded from the mount."""
+        hermes_home = tmp_path / ".hermes"
+        skills_dir = hermes_home / "skills"
+        skills_dir.mkdir(parents=True)
+        (skills_dir / "legit.md").write_text("# real skill")
+        # Create a symlink pointing outside the skills tree
+        secret = tmp_path / "secret.txt"
+        secret.write_text("TOP SECRET")
+        (skills_dir / "evil_link").symlink_to(secret)
+
+        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
+            mount = get_skills_directory_mount()
+
+        assert mount is not None
+        # The mount path should be a sanitized copy, not the original
+        safe_path = Path(mount["host_path"])
+        assert safe_path != skills_dir
+        # Legitimate file should be present
+        assert (safe_path / "legit.md").exists()
+        assert (safe_path / "legit.md").read_text() == "# real skill"
+        # Symlink should NOT be present
+        assert not (safe_path / "evil_link").exists()
+
+    def test_no_symlinks_returns_original_dir(self, tmp_path):
+        """When no symlinks exist, the original dir is returned (no copy)."""
+        hermes_home = tmp_path / ".hermes"
+        skills_dir = hermes_home / "skills"
+        skills_dir.mkdir(parents=True)
+        (skills_dir / "skill.md").write_text("ok")
+
+        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
+            mount = get_skills_directory_mount()
+
+        assert mount["host_path"] == str(skills_dir)
+
+
+class TestIterSkillsFiles:
+    def test_returns_files_skipping_symlinks(self, tmp_path):
+        hermes_home = tmp_path / ".hermes"
+        skills_dir = hermes_home / "skills"
+        (skills_dir / "cat" / "myskill").mkdir(parents=True)
+        (skills_dir / "cat" / "myskill" / "SKILL.md").write_text("# skill")
+        (skills_dir / "cat" / "myskill" / "scripts").mkdir()
+        (skills_dir / "cat" / "myskill" / "scripts" / "run.sh").write_text("#!/bin/bash")
+        # Add a symlink that should be filtered
+        secret = tmp_path / "secret"
+        secret.write_text("nope")
+        (skills_dir / "cat" / "myskill" / "evil").symlink_to(secret)
+
+        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
+            files = iter_skills_files()
+
+        paths = {f["container_path"] for f in files}
+        assert "/root/.hermes/skills/cat/myskill/SKILL.md" in paths
+        assert "/root/.hermes/skills/cat/myskill/scripts/run.sh" in paths
+        # Symlink should be excluded
+        assert not any("evil" in f["container_path"] for f in files)
+
+    def test_empty_when_no_skills_dir(self, tmp_path):
+        hermes_home = tmp_path / ".hermes"
+        hermes_home.mkdir()
+
+        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
+            assert iter_skills_files() == []

tests/tools/test_daytona_environment.py

@@ -61,6 +61,10 @@ def make_env(daytona_sdk, monkeypatch):
     """Factory that creates a DaytonaEnvironment with a mocked SDK."""
     # Prevent is_interrupted from interfering
     monkeypatch.setattr("tools.interrupt.is_interrupted", lambda: False)
+    # Prevent skills/credential sync from consuming mock exec calls
+    monkeypatch.setattr("tools.credential_files.get_credential_file_mounts", lambda: [])
+    monkeypatch.setattr("tools.credential_files.get_skills_directory_mount", lambda **kw: None)
+    monkeypatch.setattr("tools.credential_files.iter_skills_files", lambda **kw: [])
 
     def _factory(
         sandbox=None,

tools/credential_files.py

@@ -83,7 +83,7 @@ def register_credential_files(
         if isinstance(entry, str):
             rel_path = entry.strip()
         elif isinstance(entry, dict):
-            rel_path = (entry.get("path") or "").strip()
+            rel_path = (entry.get("path") or entry.get("name") or "").strip()
         else:
             continue
         if not rel_path:
@@ -152,6 +152,107 @@ def get_credential_file_mounts() -> List[Dict[str, str]]:
     ]
 
 
+def get_skills_directory_mount(
+    container_base: str = "/root/.hermes",
+) -> Dict[str, str] | None:
+    """Return mount info for a symlink-safe copy of the skills directory.
+
+    Skills may include ``scripts/``, ``templates/``, and ``references/``
+    subdirectories that the agent needs to execute inside remote sandboxes.
+
+    **Security:** Bind mounts follow symlinks, so a malicious symlink inside
+    the skills tree could expose arbitrary host files to the container.  When
+    symlinks are detected, this function creates a sanitized copy (regular
+    files only) in a temp directory and returns that path instead.  When no
+    symlinks are present (the common case), the original directory is returned
+    directly with zero overhead.
+
+    Returns a dict with ``host_path`` and ``container_path`` keys, or None.
+    """
+    hermes_home = _resolve_hermes_home()
+    skills_dir = hermes_home / "skills"
+    if not skills_dir.is_dir():
+        return None
+
+    host_path = _safe_skills_path(skills_dir)
+    return {
+        "host_path": host_path,
+        "container_path": f"{container_base.rstrip('/')}/skills",
+    }
+
+
+_safe_skills_tempdir: Path | None = None
+
+
+def _safe_skills_path(skills_dir: Path) -> str:
+    """Return *skills_dir* if symlink-free, else a sanitized temp copy."""
+    global _safe_skills_tempdir
+
+    symlinks = [p for p in skills_dir.rglob("*") if p.is_symlink()]
+    if not symlinks:
+        return str(skills_dir)
+
+    for link in symlinks:
+        logger.warning("credential_files: skipping symlink in skills dir: %s -> %s",
+                       link, os.readlink(link))
+
+    import atexit
+    import shutil
+    import tempfile
+
+    # Reuse the same temp dir across calls to avoid accumulation.
+    if _safe_skills_tempdir and _safe_skills_tempdir.is_dir():
+        shutil.rmtree(_safe_skills_tempdir, ignore_errors=True)
+
+    safe_dir = Path(tempfile.mkdtemp(prefix="hermes-skills-safe-"))
+    _safe_skills_tempdir = safe_dir
+
+    for item in skills_dir.rglob("*"):
+        if item.is_symlink():
+            continue
+        rel = item.relative_to(skills_dir)
+        target = safe_dir / rel
+        if item.is_dir():
+            target.mkdir(parents=True, exist_ok=True)
+        elif item.is_file():
+            target.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(str(item), str(target))
+
+    def _cleanup():
+        if safe_dir.is_dir():
+            shutil.rmtree(safe_dir, ignore_errors=True)
+
+    atexit.register(_cleanup)
+    logger.info("credential_files: created symlink-safe skills copy at %s", safe_dir)
+    return str(safe_dir)
+
+
+def iter_skills_files(
+    container_base: str = "/root/.hermes",
+) -> List[Dict[str, str]]:
+    """Yield individual (host_path, container_path) entries for skills files.
+
+    Skips symlinks entirely.  Preferred for backends that upload files
+    individually (Daytona, Modal) rather than mounting a directory.
+    """
+    hermes_home = _resolve_hermes_home()
+    skills_dir = hermes_home / "skills"
+    if not skills_dir.is_dir():
+        return []
+
+    container_root = f"{container_base.rstrip('/')}/skills"
+    result: List[Dict[str, str]] = []
+    for item in skills_dir.rglob("*"):
+        if item.is_symlink() or not item.is_file():
+            continue
+        rel = item.relative_to(skills_dir)
+        result.append({
+            "host_path": str(item),
+            "container_path": f"{container_root}/{rel}",
+        })
+    return result
+
+
 def clear_credential_files() -> None:
     """Reset the skill-scoped registry (e.g. on session reset)."""
     _registered_files.clear()

tools/environments/daytona.py

@@ -113,15 +113,61 @@ class DaytonaEnvironment(BaseEnvironment):
             logger.info("Daytona: created sandbox %s for task %s",
                         self._sandbox.id, task_id)
 
-        # Resolve cwd: detect actual home dir inside the sandbox
-        if self._requested_cwd in ("~", "/home/daytona"):
-            try:
-                home = self._sandbox.process.exec("echo $HOME").result.strip()
-                if home:
+        # Detect remote home dir first so mounts go to the right place.
+        self._remote_home = "/root"
+        try:
+            home = self._sandbox.process.exec("echo $HOME").result.strip()
+            if home:
+                self._remote_home = home
+                if self._requested_cwd in ("~", "/home/daytona"):
                     self.cwd = home
-            except Exception:
-                pass  # leave cwd as-is; sandbox will use its own default
-            logger.info("Daytona: resolved cwd to %s", self.cwd)
+        except Exception:
+            pass
+        logger.info("Daytona: resolved home to %s, cwd to %s", self._remote_home, self.cwd)
+
+        # Track synced files to avoid redundant uploads.
+        # Key: remote_path, Value: (mtime, size)
+        self._synced_files: Dict[str, tuple] = {}
+
+        # Upload credential files and skills directory into the sandbox.
+        self._sync_skills_and_credentials()
+
+    def _upload_if_changed(self, host_path: str, remote_path: str) -> bool:
+        """Upload a file if its mtime/size changed since last sync."""
+        hp = Path(host_path)
+        try:
+            stat = hp.stat()
+            file_key = (stat.st_mtime, stat.st_size)
+        except OSError:
+            return False
+        if self._synced_files.get(remote_path) == file_key:
+            return False
+        try:
+            parent = str(Path(remote_path).parent)
+            self._sandbox.process.exec(f"mkdir -p {parent}")
+            self._sandbox.fs.upload_file(host_path, remote_path)
+            self._synced_files[remote_path] = file_key
+            return True
+        except Exception as e:
+            logger.debug("Daytona: upload failed %s: %s", host_path, e)
+            return False
+
+    def _sync_skills_and_credentials(self) -> None:
+        """Upload changed credential files and skill files into the sandbox."""
+        container_base = f"{self._remote_home}/.hermes"
+        try:
+            from tools.credential_files import get_credential_file_mounts, iter_skills_files
+
+            for mount_entry in get_credential_file_mounts():
+                remote_path = mount_entry["container_path"].replace("/root/.hermes", container_base, 1)
+                if self._upload_if_changed(mount_entry["host_path"], remote_path):
+                    logger.debug("Daytona: synced credential %s", remote_path)
+
+            for entry in iter_skills_files(container_base=container_base):
+                if self._upload_if_changed(entry["host_path"], entry["container_path"]):
+                    logger.debug("Daytona: synced skill %s", entry["container_path"])
+        except Exception as e:
+            logger.debug("Daytona: could not sync skills/credentials: %s", e)
 
     def _ensure_sandbox_ready(self):
         """Restart sandbox if it was stopped (e.g., by a previous interrupt)."""
@@ -191,6 +237,9 @@ class DaytonaEnvironment(BaseEnvironment):
                 stdin_data: Optional[str] = None) -> dict:
         with self._lock:
             self._ensure_sandbox_ready()
+        # Incremental sync before each command so mid-session credential
+        # refreshes and skill updates are picked up.
+        self._sync_skills_and_credentials()
 
         if stdin_data is not None:
             marker = f"HERMES_EOF_{uuid.uuid4().hex[:8]}"

tools/environments/docker.py

@@ -315,7 +315,7 @@ class DockerEnvironment(BaseEnvironment):
         # Mount credential files (OAuth tokens, etc.) declared by skills.
         # Read-only so the container can authenticate but not modify host creds.
         try:
-            from tools.credential_files import get_credential_file_mounts
+            from tools.credential_files import get_credential_file_mounts, get_skills_directory_mount
 
             for mount_entry in get_credential_file_mounts():
                 volume_args.extend([
@@ -327,6 +327,20 @@ class DockerEnvironment(BaseEnvironment):
                     mount_entry["host_path"],
                     mount_entry["container_path"],
                 )
+
+            # Mount the skills directory so skill scripts/templates are
+            # available inside the container at the same relative path.
+            skills_mount = get_skills_directory_mount()
+            if skills_mount:
+                volume_args.extend([
+                    "-v",
+                    f"{skills_mount['host_path']}:{skills_mount['container_path']}:ro",
+                ])
+                logger.info(
+                    "Docker: mounting skills dir %s -> %s",
+                    skills_mount["host_path"],
+                    skills_mount["container_path"],
+                )
         except Exception as e:
             logger.debug("Docker: could not load credential file mounts: %s", e)
 

tools/environments/modal.py

@@ -142,7 +142,7 @@ class ModalEnvironment(BaseEnvironment):
         # external services but can't modify the host's credentials.
         cred_mounts = []
         try:
-            from tools.credential_files import get_credential_file_mounts
+            from tools.credential_files import get_credential_file_mounts, iter_skills_files
 
             for mount_entry in get_credential_file_mounts():
                 cred_mounts.append(
@@ -156,6 +156,18 @@ class ModalEnvironment(BaseEnvironment):
                     mount_entry["host_path"],
                     mount_entry["container_path"],
                 )
+
+            # Mount individual skill files (symlinks filtered out).
+            skills_files = iter_skills_files()
+            for entry in skills_files:
+                cred_mounts.append(
+                    _modal.Mount.from_local_file(
+                        entry["host_path"],
+                        remote_path=entry["container_path"],
+                    )
+                )
+            if skills_files:
+                logger.info("Modal: mounting %d skill files", len(skills_files))
         except Exception as e:
             logger.debug("Modal: could not load credential file mounts: %s", e)
 
@@ -184,72 +196,69 @@ class ModalEnvironment(BaseEnvironment):
         self._app, self._sandbox = self._worker.run_coroutine(
             _create_sandbox(), timeout=300
         )
-        # Track synced credential files to avoid redundant pushes.
+        # Track synced files to avoid redundant pushes.
         # Key: container_path, Value: (mtime, size) of last synced version.
-        self._synced_creds: Dict[str, tuple] = {}
+        self._synced_files: Dict[str, tuple] = {}
         logger.info("Modal: sandbox created (task=%s)", self._task_id)
 
-    def _sync_credential_files(self) -> None:
-        """Push credential files into the running sandbox.
+    def _push_file_to_sandbox(self, host_path: str, container_path: str) -> bool:
+        """Push a single file into the sandbox if changed. Returns True if synced."""
+        hp = Path(host_path)
+        try:
+            stat = hp.stat()
+            file_key = (stat.st_mtime, stat.st_size)
+        except OSError:
+            return False
 
-        Mounts are set at sandbox creation, but credentials may be created
-        later (e.g. OAuth setup mid-session).  This writes the current file
-        content into the sandbox via exec(), so new/updated credentials are
-        available without recreating the sandbox.
+        if self._synced_files.get(container_path) == file_key:
+            return False
+
+        try:
+            content = hp.read_bytes()
+        except Exception:
+            return False
+
+        import base64
+        b64 = base64.b64encode(content).decode("ascii")
+        container_dir = str(Path(container_path).parent)
+        cmd = (
+            f"mkdir -p {shlex.quote(container_dir)} && "
+            f"echo {shlex.quote(b64)} | base64 -d > {shlex.quote(container_path)}"
+        )
+
+        async def _write():
+            proc = await self._sandbox.exec.aio("bash", "-c", cmd)
+            await proc.wait.aio()
+
+        self._worker.run_coroutine(_write(), timeout=15)
+        self._synced_files[container_path] = file_key
+        return True
+
+    def _sync_files(self) -> None:
+        """Push credential files and skill files into the running sandbox.
+
+        Runs before each command. Uses mtime+size caching so only changed
+        files are pushed (~13μs overhead in the no-op case).
         """
         try:
-            from tools.credential_files import get_credential_file_mounts
+            from tools.credential_files import get_credential_file_mounts, iter_skills_files
 
-            mounts = get_credential_file_mounts()
-            if not mounts:
-                return
+            for entry in get_credential_file_mounts():
+                if self._push_file_to_sandbox(entry["host_path"], entry["container_path"]):
+                    logger.debug("Modal: synced credential %s", entry["container_path"])
 
-            for entry in mounts:
-                host_path = entry["host_path"]
-                container_path = entry["container_path"]
-                hp = Path(host_path)
-                try:
-                    stat = hp.stat()
-                    file_key = (stat.st_mtime, stat.st_size)
-                except OSError:
-                    continue
-
-                # Skip if already synced with same mtime+size
-                if self._synced_creds.get(container_path) == file_key:
-                    continue
-
-                try:
-                    content = hp.read_text(encoding="utf-8")
-                except Exception:
-                    continue
-
-                # Write via base64 to avoid shell escaping issues with JSON
-                import base64
-                b64 = base64.b64encode(content.encode("utf-8")).decode("ascii")
-                container_dir = str(Path(container_path).parent)
-                cmd = (
-                    f"mkdir -p {shlex.quote(container_dir)} && "
-                    f"echo {shlex.quote(b64)} | base64 -d > {shlex.quote(container_path)}"
-                )
-
-                _cp = container_path  # capture for closure
-
-                async def _write():
-                    proc = await self._sandbox.exec.aio("bash", "-c", cmd)
-                    await proc.wait.aio()
-
-                self._worker.run_coroutine(_write(), timeout=15)
-                self._synced_creds[container_path] = file_key
-                logger.debug("Modal: synced credential %s -> %s", host_path, container_path)
+            for entry in iter_skills_files():
+                if self._push_file_to_sandbox(entry["host_path"], entry["container_path"]):
+                    logger.debug("Modal: synced skill file %s", entry["container_path"])
         except Exception as e:
-            logger.debug("Modal: credential file sync failed: %s", e)
+            logger.debug("Modal: file sync failed: %s", e)
 
     def execute(self, command: str, cwd: str = "", *,
                 timeout: int | None = None,
                 stdin_data: str | None = None) -> dict:
         # Sync credential files before each command so mid-session
         # OAuth setups are picked up without requiring a restart.
-        self._sync_credential_files()
+        self._sync_files()
 
         if stdin_data is not None:
             marker = f"HERMES_EOF_{uuid.uuid4().hex[:8]}"

tools/environments/singularity.py

@@ -254,6 +254,28 @@ class SingularityEnvironment(BaseEnvironment):
         else:
             cmd.append("--writable-tmpfs")
 
+        # Mount credential files and skills directory (read-only).
+        try:
+            from tools.credential_files import get_credential_file_mounts, get_skills_directory_mount
+
+            for mount_entry in get_credential_file_mounts():
+                cmd.extend(["--bind", f"{mount_entry['host_path']}:{mount_entry['container_path']}:ro"])
+                logger.info(
+                    "Singularity: binding credential %s -> %s",
+                    mount_entry["host_path"],
+                    mount_entry["container_path"],
+                )
+            skills_mount = get_skills_directory_mount()
+            if skills_mount:
+                cmd.extend(["--bind", f"{skills_mount['host_path']}:{skills_mount['container_path']}:ro"])
+                logger.info(
+                    "Singularity: binding skills dir %s -> %s",
+                    skills_mount["host_path"],
+                    skills_mount["container_path"],
+                )
+        except Exception as e:
+            logger.debug("Singularity: could not load credential/skills mounts: %s", e)
+
         # Resource limits (cgroup-based, may require root or appropriate config)
         if self._memory > 0:
             cmd.extend(["--memory", f"{self._memory}M"])

tools/environments/ssh.py

@@ -55,6 +55,8 @@ class SSHEnvironment(PersistentShellMixin, BaseEnvironment):
         self.control_socket = self.control_dir / f"{user}@{host}:{port}.sock"
         _ensure_ssh_available()
         self._establish_connection()
+        self._remote_home = self._detect_remote_home()
+        self._sync_skills_and_credentials()
 
         if self.persistent:
             self._init_persistent_shell()
@@ -87,6 +89,79 @@ class SSHEnvironment(PersistentShellMixin, BaseEnvironment):
         except subprocess.TimeoutExpired:
             raise RuntimeError(f"SSH connection to {self.user}@{self.host} timed out")
 
+    def _detect_remote_home(self) -> str:
+        """Detect the remote user's home directory."""
+        try:
+            cmd = self._build_ssh_command()
+            cmd.append("echo $HOME")
+            result = subprocess.run(cmd, capture_output=True, text=True, timeout=10)
+            home = result.stdout.strip()
+            if home and result.returncode == 0:
+                logger.debug("SSH: remote home = %s", home)
+                return home
+        except Exception:
+            pass
+        # Fallback: guess from username
+        if self.user == "root":
+            return "/root"
+        return f"/home/{self.user}"
+
+    def _sync_skills_and_credentials(self) -> None:
+        """Rsync skills directory and credential files to the remote host."""
+        try:
+            container_base = f"{self._remote_home}/.hermes"
+            from tools.credential_files import get_credential_file_mounts, get_skills_directory_mount
+
+            rsync_base = ["rsync", "-az", "--timeout=30", "--safe-links"]
+            ssh_opts = f"ssh -o ControlPath={self.control_socket} -o ControlMaster=auto"
+            if self.port != 22:
+                ssh_opts += f" -p {self.port}"
+            if self.key_path:
+                ssh_opts += f" -i {self.key_path}"
+            rsync_base.extend(["-e", ssh_opts])
+            dest_prefix = f"{self.user}@{self.host}"
+
+            # Sync individual credential files (remap /root/.hermes to detected home)
+            for mount_entry in get_credential_file_mounts():
+                remote_path = mount_entry["container_path"].replace("/root/.hermes", container_base, 1)
+                parent_dir = str(Path(remote_path).parent)
+                mkdir_cmd = self._build_ssh_command()
+                mkdir_cmd.append(f"mkdir -p {parent_dir}")
+                subprocess.run(mkdir_cmd, capture_output=True, text=True, timeout=10)
+                cmd = rsync_base + [mount_entry["host_path"], f"{dest_prefix}:{remote_path}"]
+                result = subprocess.run(cmd, capture_output=True, text=True, timeout=30)
+                if result.returncode == 0:
+                    logger.info("SSH: synced credential %s -> %s", mount_entry["host_path"], remote_path)
+                else:
+                    logger.debug("SSH: rsync credential failed: %s", result.stderr.strip())
+
+            # Sync skills directory (remap to detected home)
+            skills_mount = get_skills_directory_mount(container_base=container_base)
+            if skills_mount:
+                remote_path = skills_mount["container_path"]
+                mkdir_cmd = self._build_ssh_command()
+                mkdir_cmd.append(f"mkdir -p {remote_path}")
+                subprocess.run(mkdir_cmd, capture_output=True, text=True, timeout=10)
+                cmd = rsync_base + [
+                    skills_mount["host_path"].rstrip("/") + "/",
+                    f"{dest_prefix}:{remote_path}/",
+                ]
+                result = subprocess.run(cmd, capture_output=True, text=True, timeout=60)
+                if result.returncode == 0:
+                    logger.info("SSH: synced skills dir %s -> %s", skills_mount["host_path"], remote_path)
+                else:
+                    logger.debug("SSH: rsync skills dir failed: %s", result.stderr.strip())
+        except Exception as e:
+            logger.debug("SSH: could not sync skills/credentials: %s", e)
+
+    def execute(self, command: str, cwd: str = "", *,
+                timeout: int | None = None,
+                stdin_data: str | None = None) -> dict:
+        # Incremental sync before each command so mid-session credential
+        # refreshes and skill updates are picked up.
+        self._sync_skills_and_credentials()
+        return super().execute(command, cwd, timeout=timeout, stdin_data=stdin_data)
+
     _poll_interval_start: float = 0.15  # SSH: higher initial interval (150ms) for network latency
 
     @property

tools/vision_tools.py

@@ -45,6 +45,28 @@ logger = logging.getLogger(__name__)
 
 _debug = DebugSession("vision_tools", env_var="VISION_TOOLS_DEBUG")
 
+# Configurable HTTP download timeout for _download_image().
+# Separate from auxiliary.vision.timeout which governs the LLM API call.
+# Resolution: config.yaml auxiliary.vision.download_timeout → env var → 30s default.
+def _resolve_download_timeout() -> float:
+    env_val = os.getenv("HERMES_VISION_DOWNLOAD_TIMEOUT", "").strip()
+    if env_val:
+        try:
+            return float(env_val)
+        except ValueError:
+            pass
+    try:
+        from hermes_cli.config import load_config
+        cfg = load_config()
+        val = cfg.get("auxiliary", {}).get("vision", {}).get("download_timeout")
+        if val is not None:
+            return float(val)
+    except Exception:
+        pass
+    return 30.0
+
+_VISION_DOWNLOAD_TIMEOUT = _resolve_download_timeout()
+
 
 def _validate_image_url(url: str) -> bool:
     """
@@ -146,7 +168,7 @@ async def _download_image(image_url: str, destination: Path, max_retries: int =
             # Enable follow_redirects to handle image CDNs that redirect (e.g., Imgur, Picsum)
             # SSRF: event_hooks validates each redirect target against private IP ranges
             async with httpx.AsyncClient(
-                timeout=30.0,
+                timeout=_VISION_DOWNLOAD_TIMEOUT,
                 follow_redirects=True,
                 event_hooks={"response": [_ssrf_redirect_guard]},
             ) as client:
@@ -183,6 +205,10 @@ async def _download_image(image_url: str, destination: Path, max_retries: int =
                     exc_info=True,
                 )
     
+    if last_error is None:
+        raise RuntimeError(
+            f"_download_image exited retry loop without attempting (max_retries={max_retries})"
+        )
     raise last_error
 
 

web/README.md

@@ -0,0 +1,48 @@
+# Hermes Agent — Web UI
+
+Browser-based dashboard for managing Hermes Agent configuration, API keys, and monitoring active sessions.
+
+## Stack
+
+- **Vite** + **React 19** + **TypeScript**
+- **Tailwind CSS v4** with custom dark theme
+- **shadcn/ui**-style components (hand-rolled, no CLI dependency)
+
+## Development
+
+```bash
+# Start the backend API server
+cd ../
+python -m hermes_cli.main web --no-open
+
+# In another terminal, start the Vite dev server (with HMR + API proxy)
+cd web/
+npm run dev
+```
+
+The Vite dev server proxies `/api` requests to `http://127.0.0.1:9119` (the FastAPI backend).
+
+## Build
+
+```bash
+npm run build
+```
+
+This outputs to `../hermes_cli/web_dist/`, which the FastAPI server serves as a static SPA. The built assets are included in the Python package via `pyproject.toml` package-data.
+
+## Structure
+
+```
+src/
+├── components/ui/   # Reusable UI primitives (Card, Badge, Button, Input, etc.)
+├── lib/
+│   ├── api.ts       # API client — typed fetch wrappers for all backend endpoints
+│   └── utils.ts     # cn() helper for Tailwind class merging
+├── pages/
+│   ├── StatusPage   # Agent status, active/recent sessions
+│   ├── ConfigPage   # Dynamic config editor (reads schema from backend)
+│   └── EnvPage      # API key management with save/clear
+├── App.tsx          # Main layout and navigation
+├── main.tsx         # React entry point
+└── index.css        # Tailwind imports and theme variables
+```

web/eslint.config.js

@@ -0,0 +1,23 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+import { defineConfig, globalIgnores } from 'eslint/config'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+  },
+])

web/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.ico" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Hermes Agent</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

web/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "web",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "lint": "eslint .",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@tailwindcss/vite": "^4.2.1",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^0.577.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "react-router-dom": "^7.13.1",
+    "tailwind-merge": "^3.5.0",
+    "tailwindcss": "^4.2.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.4",
+    "@types/node": "^24.12.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.2.0",
+    "eslint": "^9.39.4",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.5.2",
+    "globals": "^17.4.0",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.56.1",
+    "vite": "^7.3.1"
+  }
+}

web/src/App.tsx

@@ -0,0 +1,51 @@
+import { useState } from "react";
+import { Activity, KeyRound, Settings } from "lucide-react";
+import StatusPage from "@/pages/StatusPage";
+import ConfigPage from "@/pages/ConfigPage";
+import EnvPage from "@/pages/EnvPage";
+
+const NAV_ITEMS = [
+  { id: "status", label: "Status", icon: Activity },
+  { id: "config", label: "Config", icon: Settings },
+  { id: "env", label: "API Keys", icon: KeyRound },
+] as const;
+
+type PageId = (typeof NAV_ITEMS)[number]["id"];
+
+export default function App() {
+  const [page, setPage] = useState<PageId>("status");
+
+  return (
+    <div className="flex min-h-screen flex-col bg-background text-foreground">
+      <header className="sticky top-0 z-40 border-b border-border bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/60">
+        <div className="mx-auto flex h-14 max-w-5xl items-center gap-6 px-6">
+          <span className="text-lg font-bold tracking-tight">Hermes Agent</span>
+
+          <nav className="flex items-center gap-1">
+            {NAV_ITEMS.map(({ id, label, icon: Icon }) => (
+              <button
+                key={id}
+                type="button"
+                onClick={() => setPage(id)}
+                className={`inline-flex items-center gap-1.5 rounded-md px-3 py-1.5 text-sm font-medium transition-colors cursor-pointer ${
+                  page === id
+                    ? "bg-secondary text-secondary-foreground"
+                    : "text-muted-foreground hover:bg-secondary/50 hover:text-foreground"
+                }`}
+              >
+                <Icon className="h-4 w-4" />
+                {label}
+              </button>
+            ))}
+          </nav>
+        </div>
+      </header>
+
+      <main className="mx-auto w-full max-w-5xl flex-1 px-6 py-8">
+        {page === "status" && <StatusPage />}
+        {page === "config" && <ConfigPage />}
+        {page === "env" && <EnvPage />}
+      </main>
+    </div>
+  );
+}

web/src/components/AutoField.tsx

@@ -0,0 +1,127 @@
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { Select } from "@/components/ui/select";
+import { Switch } from "@/components/ui/switch";
+
+export function AutoField({
+  schemaKey,
+  schema,
+  value,
+  onChange,
+}: AutoFieldProps) {
+  const label = schemaKey.split(".").pop() ?? schemaKey;
+  const description = String(schema.description ?? "");
+
+  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+    const obj = value as Record<string, unknown>;
+    return (
+      <div className="grid gap-3 rounded-lg border border-border p-3">
+        <Label className="text-xs font-medium">{label}</Label>
+        {description && <p className="text-xs text-muted-foreground">{description}</p>}
+        {Object.entries(obj).map(([subKey, subVal]) => (
+          <div key={subKey} className="grid gap-1">
+            <Label className="text-xs text-muted-foreground">{subKey}</Label>
+            <Input
+              value={String(subVal ?? "")}
+              onChange={(e) => onChange({ ...obj, [subKey]: e.target.value })}
+              className="text-xs"
+            />
+          </div>
+        ))}
+      </div>
+    );
+  }
+
+  if (schema.type === "boolean") {
+    return (
+      <div className="flex items-center justify-between gap-4">
+        <div className="flex flex-col gap-0.5">
+          <Label className="text-sm">{label}</Label>
+          {description && <p className="text-xs text-muted-foreground">{description}</p>}
+        </div>
+        <Switch checked={!!value} onCheckedChange={onChange} />
+      </div>
+    );
+  }
+
+  if (schema.type === "select") {
+    const options = (schema.options as string[]) ?? [];
+    return (
+      <div className="grid gap-2">
+        <Label className="text-sm">{label}</Label>
+        {description && <p className="text-xs text-muted-foreground">{description}</p>}
+        <Select value={String(value ?? "")} onChange={(e) => onChange(e.target.value)}>
+          {options.map((opt) => (
+            <option key={opt} value={opt}>
+              {opt}
+            </option>
+          ))}
+        </Select>
+      </div>
+    );
+  }
+
+  if (schema.type === "number") {
+    return (
+      <div className="grid gap-2">
+        <Label className="text-sm">{label}</Label>
+        {description && <p className="text-xs text-muted-foreground">{description}</p>}
+        <Input
+          type="number"
+          value={String(value ?? "")}
+          onChange={(e) => onChange(Number(e.target.value))}
+        />
+      </div>
+    );
+  }
+
+  if (schema.type === "text") {
+    return (
+      <div className="grid gap-2">
+        <Label className="text-sm">{label}</Label>
+        {description && <p className="text-xs text-muted-foreground">{description}</p>}
+        <textarea
+          className="flex min-h-[80px] w-full rounded-md border border-input bg-transparent px-3 py-2 text-sm shadow-sm placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+          value={String(value ?? "")}
+          onChange={(e) => onChange(e.target.value)}
+        />
+      </div>
+    );
+  }
+
+  if (schema.type === "list") {
+    return (
+      <div className="grid gap-2">
+        <Label className="text-sm">{label}</Label>
+        {description && <p className="text-xs text-muted-foreground">{description}</p>}
+        <Input
+          value={Array.isArray(value) ? value.join(", ") : String(value ?? "")}
+          onChange={(e) =>
+            onChange(
+              e.target.value
+                .split(",")
+                .map((s) => s.trim())
+                .filter(Boolean),
+            )
+          }
+          placeholder="comma-separated values"
+        />
+      </div>
+    );
+  }
+
+  return (
+    <div className="grid gap-2">
+      <Label className="text-sm">{label}</Label>
+      {description && <p className="text-xs text-muted-foreground">{description}</p>}
+      <Input value={String(value ?? "")} onChange={(e) => onChange(e.target.value)} />
+    </div>
+  );
+}
+
+interface AutoFieldProps {
+  schemaKey: string;
+  schema: Record<string, unknown>;
+  value: unknown;
+  onChange: (v: unknown) => void;
+}

web/src/components/Toast.tsx

@@ -0,0 +1,15 @@
+export function Toast({ toast }: { toast: { message: string; type: "success" | "error" } | null }) {
+  if (!toast) return null;
+
+  return (
+    <div
+      className={`fixed top-4 right-4 z-50 rounded-lg px-4 py-2 text-sm font-medium shadow-lg ${
+        toast.type === "success"
+          ? "bg-success/20 text-success border border-success/30"
+          : "bg-destructive/20 text-destructive border border-destructive/30"
+      }`}
+    >
+      {toast.message}
+    </div>
+  );
+}

web/src/components/ui/badge.tsx

@@ -0,0 +1,29 @@
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "@/lib/utils";
+
+const badgeVariants = cva(
+  "inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-semibold transition-colors",
+  {
+    variants: {
+      variant: {
+        default: "border-transparent bg-primary text-primary-foreground",
+        secondary: "border-transparent bg-secondary text-secondary-foreground",
+        destructive: "border-transparent bg-destructive text-destructive-foreground",
+        outline: "text-foreground",
+        success: "border-transparent bg-success/20 text-success",
+        warning: "border-transparent bg-warning/20 text-warning",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  },
+);
+
+export function Badge({
+  className,
+  variant,
+  ...props
+}: React.HTMLAttributes<HTMLDivElement> & VariantProps<typeof badgeVariants>) {
+  return <div className={cn(badgeVariants({ variant }), className)} {...props} />;
+}

web/src/components/ui/button.tsx

@@ -0,0 +1,38 @@
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "@/lib/utils";
+
+const buttonVariants = cva(
+  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-colors cursor-pointer"
+  + " disabled:pointer-events-none disabled:opacity-50",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground hover:bg-primary/90",
+        destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
+        outline: "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
+        secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80",
+        ghost: "hover:bg-accent hover:text-accent-foreground",
+        link: "text-primary underline-offset-4 hover:underline",
+      },
+      size: {
+        default: "h-9 px-4 py-2",
+        sm: "h-8 rounded-md px-3 text-xs",
+        lg: "h-10 rounded-md px-8",
+        icon: "h-9 w-9",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  },
+);
+
+export function Button({
+  className,
+  variant,
+  size,
+  ...props
+}: React.ButtonHTMLAttributes<HTMLButtonElement> & VariantProps<typeof buttonVariants>) {
+  return <button className={cn(buttonVariants({ variant, size }), className)} {...props} />;
+}

web/src/components/ui/card.tsx

@@ -0,0 +1,29 @@
+import { cn } from "@/lib/utils";
+
+export function Card({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      className={cn(
+        "rounded-xl border border-border bg-card text-card-foreground shadow-sm",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export function CardHeader({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+  return <div className={cn("flex flex-col gap-1.5 p-6", className)} {...props} />;
+}
+
+export function CardTitle({ className, ...props }: React.HTMLAttributes<HTMLHeadingElement>) {
+  return <h3 className={cn("font-semibold leading-none tracking-tight", className)} {...props} />;
+}
+
+export function CardDescription({ className, ...props }: React.HTMLAttributes<HTMLParagraphElement>) {
+  return <p className={cn("text-sm text-muted-foreground", className)} {...props} />;
+}
+
+export function CardContent({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+  return <div className={cn("p-6 pt-0", className)} {...props} />;
+}

web/src/components/ui/input.tsx

@@ -0,0 +1,16 @@
+import { cn } from "@/lib/utils";
+
+export function Input({ className, ...props }: React.InputHTMLAttributes<HTMLInputElement>) {
+  return (
+    <input
+      className={cn(
+        "flex h-9 w-full rounded-md border border-input bg-transparent px-3 py-1 text-sm shadow-sm transition-colors",
+        "placeholder:text-muted-foreground",
+        "focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring",
+        "disabled:cursor-not-allowed disabled:opacity-50",
+        className,
+      )}
+      {...props}
+    />
+  );
+}

web/src/components/ui/label.tsx

@@ -0,0 +1,13 @@
+import { cn } from "@/lib/utils";
+
+export function Label({ className, ...props }: React.LabelHTMLAttributes<HTMLLabelElement>) {
+  return (
+    <label
+      className={cn(
+        "text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70",
+        className,
+      )}
+      {...props}
+    />
+  );
+}

web/src/components/ui/select.tsx

@@ -0,0 +1,15 @@
+import { cn } from "@/lib/utils";
+
+export function Select({ className, ...props }: React.SelectHTMLAttributes<HTMLSelectElement>) {
+  return (
+    <select
+      className={cn(
+        "flex h-9 w-full rounded-md border border-input bg-transparent px-3 py-1 text-sm shadow-sm",
+        "focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring",
+        "disabled:cursor-not-allowed disabled:opacity-50",
+        className,
+      )}
+      {...props}
+    />
+  );
+}

web/src/components/ui/separator.tsx

@@ -0,0 +1,19 @@
+import { cn } from "@/lib/utils";
+
+export function Separator({
+  className,
+  orientation = "horizontal",
+  ...props
+}: React.HTMLAttributes<HTMLDivElement> & { orientation?: "horizontal" | "vertical" }) {
+  return (
+    <div
+      role="separator"
+      className={cn(
+        "shrink-0 bg-border",
+        orientation === "horizontal" ? "h-px w-full" : "h-full w-px",
+        className,
+      )}
+      {...props}
+    />
+  );
+}

web/src/components/ui/switch.tsx

@@ -0,0 +1,37 @@
+import { cn } from "@/lib/utils";
+
+export function Switch({
+  checked,
+  onCheckedChange,
+  className,
+  disabled,
+}: {
+  checked: boolean;
+  onCheckedChange: (v: boolean) => void;
+  className?: string;
+  disabled?: boolean;
+}) {
+  return (
+    <button
+      type="button"
+      role="switch"
+      aria-checked={checked}
+      disabled={disabled}
+      className={cn(
+        "peer inline-flex h-5 w-9 shrink-0 cursor-pointer items-center rounded-full border-2 border-transparent shadow-sm transition-colors",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
+        "disabled:cursor-not-allowed disabled:opacity-50",
+        checked ? "bg-primary" : "bg-input",
+        className,
+      )}
+      onClick={() => onCheckedChange(!checked)}
+    >
+      <span
+        className={cn(
+          "pointer-events-none block h-4 w-4 rounded-full bg-background shadow-lg ring-0 transition-transform",
+          checked ? "translate-x-4" : "translate-x-0",
+        )}
+      />
+    </button>
+  );
+}

web/src/components/ui/tabs.tsx

@@ -0,0 +1,49 @@
+import { useState } from "react";
+import { cn } from "@/lib/utils";
+
+export function Tabs({
+  defaultValue,
+  children,
+  className,
+}: {
+  defaultValue: string;
+  children: (active: string, setActive: (v: string) => void) => React.ReactNode;
+  className?: string;
+}) {
+  const [active, setActive] = useState(defaultValue);
+  return <div className={cn("flex flex-col gap-4", className)}>{children(active, setActive)}</div>;
+}
+
+export function TabsList({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      className={cn(
+        "inline-flex h-9 items-center justify-start gap-1 rounded-lg bg-muted p-1 text-muted-foreground",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export function TabsTrigger({
+  active,
+  value,
+  onClick,
+  className,
+  ...props
+}: React.ButtonHTMLAttributes<HTMLButtonElement> & { active: boolean; value: string }) {
+  return (
+    <button
+      type="button"
+      className={cn(
+        "inline-flex items-center justify-center whitespace-nowrap rounded-md px-3 py-1 text-sm font-medium ring-offset-background transition-all cursor-pointer",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
+        active ? "bg-background text-foreground shadow" : "hover:bg-background/50",
+        className,
+      )}
+      onClick={onClick}
+      {...props}
+    />
+  );
+}

web/src/hooks/useToast.ts

@@ -0,0 +1,15 @@
+import { useCallback, useState } from "react";
+
+export function useToast(duration = 3000) {
+  const [toast, setToast] = useState<{ message: string; type: "success" | "error" } | null>(null);
+
+  const showToast = useCallback(
+    (message: string, type: "success" | "error") => {
+      setToast({ message, type });
+      setTimeout(() => setToast(null), duration);
+    },
+    [duration],
+  );
+
+  return { toast, showToast };
+}

web/src/index.css

@@ -0,0 +1,39 @@
+@import "tailwindcss";
+
+@theme {
+  --color-background: oklch(0.145 0 0);
+  --color-foreground: oklch(0.95 0 0);
+  --color-card: oklch(0.17 0 0);
+  --color-card-foreground: oklch(0.95 0 0);
+  --color-primary: oklch(0.7 0.15 250);
+  --color-primary-foreground: oklch(0.98 0 0);
+  --color-secondary: oklch(0.22 0 0);
+  --color-secondary-foreground: oklch(0.9 0 0);
+  --color-muted: oklch(0.2 0 0);
+  --color-muted-foreground: oklch(0.6 0 0);
+  --color-accent: oklch(0.25 0 0);
+  --color-accent-foreground: oklch(0.95 0 0);
+  --color-destructive: oklch(0.6 0.2 25);
+  --color-destructive-foreground: oklch(0.98 0 0);
+  --color-success: oklch(0.7 0.18 155);
+  --color-warning: oklch(0.75 0.15 75);
+  --color-border: oklch(0.25 0 0);
+  --color-input: oklch(0.25 0 0);
+  --color-ring: oklch(0.7 0.15 250);
+}
+
+body {
+  margin: 0;
+  font-family: system-ui, -apple-system, sans-serif;
+  background: var(--color-background);
+  color: var(--color-foreground);
+  -webkit-font-smoothing: antialiased;
+}
+
+code {
+  font-family: ui-monospace, "SF Mono", Menlo, monospace;
+  font-size: 0.85em;
+  padding: 0.15em 0.4em;
+  border-radius: 0.25rem;
+  background: var(--color-secondary);
+}

web/src/lib/api.ts

@@ -0,0 +1,88 @@
+const BASE = "";
+
+async function fetchJSON<T>(url: string, init?: RequestInit): Promise<T> {
+  const res = await fetch(`${BASE}${url}`, init);
+  if (!res.ok) {
+    const text = await res.text().catch(() => res.statusText);
+    throw new Error(`${res.status}: ${text}`);
+  }
+  return res.json();
+}
+
+export const api = {
+  getStatus: () => fetchJSON<StatusResponse>("/api/status"),
+  getSessions: () => fetchJSON<SessionInfo[]>("/api/sessions"),
+  getConfig: () => fetchJSON<Record<string, unknown>>("/api/config"),
+  getDefaults: () => fetchJSON<Record<string, unknown>>("/api/config/defaults"),
+  getSchema: () => fetchJSON<Record<string, unknown>>("/api/config/schema"),
+  saveConfig: (config: Record<string, unknown>) =>
+    fetchJSON<{ ok: boolean }>("/api/config", {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ config }),
+    }),
+  getEnvVars: () => fetchJSON<Record<string, EnvVarInfo>>("/api/env"),
+  setEnvVar: (key: string, value: string) =>
+    fetchJSON<{ ok: boolean }>("/api/env", {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ key, value }),
+    }),
+  deleteEnvVar: (key: string) =>
+    fetchJSON<{ ok: boolean }>("/api/env", {
+      method: "DELETE",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ key }),
+    }),
+};
+
+export interface PlatformStatus {
+  error_code?: string;
+  error_message?: string;
+  state: string;
+  updated_at: string;
+}
+
+export interface StatusResponse {
+  active_sessions: number;
+  config_path: string;
+  config_version: number;
+  env_path: string;
+  gateway_exit_reason: string | null;
+  gateway_pid: number | null;
+  gateway_platforms: Record<string, PlatformStatus>;
+  gateway_running: boolean;
+  gateway_state: string | null;
+  gateway_updated_at: string | null;
+  hermes_home: string;
+  latest_config_version: number;
+  release_date: string;
+  version: string;
+}
+
+export interface SessionInfo {
+  id: string;
+  source: string;
+  model: string;
+  title: string | null;
+  started_at: number;
+  ended_at: number | null;
+  last_active: number;
+  is_active: boolean;
+  message_count: number;
+  tool_call_count: number;
+  input_tokens: number;
+  output_tokens: number;
+  preview: string;
+}
+
+export interface EnvVarInfo {
+  is_set: boolean;
+  redacted_value: string | null;
+  description: string;
+  url: string | null;
+  category: string;
+  is_password: boolean;
+  tools: string[];
+  advanced: boolean;
+}

web/src/lib/nested.ts

@@ -0,0 +1,23 @@
+export function getNestedValue(obj: Record<string, unknown>, path: string): unknown {
+  const parts = path.split(".");
+  let cur: unknown = obj;
+  for (const p of parts) {
+    if (cur == null || typeof cur !== "object") return undefined;
+    cur = (cur as Record<string, unknown>)[p];
+  }
+  return cur;
+}
+
+export function setNestedValue(obj: Record<string, unknown>, path: string, value: unknown): Record<string, unknown> {
+  const clone = structuredClone(obj);
+  const parts = path.split(".");
+  let cur: Record<string, unknown> = clone;
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (cur[parts[i]] == null || typeof cur[parts[i]] !== "object") {
+      cur[parts[i]] = {};
+    }
+    cur = cur[parts[i]] as Record<string, unknown>;
+  }
+  cur[parts[parts.length - 1]] = value;
+  return clone;
+}

web/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

web/src/main.tsx

@@ -0,0 +1,10 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import "./index.css";
+import App from "./App";
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);

web/src/pages/ConfigPage.tsx

@@ -0,0 +1,149 @@
+import { useEffect, useRef, useState } from "react";
+import { Download, RotateCcw, Save, Upload } from "lucide-react";
+import { api } from "@/lib/api";
+import { getNestedValue, setNestedValue } from "@/lib/nested";
+import { useToast } from "@/hooks/useToast";
+import { Toast } from "@/components/Toast";
+import { AutoField } from "@/components/AutoField";
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import { Button } from "@/components/ui/button";
+import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs";
+
+export default function ConfigPage() {
+  const [config, setConfig] = useState<Record<string, unknown> | null>(null);
+  const [schema, setSchema] = useState<Record<string, Record<string, unknown>> | null>(null);
+  const [defaults, setDefaults] = useState<Record<string, unknown> | null>(null);
+  const [saving, setSaving] = useState(false);
+  const { toast, showToast } = useToast();
+  const fileInputRef = useRef<HTMLInputElement>(null);
+
+  useEffect(() => {
+    api.getConfig().then(setConfig).catch(() => {});
+    api.getSchema().then((s) => setSchema(s as Record<string, Record<string, unknown>>)).catch(() => {});
+    api.getDefaults().then(setDefaults).catch(() => {});
+  }, []);
+
+  const handleSave = async () => {
+    if (!config) return;
+    setSaving(true);
+    try {
+      await api.saveConfig(config);
+      showToast("Configuration saved", "success");
+    } catch (e) {
+      showToast(`Failed to save: ${e}`, "error");
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const handleReset = () => {
+    if (defaults) setConfig(structuredClone(defaults));
+  };
+
+  const handleExport = () => {
+    if (!config) return;
+    const blob = new Blob([JSON.stringify(config, null, 2)], { type: "application/json" });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = "hermes-config.json";
+    a.click();
+    URL.revokeObjectURL(url);
+  };
+
+  const handleImport = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0];
+    if (!file) return;
+    const reader = new FileReader();
+    reader.onload = () => {
+      try {
+        const imported = JSON.parse(reader.result as string);
+        setConfig(imported);
+        showToast("Config imported — review and save", "success");
+      } catch {
+        showToast("Invalid JSON file", "error");
+      }
+    };
+    reader.readAsText(file);
+  };
+
+  if (!config || !schema) {
+    return (
+      <div className="flex items-center justify-center py-24">
+        <div className="h-6 w-6 animate-spin rounded-full border-2 border-primary border-t-transparent" />
+      </div>
+    );
+  }
+
+  const categories = [...new Set(Object.values(schema).map((s) => String(s.category ?? "general")))];
+
+  return (
+    <div className="flex flex-col gap-6">
+      <Toast toast={toast} />
+
+      <div className="flex items-center justify-between flex-wrap gap-2">
+        <p className="text-sm text-muted-foreground">
+          Edit <code>~/.hermes/config.yaml</code>
+        </p>
+
+        <div className="flex items-center gap-2">
+          <Button variant="outline" size="sm" onClick={handleExport}>
+            <Download className="h-3 w-3" />
+            Export
+          </Button>
+
+          <Button variant="outline" size="sm" onClick={() => fileInputRef.current?.click()}>
+            <Upload className="h-3 w-3" />
+            Import
+          </Button>
+
+          <input ref={fileInputRef} type="file" accept=".json,.yaml,.yml" className="hidden" onChange={handleImport} />
+
+          <Button variant="outline" size="sm" onClick={handleReset}>
+            <RotateCcw className="h-3 w-3" />
+            Reset
+          </Button>
+
+          <Button size="sm" onClick={handleSave} disabled={saving}>
+            <Save className="h-3 w-3" />
+            {saving ? "Saving..." : "Save"}
+          </Button>
+        </div>
+      </div>
+
+      <Tabs defaultValue={categories[0]}>
+        {(active, setActive) => (
+          <>
+            <TabsList className="flex-wrap">
+              {categories.map((cat) => (
+                <TabsTrigger key={cat} value={cat} active={active === cat} onClick={() => setActive(cat)}>
+                  {cat.charAt(0).toUpperCase() + cat.slice(1)}
+                </TabsTrigger>
+              ))}
+            </TabsList>
+
+            <Card>
+              <CardHeader>
+                <CardTitle className="text-base capitalize">{active}</CardTitle>
+              </CardHeader>
+
+              <CardContent className="grid gap-6">
+                {Object.entries(schema)
+                  .filter(([, s]) => String(s.category ?? "general") === active)
+                  .map(([key, s]) => (
+                    <AutoField
+                      key={key}
+                      schemaKey={key}
+                      schema={s}
+                      value={getNestedValue(config, key)}
+                      onChange={(v) => setConfig(setNestedValue(config, key, v))}
+                    />
+                  ))}
+              </CardContent>
+            </Card>
+          </>
+        )}
+      </Tabs>
+    </div>
+  );
+}

web/src/pages/EnvPage.tsx

@@ -0,0 +1,240 @@
+import { useEffect, useState } from "react";
+import {
+  ExternalLink,
+  Eye,
+  EyeOff,
+  KeyRound,
+  MessageSquare,
+  Save,
+  Settings,
+  Trash2,
+  Zap,
+} from "lucide-react";
+import { api } from "@/lib/api";
+import type { EnvVarInfo } from "@/lib/api";
+import { useToast } from "@/hooks/useToast";
+import { Toast } from "@/components/Toast";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+
+const CATEGORY_META: Record<string, { label: string; icon: typeof KeyRound }> = {
+  provider: { label: "LLM Providers", icon: Zap },
+  tool: { label: "Tool API Keys", icon: KeyRound },
+  messaging: { label: "Messaging Platforms", icon: MessageSquare },
+  setting: { label: "Agent Settings", icon: Settings },
+};
+
+export default function EnvPage() {
+  const [vars, setVars] = useState<Record<string, EnvVarInfo> | null>(null);
+  const [edits, setEdits] = useState<Record<string, string>>({});
+  const [showValues, setShowValues] = useState<Record<string, boolean>>({});
+  const [saving, setSaving] = useState<string | null>(null);
+  const [showAdvanced, setShowAdvanced] = useState(false);
+  const { toast, showToast } = useToast();
+
+  useEffect(() => {
+    api.getEnvVars().then(setVars).catch(() => {});
+  }, []);
+
+  const handleSave = async (key: string) => {
+    const value = edits[key];
+    if (!value) return;
+    setSaving(key);
+    try {
+      await api.setEnvVar(key, value);
+      setVars((prev) =>
+        prev
+          ? {
+              ...prev,
+              [key]: { ...prev[key], is_set: true, redacted_value: value.slice(0, 4) + "..." + value.slice(-4) },
+            }
+          : prev,
+      );
+      setEdits((prev) => {
+        const next = { ...prev };
+        delete next[key];
+        return next;
+      });
+      showToast(`${key} saved — active sessions will pick this up automatically`, "success");
+    } catch (e) {
+      showToast(`Failed to save ${key}: ${e}`, "error");
+    } finally {
+      setSaving(null);
+    }
+  };
+
+  const handleClear = async (key: string) => {
+    setSaving(key);
+    try {
+      await api.deleteEnvVar(key);
+      setVars((prev) =>
+        prev
+          ? { ...prev, [key]: { ...prev[key], is_set: false, redacted_value: null } }
+          : prev,
+      );
+      setEdits((prev) => {
+        const next = { ...prev };
+        delete next[key];
+        return next;
+      });
+      showToast(`${key} removed`, "success");
+    } catch (e) {
+      showToast(`Failed to remove ${key}: ${e}`, "error");
+    } finally {
+      setSaving(null);
+    }
+  };
+
+  if (!vars) {
+    return (
+      <div className="flex items-center justify-center py-24">
+        <div className="h-6 w-6 animate-spin rounded-full border-2 border-primary border-t-transparent" />
+      </div>
+    );
+  }
+
+  const categories = Object.keys(CATEGORY_META);
+  const grouped = categories.map((cat) => ({
+    ...CATEGORY_META[cat],
+    category: cat,
+    entries: Object.entries(vars).filter(
+      ([, info]) => info.category === cat && (showAdvanced || !info.advanced),
+    ),
+  }));
+
+  return (
+    <div className="flex flex-col gap-6">
+      <Toast toast={toast} />
+
+      <div className="flex items-center justify-between">
+        <div className="flex flex-col gap-1">
+          <p className="text-sm text-muted-foreground">
+            Manage API keys and secrets stored in <code>~/.hermes/.env</code>
+          </p>
+          <p className="text-xs text-muted-foreground/70">
+            Changes are saved to disk immediately. Active sessions pick up new keys automatically within a few seconds.
+          </p>
+        </div>
+        <Button
+          variant="ghost"
+          size="sm"
+          onClick={() => setShowAdvanced(!showAdvanced)}
+        >
+          {showAdvanced ? "Hide Advanced" : "Show Advanced"}
+        </Button>
+      </div>
+
+      {grouped.map(({ label, icon: Icon, entries, category }) => {
+        if (entries.length === 0) return null;
+        return (
+          <Card key={category}>
+            <CardHeader>
+              <div className="flex items-center gap-2">
+                <Icon className="h-5 w-5 text-muted-foreground" />
+                <CardTitle className="text-base">{label}</CardTitle>
+              </div>
+              <CardDescription>
+                {entries.filter(([, i]) => i.is_set).length} of {entries.length} configured
+              </CardDescription>
+            </CardHeader>
+
+            <CardContent className="grid gap-4">
+              {entries.map(([key, info]) => (
+                <div key={key} className="grid gap-2 rounded-lg border border-border p-4">
+                  <div className="flex items-center justify-between gap-2 flex-wrap">
+                    <div className="flex items-center gap-2">
+                      <Label className="font-mono text-xs">{key}</Label>
+                      <Badge variant={info.is_set ? "success" : "outline"}>
+                        {info.is_set ? "Set" : "Not set"}
+                      </Badge>
+                    </div>
+
+                    {info.url && (
+                      <a
+                        href={info.url}
+                        target="_blank"
+                        rel="noreferrer"
+                        className="inline-flex items-center gap-1 text-xs text-primary hover:underline"
+                      >
+                        Get key <ExternalLink className="h-3 w-3" />
+                      </a>
+                    )}
+                  </div>
+
+                  <p className="text-xs text-muted-foreground">{info.description}</p>
+
+                  {info.tools.length > 0 && (
+                    <div className="flex flex-wrap gap-1">
+                      {info.tools.map((tool) => (
+                        <Badge key={tool} variant="secondary" className="text-[10px]">
+                          {tool}
+                        </Badge>
+                      ))}
+                    </div>
+                  )}
+
+                  <div className="flex items-center gap-2">
+                    <div className="relative flex-1">
+                      <Input
+                        type={showValues[key] ? "text" : "password"}
+                        value={
+                          edits[key] !== undefined
+                            ? edits[key]
+                            : info.is_set
+                              ? info.redacted_value ?? ""
+                              : ""
+                        }
+                        onChange={(e) => setEdits({ ...edits, [key]: e.target.value })}
+                        onFocus={() => {
+                          if (edits[key] === undefined && info.is_set) {
+                            setEdits({ ...edits, [key]: "" });
+                          }
+                        }}
+                        placeholder={info.is_set ? "(click to replace)" : "Enter value..."}
+                        className="pr-9 font-mono text-xs"
+                      />
+                      <button
+                        type="button"
+                        className="absolute right-2 top-1/2 -translate-y-1/2 text-muted-foreground hover:text-foreground cursor-pointer"
+                        onClick={() => setShowValues({ ...showValues, [key]: !showValues[key] })}
+                      >
+                        {showValues[key] ? <EyeOff className="h-4 w-4" /> : <Eye className="h-4 w-4" />}
+                      </button>
+                    </div>
+
+                    {edits[key] !== undefined && (
+                      <Button
+                        size="sm"
+                        onClick={() => handleSave(key)}
+                        disabled={saving === key || !edits[key]}
+                      >
+                        <Save className="h-3 w-3" />
+                        {saving === key ? "..." : "Save"}
+                      </Button>
+                    )}
+
+                    {info.is_set && edits[key] === undefined && (
+                      <Button
+                        size="sm"
+                        variant="ghost"
+                        className="text-destructive hover:text-destructive hover:bg-destructive/10"
+                        onClick={() => handleClear(key)}
+                        disabled={saving === key}
+                      >
+                        <Trash2 className="h-3 w-3" />
+                        {saving === key ? "..." : "Clear"}
+                      </Button>
+                    )}
+                  </div>
+                </div>
+              ))}
+            </CardContent>
+          </Card>
+        );
+      })}
+    </div>
+  );
+}

web/src/pages/StatusPage.tsx

@@ -0,0 +1,295 @@
+import { useEffect, useState } from "react";
+import {
+  Activity,
+  AlertTriangle,
+  Clock,
+  Cpu,
+  Database,
+  Radio,
+  Shield,
+  Wifi,
+  WifiOff,
+} from "lucide-react";
+import { api } from "@/lib/api";
+import type { PlatformStatus, SessionInfo, StatusResponse } from "@/lib/api";
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import { Badge } from "@/components/ui/badge";
+
+function timeAgo(ts: number): string {
+  const delta = Date.now() / 1000 - ts;
+  if (delta < 60) return "just now";
+  if (delta < 3600) return `${Math.floor(delta / 60)}m ago`;
+  if (delta < 86400) return `${Math.floor(delta / 3600)}h ago`;
+  if (delta < 172800) return "yesterday";
+  return `${Math.floor(delta / 86400)}d ago`;
+}
+
+function isoTimeAgo(iso: string): string {
+  const delta = (Date.now() - new Date(iso).getTime()) / 1000;
+  if (delta < 0 || Number.isNaN(delta)) return "unknown";
+  if (delta < 60) return "just now";
+  if (delta < 3600) return `${Math.floor(delta / 60)}m ago`;
+  if (delta < 86400) return `${Math.floor(delta / 3600)}h ago`;
+  return `${Math.floor(delta / 86400)}d ago`;
+}
+
+const PLATFORM_STATE_BADGE: Record<string, { variant: "success" | "warning" | "destructive"; label: string }> = {
+  connected: { variant: "success", label: "Connected" },
+  disconnected: { variant: "warning", label: "Disconnected" },
+  fatal: { variant: "destructive", label: "Error" },
+};
+
+const GATEWAY_STATE_DISPLAY: Record<string, { badge: "success" | "warning" | "destructive" | "outline"; label: string }> = {
+  running: { badge: "success", label: "Running" },
+  starting: { badge: "warning", label: "Starting" },
+  startup_failed: { badge: "destructive", label: "Failed" },
+  stopped: { badge: "outline", label: "Stopped" },
+};
+
+function gatewayValue(status: StatusResponse): string {
+  if (status.gateway_running) return `PID ${status.gateway_pid}`;
+  if (status.gateway_state === "startup_failed") return "Start failed";
+  return "Not running";
+}
+
+function gatewayBadge(status: StatusResponse) {
+  const info = status.gateway_state ? GATEWAY_STATE_DISPLAY[status.gateway_state] : null;
+  if (info) return info;
+  return status.gateway_running
+    ? { badge: "success" as const, label: "Running" }
+    : { badge: "outline" as const, label: "Off" };
+}
+
+export default function StatusPage() {
+  const [status, setStatus] = useState<StatusResponse | null>(null);
+  const [sessions, setSessions] = useState<SessionInfo[]>([]);
+
+  useEffect(() => {
+    const load = () => {
+      api.getStatus().then(setStatus).catch(() => {});
+      api.getSessions().then(setSessions).catch(() => {});
+    };
+    load();
+    const interval = setInterval(load, 5000);
+    return () => clearInterval(interval);
+  }, []);
+
+  if (!status) {
+    return (
+      <div className="flex items-center justify-center py-24">
+        <div className="h-6 w-6 animate-spin rounded-full border-2 border-primary border-t-transparent" />
+      </div>
+    );
+  }
+
+  const configNeedsMigration = status.config_version < status.latest_config_version;
+  const gwBadge = gatewayBadge(status);
+
+  const items = [
+    {
+      icon: Cpu,
+      label: "Agent",
+      value: `v${status.version}`,
+      badgeText: "Live",
+      badgeVariant: "success" as const,
+    },
+    {
+      icon: Activity,
+      label: "Active Sessions",
+      value: status.active_sessions > 0 ? `${status.active_sessions} running` : "None",
+      badgeText: status.active_sessions > 0 ? "Live" : "Off",
+      badgeVariant: (status.active_sessions > 0 ? "success" : "outline") as "success" | "outline",
+    },
+    {
+      icon: Radio,
+      label: "Gateway",
+      value: gatewayValue(status),
+      badgeText: gwBadge.label,
+      badgeVariant: gwBadge.badge,
+    },
+    {
+      icon: Shield,
+      label: "Config Version",
+      value: `v${status.config_version}`,
+      badgeText: configNeedsMigration ? "Migrate" : "Current",
+      badgeVariant: (configNeedsMigration ? "warning" : "success") as "warning" | "success",
+    },
+  ];
+
+  const platforms = Object.entries(status.gateway_platforms ?? {});
+  const activeSessions = sessions.filter((s) => s.is_active);
+  const recentSessions = sessions.filter((s) => !s.is_active).slice(0, 5);
+
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-4">
+        {items.map(({ icon: Icon, label, value, badgeText, badgeVariant }) => (
+          <Card key={label}>
+            <CardHeader className="flex flex-row items-center justify-between pb-2">
+              <CardTitle className="text-sm font-medium">{label}</CardTitle>
+              <Icon className="h-4 w-4 text-muted-foreground" />
+            </CardHeader>
+
+            <CardContent>
+              <div className="text-2xl font-bold">{value}</div>
+
+              <Badge variant={badgeVariant} className="mt-2">
+                {badgeVariant === "success" && (
+                  <span className="mr-1 inline-block h-1.5 w-1.5 animate-pulse rounded-full bg-current" />
+                )}
+                {badgeText}
+              </Badge>
+
+              {label === "Gateway" && !status.gateway_running && status.gateway_exit_reason && (
+                <p className="mt-2 text-xs text-destructive">{status.gateway_exit_reason}</p>
+              )}
+            </CardContent>
+          </Card>
+        ))}
+      </div>
+
+      {platforms.length > 0 && (
+        <PlatformsCard platforms={platforms} />
+      )}
+
+      {activeSessions.length > 0 && (
+        <Card>
+          <CardHeader>
+            <div className="flex items-center gap-2">
+              <Activity className="h-5 w-5 text-success" />
+              <CardTitle className="text-base">Active Sessions</CardTitle>
+            </div>
+          </CardHeader>
+
+          <CardContent className="grid gap-3">
+            {activeSessions.map((s) => (
+              <div
+                key={s.id}
+                className="flex items-center justify-between rounded-lg border border-border p-3"
+              >
+                <div className="flex flex-col gap-1">
+                  <div className="flex items-center gap-2">
+                    <span className="font-medium text-sm">{s.title ?? "Untitled"}</span>
+
+                    <Badge variant="success" className="text-[10px]">
+                      <span className="mr-1 inline-block h-1.5 w-1.5 animate-pulse rounded-full bg-current" />
+                      Live
+                    </Badge>
+                  </div>
+
+                  <span className="text-xs text-muted-foreground">
+                    {s.model} · {s.message_count} msgs · {timeAgo(s.last_active)}
+                  </span>
+                </div>
+              </div>
+            ))}
+          </CardContent>
+        </Card>
+      )}
+
+      {recentSessions.length > 0 && (
+        <Card>
+          <CardHeader>
+            <div className="flex items-center gap-2">
+              <Clock className="h-5 w-5 text-muted-foreground" />
+              <CardTitle className="text-base">Recent Sessions</CardTitle>
+            </div>
+          </CardHeader>
+
+          <CardContent className="grid gap-3">
+            {recentSessions.map((s) => (
+              <div
+                key={s.id}
+                className="flex items-center justify-between rounded-lg border border-border p-3"
+              >
+                <div className="flex flex-col gap-1">
+                  <span className="font-medium text-sm">{s.title ?? "Untitled"}</span>
+
+                  <span className="text-xs text-muted-foreground">
+                    {s.model} · {s.message_count} msgs · {timeAgo(s.last_active)}
+                  </span>
+
+                  {s.preview && (
+                    <span className="text-xs text-muted-foreground/70 truncate max-w-md">
+                      {s.preview}
+                    </span>
+                  )}
+                </div>
+
+                <Badge variant="outline" className="text-[10px]">
+                  <Database className="mr-1 h-3 w-3" />
+                  {s.source}
+                </Badge>
+              </div>
+            ))}
+          </CardContent>
+        </Card>
+      )}
+    </div>
+  );
+}
+
+function PlatformsCard({ platforms }: PlatformsCardProps) {
+  return (
+    <Card>
+      <CardHeader>
+        <div className="flex items-center gap-2">
+          <Radio className="h-5 w-5 text-muted-foreground" />
+          <CardTitle className="text-base">Connected Platforms</CardTitle>
+        </div>
+      </CardHeader>
+
+      <CardContent className="grid gap-3">
+        {platforms.map(([name, info]) => {
+          const display = PLATFORM_STATE_BADGE[info.state] ?? {
+            variant: "outline" as const,
+            label: info.state,
+          };
+          const IconComponent = info.state === "connected" ? Wifi : info.state === "fatal" ? AlertTriangle : WifiOff;
+
+          return (
+            <div
+              key={name}
+              className="flex items-center justify-between rounded-lg border border-border p-3"
+            >
+              <div className="flex items-center gap-3">
+                <IconComponent className={`h-4 w-4 ${
+                  info.state === "connected"
+                    ? "text-success"
+                    : info.state === "fatal"
+                      ? "text-destructive"
+                      : "text-warning"
+                }`} />
+
+                <div className="flex flex-col gap-0.5">
+                  <span className="text-sm font-medium capitalize">{name}</span>
+
+                  {info.error_message && (
+                    <span className="text-xs text-destructive">{info.error_message}</span>
+                  )}
+
+                  {info.updated_at && (
+                    <span className="text-xs text-muted-foreground">
+                      Last update: {isoTimeAgo(info.updated_at)}
+                    </span>
+                  )}
+                </div>
+              </div>
+
+              <Badge variant={display.variant}>
+                {display.variant === "success" && (
+                  <span className="mr-1 inline-block h-1.5 w-1.5 animate-pulse rounded-full bg-current" />
+                )}
+                {display.label}
+              </Badge>
+            </div>
+          );
+        })}
+      </CardContent>
+    </Card>
+  );
+}
+
+interface PlatformsCardProps {
+  platforms: [string, PlatformStatus][];
+}

web/tsconfig.app.json

@@ -0,0 +1,34 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "ES2023",
+    "useDefineForClassFields": true,
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "types": ["vite/client"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Path aliases */
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    },
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["src"]
+}

web/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.app.json" },
+    { "path": "./tsconfig.node.json" }
+  ]
+}

web/tsconfig.node.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+    "target": "ES2023",
+    "lib": ["ES2023"],
+    "module": "ESNext",
+    "types": ["node"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["vite.config.ts"]
+}

web/vite.config.ts

@@ -0,0 +1,22 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import tailwindcss from "@tailwindcss/vite";
+import path from "path";
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+  resolve: {
+    alias: {
+      "@": path.resolve(__dirname, "./src"),
+    },
+  },
+  build: {
+    outDir: "../hermes_cli/web_dist",
+    emptyOutDir: true,
+  },
+  server: {
+    proxy: {
+      "/api": "http://127.0.0.1:9119",
+    },
+  },
+});

website/docs/user-guide/configuration.md

@@ -1018,7 +1018,8 @@ auxiliary:
     model: ""                  # e.g. "openai/gpt-4o", "google/gemini-2.5-flash"
     base_url: ""               # Custom OpenAI-compatible endpoint (overrides provider)
     api_key: ""                # API key for base_url (falls back to OPENAI_API_KEY)
-    timeout: 30                # seconds — increase for slow local vision models
+    timeout: 30                # seconds — LLM API call; increase for slow local vision models
+    download_timeout: 30       # seconds — image HTTP download; increase for slow connections
 
   # Web page summarization + browser page text extraction
   web_extract:
@@ -1042,7 +1043,7 @@ auxiliary:
 ```
 
 :::tip
-Each auxiliary task has a configurable `timeout` (in seconds). Defaults: vision 30s, web_extract 30s, approval 30s, compression 120s. Increase these if you use slow local models for auxiliary tasks.
+Each auxiliary task has a configurable `timeout` (in seconds). Defaults: vision 30s, web_extract 30s, approval 30s, compression 120s. Increase these if you use slow local models for auxiliary tasks. Vision also has a separate `download_timeout` (default 30s) for the HTTP image download — increase this for slow connections or self-hosted image servers.
 :::
 
 :::info

website/docs/user-guide/messaging/feishu.md

@@ -32,8 +32,8 @@ Set it to `false` only if you explicitly want one shared conversation per chat.
 ## Step 1: Create a Feishu / Lark App
 
 1. Open the Feishu or Lark developer console:
-   - Feishu: <https://open.feishu.cn/>
-   - Lark: <https://open.larksuite.com/>
+   - Feishu: [https://open.feishu.cn/](https://open.feishu.cn/)
+   - Lark: [https://open.larksuite.com/](https://open.larksuite.com/)
 2. Create a new app.
 3. In **Credentials & Basic Info**, copy the **App ID** and **App Secret**.
 4. Enable the **Bot** capability for the app.