hermes - 💡(How to fix) Fix [Bug]: Automatic transition to Docker sandbox when starting background processes causing filesystem desync [1 participants]

Bug Description

Description: I discovered a critical behavior in Hermes Agent where certain terminal operations trigger an automatic backend switch from local to docker (sandbox) mid-session, leading to a "ghost filesystem" state.

The "Sandbox Trap" Flow:

Initial State: The agent starts in local mode. write_file operations correctly reflect on the host machine. The Trigger: Using terminal with background=true (especially when running tools like npx live-server or npm based servers) triggers an automatic transition to the Docker sandbox. The Symptom: Once the session enters the sandbox, all subsequent write_file calls return "Success" in the logs, but the changes are written to a virtual mirror and do not reflect on the host filesystem. The Process Paradox: Background processes started before the transition (on the host) cannot be killed by the agent after the transition, because the kill commands are now executing inside the isolated sandbox. Reproduction Steps:

Ask the agent to create a file on the host desktop (Success). Ask the agent to start a server using npx live-server with background=true (Triggers Sandbox). Ask the agent to create another file on the desktop → Tool reports success, but no file appears on the host. Try to kill the server → The agent fails to kill the host process. Proposed Workaround: Currently, the only way to avoid this is "Session Isolation":

Use a Main Session for all file modifications (ensure it never starts a background process). Use a Disposable Session exclusively for starting/managing servers. Use a Fresh Session to kill processes to ensure the command hits the host. Expected Behavior: The agent should maintain the local backend unless explicitly configured otherwise, or provide a clear notification when a backend switch occurs.

Steps to Reproduce

Baseline Verification: Ask the agent to create a simple file on the host Desktop. Expected Result: File is created successfully on the host machine (confirms the agent is initially in local mode). Trigger Sandbox: Instruct the agent to start a background server on a specific port (e.g., python3 -m http.server 8001). Process Manipulation: Ask the agent to kill the existing server and start a new one on a different port (e.g., 8002). Symptom Observation: Ask the agent to create another file on the host Desktop. Actual Result: The agent reports that the file was created successfully in the logs, but the file does not exist on the host Desktop. Observation: The agent has silently transitioned to the Docker sandbox, where write_file operations are mirrored but not synced to the host.

Expected Behavior

The agent should maintain its local backend and consistent write access to the host filesystem, regardless of whether a background process (like a server) is started. Any write_file operation should always be reflected on the host machine in real-time.

Actual Behavior

Upon starting a background process (using background=true), the agent's backend silently transitions to docker (sandbox). While the write_file tool continues to return a "Success" status in the logs, the changes are written to a virtual mirrored filesystem and are not synced to the host machine. Additionally, the agent loses the ability to manage (e.g., kill) processes that were started prior to the transition on the host.

Affected Component

Configuration (config.yaml, .env, hermes setup)

Messaging Platform (if gateway-related)

N/A (CLI only)

Debug Report

;

Operating System

macOS 26.3.1 (a)

Python Version

3.14.3

Hermes Version

v0.12.0 (2026.4.30)

Additional Logs / Traceback (optional)

Root Cause Analysis (optional)

No response

Proposed Fix (optional)

No response

Are you willing to submit a PR for this?

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