Environment Abstraction

Relevant source files

• hermes_cli/callbacks.py
• scripts/tests/test-install-ps1-gitbash-compatibility.ps1
• tests/acp/test_approval_isolation.py
• tests/gateway/test_config_cwd_bridge.py
• tests/gateway/test_cwd_placeholder.py
• tests/gateway/test_internal_event_bypass_pairing.py
• tests/run_agent/test_24996_fallback_exhaustion_cooldown.py
• tests/test_transform_tool_result_hook.py
• tests/tools/test_approved_command_clean_slate.py
• tests/tools/test_base_environment.py
• tests/tools/test_code_execution.py
• tests/tools/test_code_execution_windows_env.py
• tests/tools/test_file_tools_live.py
• tests/tools/test_find_shell.py
• tests/tools/test_interrupt.py
• tests/tools/test_local_background_child_hang.py
• tests/tools/test_local_env_blocklist.py
• tests/tools/test_local_env_cwd_recovery.py
• tests/tools/test_local_env_windows_msys.py
• tests/tools/test_local_shell_init.py
• tests/tools/test_managed_modal_environment.py
• tests/tools/test_notify_on_complete.py
• tests/tools/test_process_registry.py
• tests/tools/test_snapshot_session_id_leak.py
• tests/tools/test_terminal_output_transform_hook.py
• tests/tools/test_terminal_tool.py
• tests/tools/test_threaded_process_handle.py
• tests/tools/test_tirith_security.py
• tests/tools/test_voice_cli_integration.py
• tests/tools/test_voice_mode.py
• tests/tools/test_watch_patterns.py
• tools/code_execution_tool.py
• tools/environments/base.py
• tools/environments/local.py
• tools/environments/managed_modal.py
• tools/environments/modal_utils.py
• tools/interrupt.py
• tools/process_registry.py
• tools/tirith_security.py
• tools/voice_mode.py

Purpose and Scope

This page documents the environment abstraction layer that enables Hermes Agent to execute commands and manipulate files across multiple execution backends (local, Docker, Modal, SSH, Singularity, and Daytona) through a unified interface. This abstraction allows tools like terminal, read_file, write_file, patch, and search_files to work identically regardless of where the code runs.

The abstraction provides:

• Unified Interface: A common set of methods for command execution and cleanup defined in the BaseEnvironment abstract base class tools/environments/base.py19-21
• Lifecycle Management: Automated creation, caching, and background reaping of inactive environments via a background cleanup thread tools/terminal_tool.py530-631
• Session Reuse: Persistent state (CWD, environment variables, shell variables) across multiple tool calls within the same task using a "spawn-per-call" model where a session snapshot is captured once at init and re-sourced before each command tools/environments/base.py3-7
• Security Isolation: Per-task sandboxed execution and environment variable sanitization to prevent sensitive Hermes-internal credentials from leaking into subprocesses tools/environments/local.py148-173 tools/code_execution_tool.py135-173

Sources: tools/environments/base.py1-21 tools/terminal_tool.py530-631 tools/environments/local.py148-173 tools/code_execution_tool.py135-173

---

The BaseEnvironment Interface

All execution environments implement a minimal interface consisting of core methods defined in the BaseEnvironment class.

Method	Signature	Purpose
execute()	execute(command: str, cwd: str = None, timeout: int = None, stdin_data: str = None) -> dict	Execute a shell command and return a dictionary containing output and returncode tools/environments/base.py214-219
cleanup()	cleanup() -> None	Release resources, such as stopping containers, closing SSH ControlMaster sockets, or terminating sandboxes tools/environments/base.py216

Implementation Details

• ProcessHandle Protocol: Backends return a ProcessHandle (like subprocess.Popen) or a _ThreadedProcessHandle for SDK-based backends (Modal, Daytona) to provide a consistent polling and wait interface tools/environments/base.py187-200
• Heredoc Support: Backends like DaytonaEnvironment and ModalEnvironment use a _stdin_mode = "heredoc" for stdin_data to pass multi-line strings into cloud sandboxes efficiently tools/environments/base.py102-133
• Activity Monitoring: The touch_activity_if_due function allows long-running executions to report liveness to the gateway via a thread-local activity callback, preventing session timeouts during heavy computation tools/environments/base.py156-181
• Safe Stdin Piping: To avoid pipe-buffer deadlocks and Windows newline corruption, the base layer uses _pipe_stdin which writes through the underlying byte buffer on a daemon thread tools/environments/base.py102-133
• Atomic Snapshots: Environment snapshots are written using a temporary file and an atomic mv -f operation to prevent concurrent command execution from reading torn/corrupted state files tests/tools/test_base_environment.py139-153

Sources: tools/environments/base.py44-219 tests/tools/test_base_environment.py139-182

---

Environment Factory and Configuration

Factory Pattern

The _create_environment() function in terminal_tool.py serves as the central factory. It resolves the backend type from the TERMINAL_ENV variable and instantiates the specific implementation class tools/terminal_tool.py406-454

Environment Resolution Flow

