Execution Environments provide an abstraction layer that allows the terminal tool to execute commands in different backends, from direct local execution to isolated containers and remote cloud sandboxes. This system enables Hermes to adapt its execution strategy based on security requirements, resource constraints, and deployment scenarios.
The environment system is primarily utilized by the terminal_tool tools/terminal_tool.py23-31 and file tools, which delegate to the terminal's execution layer. This abstraction ensures that the agent can interact with the filesystem and shell consistently, regardless of whether it is running on a developer's laptop, in a Docker container, or in a serverless cloud sandbox.
The environment backend is selected via the TERMINAL_ENV environment variable tools/terminal_tool.py9-12 The _create_environment factory function tools/terminal_tool.py534-585 (called within get_or_create_env) resolves the requested environment type and instantiates the corresponding backend class.
| Backend | Value | Implementation Class | Use Case |
|---|---|---|---|
| Local | local | LocalEnvironment | Direct host execution (fastest) |
| Docker | docker | DockerEnvironment | Isolated containers with hardened security |
| SSH | ssh | SSHEnvironment | Remote execution via SSH connection |
| Modal | modal | ModalEnvironment | Serverless cloud sandboxes (scalable) |
| Daytona | daytona | DaytonaEnvironment | Cloud development workspaces |
| Singularity | singularity | SingularityEnvironment | HPC containers (research clusters) |
Sources: tools/terminal_tool.py9-12 tools/terminal_tool.py534-585
Environments are created lazily on the first command execution and cached per task_id to enable session persistence. The lifecycle is managed by global state dictionaries in tools/terminal_tool.py that track active instances and their last activity timestamps.
Environment Management Diagram
The per-task lock (_creation_locks) tools/terminal_tool.py473-476 prevents race conditions where concurrent tool calls for the same task_id would create duplicate sandboxes.
For details, see Environment Abstraction.
Sources: tools/terminal_tool.py469-476 tools/terminal_tool.py957-1031
A background cleanup thread (_cleanup_thread_worker) tools/terminal_tool.py674-753 runs every 60 seconds to terminate environments inactive for longer than TERMINAL_LIFETIME_SECONDS (default 300s). Environments with active background processes (tracked in process_registry tools/process_registry.py142) have their timestamps automatically refreshed to prevent premature termination tools/terminal_tool.py738-753 The system also includes disk usage monitoring tools/terminal_tool.py123-149 to warn when scratch space exceeds thresholds.
Sources: tools/terminal_tool.py674-753 tools/terminal_tool.py123-149 tools/process_registry.py142
The system supports granular control over container resources and images via environment variables.
| Variable | Default | Description |
|---|---|---|
TERMINAL_DOCKER_IMAGE | nikolaik/python-nodejs:python3.11-nodejs20 | Default Docker image tools/terminal_tool.py537 |
TERMINAL_TIMEOUT | 180 | Command timeout in seconds tools/terminal_tool.py552 |
TERMINAL_CONTAINER_CPU | 1 | CPU cores for containers tools/terminal_tool.py555 |
TERMINAL_CONTAINER_MEMORY | 5120 | Memory in MB tools/terminal_tool.py558 |
TERMINAL_CONTAINER_PERSISTENT | true | Enable persistent filesystem tools/terminal_tool.py564 |
Sources: tools/terminal_tool.py534-585
To prevent sensitive Hermes credentials (like LLM API keys) from leaking into the execution environment, the LocalEnvironment and DockerEnvironment implement a blocklist system tools/environments/local.py21-23 This is critical for preventing external CLI tools from inheriting Hermes' operational secrets.
Secret Sanitization Flow
The blocklist includes explicit provider keys and general credential-shaped patterns tools/environments/local.py21-23 Users can override this using the _HERMES_FORCE_ prefix for specific variables tools/environments/local.py95 On Windows, essential OS variables like SYSTEMROOT and COMSPEC are preserved to ensure basic process spawning remains functional tools/environments/local.py228-245
Sources: tools/environments/local.py95-228 tools/environments/docker.py21-23
All Hermes execution backends inherit from the BaseEnvironment abstract class tools/environments/base.py213 This base class defines a unified spawn-per-call model where every command spawns a fresh bash -c process but maintains state through session snapshots tools/environments/base.py3-7
_sanitize_subprocess_env to filter secrets tools/environments/local.py228cap-drop ALL, no-new-privileges, and PID limits tools/environments/docker.py1-6 It includes an orphan reaper to clean up stale containers tools/environments/docker.py143-173ControlMaster for connection persistence tools/environments/ssh.py85-87 and FileSyncManager tools/environments/ssh.py72-79 to sync credentials and skills to the remote host.modal.Sandbox tools/environments/modal.py164 Supports filesystem snapshots that are restored on subsequent sessions for the same task_id tools/environments/modal.py196-202Execution Interface Diagram
For details, see Backend Implementations.
Sources: tools/environments/base.py tools/environments/local.py tools/environments/docker.py tools/environments/ssh.py tools/environments/daytona.py tools/environments/modal.py
Remote backends (SSH, Daytona, Modal) lack direct access to host files. The FileSyncManager ensures that necessary credentials, skills, and cache files are available in the sandbox.
sandbox.fs.upload_files() for batched multipart POST tools/environments/daytona.py160-180sandbox.upload_file() tools/environments/modal.py265-273Sources: tools/environments/file_sync.py tools/environments/ssh.py188-195 tools/environments/daytona.py160-180 tools/environments/modal.py265-273
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.