Backend Implementations

Relevant source files

• tests/gateway/test_internal_event_bypass_pairing.py
• tests/integration/test_daytona_terminal.py
• tests/run_agent/test_24996_fallback_exhaustion_cooldown.py
• tests/tools/test_approved_command_clean_slate.py
• tests/tools/test_code_execution.py
• tests/tools/test_code_execution_windows_env.py
• tests/tools/test_daytona_environment.py
• tests/tools/test_docker_environment.py
• tests/tools/test_docker_orphan_reaper_integration.py
• tests/tools/test_file_sync.py
• tests/tools/test_file_sync_back.py
• tests/tools/test_file_sync_sigint.py
• tests/tools/test_file_tools_live.py
• tests/tools/test_interrupt.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_modal_bulk_upload.py
• tests/tools/test_modal_snapshot_isolation.py
• tests/tools/test_notify_on_complete.py
• tests/tools/test_process_registry.py
• tests/tools/test_ssh_bulk_upload.py
• tests/tools/test_ssh_environment.py
• tests/tools/test_sync_back_backends.py
• tests/tools/test_terminal_config_env_sync.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/daytona.py
• tools/environments/docker.py
• tools/environments/file_sync.py
• tools/environments/local.py
• tools/environments/modal.py
• tools/environments/singularity.py
• tools/environments/ssh.py
• tools/interrupt.py
• tools/process_registry.py
• tools/terminal_tool.py
• tools/tirith_security.py
• tools/voice_mode.py

This page documents the execution environment backends that implement the common execute() interface defined in the environment abstraction layer. Each backend provides command execution in a different context: local machine, Docker containers, Singularity containers, Modal cloud sandboxes, remote SSH hosts, or Daytona workspaces.

For the common interface and lifecycle management (environment creation, cleanup, activity tracking), see 6.1 Environment Abstraction For details on command execution through the terminal tool and process management, see 5.2 Terminal and File Operations and 5.3 Process Management

---

Configuration System

Backend selection and configuration are controlled by environment variables and the ~/.hermes/config.yaml file. The TERMINAL_ENV environment variable or the configuration logic determines which backend is instantiated tools/terminal_tool.py9-13

Backend Selection

The environment variable or config key controls which backend is instantiated:

Value	Backend	Use Case
local	LocalEnvironment	Direct execution on host machine (default, fastest) tools/environments/local.py1
docker	DockerEnvironment	Isolated Docker containers with security hardening tools/environments/docker.py1-6
singularity	SingularityEnvironment	HPC-friendly containers with overlay filesystems tools/environments/singularity.py65-69
modal	ModalEnvironment	Cloud sandboxes via Modal.com SDK tools/terminal_tool.py12
ssh	SSHEnvironment	Remote execution over SSH with ControlMaster tools/environments/ssh.py36-43
daytona	DaytonaEnvironment	Daytona development environment workspaces tools/environments/daytona.py30-36

Configuration Variables Mapping

The following diagram maps environment variables and configuration keys to the internal structures used during backend initialization.

"Natural Language Space to Code Entity Space: Configuration Mapping"

Sources: tools/environments/docker.py38-60 tools/environments/ssh.py45-51 tools/environments/daytona.py40-50

---

LocalEnvironment

The LocalEnvironment backend executes commands directly on the host machine. It is the default option and provides the lowest latency but offers no process or filesystem isolation.

Key Features

• Shell Resolution: It utilizes _popen_bash to spawn a subprocess with standard I/O setup tools/environments/base.py136-157
• Path Normalization: On Windows, it translates MSYS/Git Bash paths to native forms using _msys_to_windows_path tools/environments/local.py24-50
• CWD Recovery: The environment recovers when a working directory is deleted or inaccessible by walking up to the nearest existing ancestor via _resolve_safe_cwd tools/environments/local.py154-172
• Environment Scrubbing: To prevent leaking sensitive provider keys into the local shell, it utilizes _sanitize_subprocess_env which filters out variables matching _HERMES_PROVIDER_ENV_BLOCKLIST tools/environments/local.py127-132

Sources: tools/environments/base.py136-157 tools/environments/local.py24-172

---

DockerEnvironment

The DockerEnvironment provides a security-hardened container execution environment.

Security and Resource Limits

Hermes applies strict security flags to every container to prevent host breakout:

• Hardening: Containers are created with cap-drop ALL, no-new-privileges, and PID limits tools/environments/docker.py1-6
• Orphan Reaping: Stale containers left behind by crashed processes are removed via reap_orphan_containers, which targets containers labeled hermes-agent=1 with status=exited tools/environments/docker.py143-173
• Resource Constraints: Supports CPU, memory, and disk limits configured during initialization tools/environments/docker.py42-44

Configuration and Mounting

• Auto-Mount: Can automatically mount the host's current working directory to the container's /workspace tools/environments/docker.py50-52
• Environment Forwarding: Allows specific host environment variables to be forwarded into the container after validation via _normalize_forward_env_names tools/environments/docker.py43-63

Sources: tools/environments/docker.py1-63 tools/environments/docker.py143-173

---

SSHEnvironment

The SSHEnvironment allows the agent to execute commands on a remote server.

Connection Persistence

To avoid the overhead of establishing a new SSH connection for every tool call, Hermes uses ControlMaster tools/environments/ssh.py1-2:

• ControlPath: A local socket is created in tempfile.gettempdir() / "hermes-ssh". The filename is a stable hash of the connection triple to stay under the 104-byte Unix domain socket limit on macOS tools/environments/ssh.py53-66
• ControlPersist: The connection is kept open for 300 seconds tools/environments/ssh.py87

File Synchronization

The SSHEnvironment uses a FileSyncManager to synchronize local ~/.hermes files to the remote host tools/environments/ssh.py72-79

• Bulk Transfers: Uses a streaming tar pipe over the existing SSH connection for efficient bulk transfers via _ssh_bulk_upload tools/environments/ssh.py188-210
• Home Detection: Automatically detects the remote user's home directory by executing echo $HOME tools/environments/ssh.py117-137

Sources: tools/environments/ssh.py36-137 tools/environments/ssh.py188-210

---

SingularityEnvironment

The SingularityEnvironment (also known as Apptainer) provides containerized execution, often used in HPC environments. It leverages an overlay filesystem for persistent changes within the container.

Key Features

• Scratch Directory: Uses a dedicated scratch directory for temporary files and overlay storage, managed by _get_scratch_dir tools/terminal_tool.py69
• SIF Cache: Manages a cache for Singularity Image Format (SIF) files to optimize image startup tools/terminal_tool.py68-69
• Disk Usage Warning: Monitors disk usage within the scratch directory and issues warnings if it exceeds DISK_USAGE_WARNING_THRESHOLD_GB tools/terminal_tool.py115-149 This helps prevent issues in environments with strict storage quotas.

Sources: tools/terminal_tool.py65-69 tools/terminal_tool.py115-149

---

ModalEnvironment

The ModalEnvironment integrates with Modal.com to provide cloud-based sandboxed execution. It supports both direct Modal usage and managed gateway modes.

Key Features

• Modal Mode Coercion: Uses coerce_modal_mode to determine the appropriate Modal execution context (e.g., direct or managed) tools/terminal_tool.py71-75
• Credential Handling: Checks for direct Modal credentials using has_direct_modal_credentials tools/terminal_tool.py72
• Managed Tools: Integrates with managed_nous_tools_enabled to leverage Nous Research's managed tool gateway for simplified setup tools/terminal_tool.py73
• Backend State Resolution: resolve_modal_backend_state determines the operational state of the Modal backend, including potential unavailability messages tools/terminal_tool.py74

Sources: tools/terminal_tool.py71-75

---

DaytonaEnvironment

The DaytonaEnvironment integrates with the Daytona cloud development platform tools/environments/daytona.py30-36

Sandbox Lifecycle

• Persistence: Supports persistent sandboxes that are resumed across sessions tools/environments/daytona.py89-101
• Resource Management: Translates memory and disk requirements into GiB tools/environments/daytona.py76-84
• Bulk I/O: Implements _daytona_bulk_upload using sandbox.fs.upload_files() for optimized multi-file transfers tools/environments/daytona.py154-181

Sources: tools/environments/daytona.py30-181

---

Code Execution Sandbox (PTC)

The execute_code tool allows the LLM to write Python scripts that call Hermes tools via RPC, collapsing multi-step tool chains into a single turn tools/code_execution_tool.py3-7

Architecture

The system supports two RPC transports depending on the backend:

• Local (UDS): Uses Unix Domain Sockets. The parent process starts an RPC listener thread, and the child script calls tools via a generated hermes_tools.py stub tools/code_execution_tool.py10-14
• Remote (File-based): For Docker/SSH/Modal backends, tool calls are written as request files. A polling thread on the parent reads these via env.execute(), dispatches them, and writes response files back to the remote environment tools/code_execution_tool.py16-22

Resource Limits

Default limits are enforced to prevent runaway scripts:

• DEFAULT_TIMEOUT: 300 seconds tools/code_execution_tool.py73
• DEFAULT_MAX_TOOL_CALLS: 50 calls tools/code_execution_tool.py74
• MAX_STDOUT_BYTES: 50 KB tools/code_execution_tool.py75

Sources: tools/code_execution_tool.py3-75

---

Background Process Management

The ProcessRegistry manages background processes spawned via terminal(background=true) tools/process_registry.py4-10

Features

• Output Buffering: Maintains a rolling 200KB window of process output in ProcessSession.output_buffer tools/process_registry.py58
• Watch Patterns: Triggers agent notifications when process output matches specific regex patterns tools/process_registry.py120-121
• Crash Recovery: Persists process metadata to processes.json for gateway reset protection tools/process_registry.py55-56
• Interactive Input: Supports writing to the stdin of a running process via write_stdin, handling platform-specific differences (e.g., str for Windows PTY, bytes for POSIX PTY) tests/tools/test_process_registry.py68-104
• Terminal Closing: The request_close_terminal method allows the UI to signal that a terminal view should be closed without necessarily killing the underlying process, especially in desktop environments tests/tools/test_process_registry.py155-170

Sources: tools/process_registry.py1-139 tests/tools/test_process_registry.py68-104 tests/tools/test_process_registry.py155-170

---

Execution Flow and Data Path

The following diagram illustrates the path a command takes from the agent to a specific backend implementation.

"Code Entity Space: Command Execution Flow"

Sources: tools/environments/base.py136-157 tools/environments/daytona.py30-40 tools/environments/ssh.py36-43 tools/environments/docker.py1-6 tools/terminal_tool.py9-13