Sources: tools/terminal_tool.py406-454

Configuration Resolution

Configuration follows a strict hierarchy:

1. Per-task overrides: Set via register_task_env_overrides(), used for specific tasks or benchmarks tools/terminal_tool.py378-395
2. Environment Variables: TERMINAL_ENV, TERMINAL_DOCKER_IMAGE, TERMINAL_SSH_HOST, etc. tools/terminal_tool.py9-12
3. Defaults: Hardcoded fallbacks (e.g., local backend) tools/terminal_tool.py10

Sources: tools/terminal_tool.py8-12 tools/terminal_tool.py378-454

---

Environment Lifecycle Management

Creation and Caching

Environments are created on-demand and stored in a global _active_environments registry, keyed by task_id. To prevent race conditions where multiple tool calls attempt to spawn the same sandbox simultaneously, a _creation_locks dictionary provides per-task synchronization tools/terminal_tool.py359-365

Automatic Cleanup and Reaping

A background thread, _cleanup_thread_worker, periodically scans active environments to reap those that have exceeded their idle TTL tools/terminal_tool.py530-631

Environment Cleanup Flow

Key Behaviors:

• Background Process Protection: If the ProcessRegistry reports active background tasks for a task_id, the environment is kept alive regardless of tool inactivity tools/terminal_tool.py536-544
• Non-blocking Teardown: env.cleanup() is called outside the global lock to prevent slow container shutdowns from blocking the entire system tools/terminal_tool.py560-592
• Disk Usage Warnings: The tool monitors total disk usage of hermes-related scratch directories via _check_disk_usage_warning() and warns when thresholds are exceeded tools/terminal_tool.py123-149

Sources: tools/terminal_tool.py123-149 tools/terminal_tool.py530-631 tools/process_registry.py142-151

---

Execution Backend Implementations

Backend	Class	Characteristics
Local	LocalEnvironment	Runs on host. Uses _run_bash for execution. Filters internal credentials via _sanitize_subprocess_env tools/environments/local.py148-173 Handles path translation between MSYS/Git Bash and Windows tools/environments/local.py24-108
Docker	DockerEnvironment	Security-hardened with cap-drop ALL, no-new-privileges, and PID limits. Supports filesystem persistence via bind mounts.
Modal	ModalEnvironment	Cloud-based execution via native Modal Sandboxes. Supports filesystem snapshots and persistent storage.
SSH	SSHEnvironment	Remote execution via ControlMaster persistence. Uses hashed socket IDs to fit macOS path limits.
Singularity	SingularityEnvironment	Hardened Singularity/Apptainer containers with resource limits and optional writable overlays for persistence.
Daytona	DaytonaEnvironment	Cloud-based execution using the Daytona Python SDK. Supports persistent sandboxes that can be stopped and resumed.

Sources: tools/environments/local.py24-173 tools/environments/base.py1-21

---

Background Process Management

The ProcessRegistry tracks background processes spawned via terminal(background=true). These processes execute through the environment interface, ensuring they run inside the sandbox (Docker, SSH, etc.) rather than on the host machine tools/process_registry.py12-15

• Output Buffering: Maintains a rolling 200KB output window for each background process via MAX_OUTPUT_CHARS tools/process_registry.py58
• Watch Patterns: Allows the agent to be notified when specific output patterns are matched, with per-session rate limiting (WATCH_MIN_INTERVAL_SECONDS) and strike-based circuit breakers tools/process_registry.py63-70
• Crash Recovery: Periodically saves the registry state to processes.json (CHECKPOINT_PATH) to allow recovering tracking of long-running tasks after a gateway restart tools/process_registry.py54-56
• PID-Reuse Guard: Tracks kernel start ticks (host_start_time) to ensure a PID hasn't been recycled by the OS before attempting to poll or kill a process tools/process_registry.py102

Sources: tools/process_registry.py1-139 tools/process_registry.py142-151

---

Programmatic Tool Calling (PTC)

The execute_code tool allows the agent to write Python scripts that call other Hermes tools via an RPC mechanism. This collapses multi-step tool chains into a single inference turn tools/code_execution_tool.py3-6

• Transports: Uses Unix Domain Sockets (UDS) for local execution and file-based RPC for remote backends tools/code_execution_tool.py10-23
• Sandboxing: The script runs in a child process with a scrubbed environment, removing all Hermes-internal API keys and sensitive tokens defined in _SECRET_SUBSTRINGS tools/code_execution_tool.py135-173
• Allowed Tools: Only a subset of tools defined in SANDBOX_ALLOWED_TOOLS (e.g., web_search, read_file, terminal) are available inside the execute_code sandbox tools/code_execution_tool.py62-70

Sources: tools/code_execution_tool.py1-77 tools/code_execution_tool.py135-173

---

Tool Integration Flow

The relationship between high-level tools and the environment abstraction is mediated by terminal_tool and the ProcessRegistry.

Terminal Tool Execution Flow

Sources: tools/terminal_tool.py25-32 tools/process_registry.py142-151 tools/environments/base.py187-200