Hermes Terminal Backends

Summary

The Hermes Agent supports six distinct execution backends that determine where shell commands are executed. These range from high-performance local execution to strictly sandboxed Docker containers and remote cloud environments, allowing for a configurable balance between security, persistence, and resource access.

Details

The terminal tool in Hermes is the primary interface for the agent to interact with operating systems. To manage security and environmental requirements, Hermes abstracts the execution layer into several backends.

Backend Types and Isolation

Backend	Isolation Level	Primary Use Case
local	None	Development and trusted local tasks. Default behavior.
docker	Full Namespaces	Safe sandboxing and reproducible CI/CD environments.
ssh	Network Boundary	Remote development or keeping the agent away from its own source code.
modal	Cloud VM	Ephemeral or persistent cloud compute via Modal.
daytona	Container	Managed cloud workspaces with stop/resume capabilities.
singularity	Namespaces	HPC clusters where Docker is unavailable or rootless execution is required.

Docker Backend Configuration and Security

The Docker backend is the preferred method for running untrusted code. It utilizes hardened containers with the following security constraints:

• Capabilities: All Linux capabilities are dropped (--cap-drop ALL).
• Privileges: No new privileges are allowed (--security-opt no-new-privileges).
• Process Limits: A PID limit of 256 prevents fork bombs.
• Filesystem: Uses size-limited tmpfs for /tmp, /var/tmp, and /run.

Configuration is managed via ~/.hermes/config.yaml. Key parameters include:

• docker_image: Defaults to nikolaik/python-nodejs:python3.11-nodejs20.
• docker_mount_cwd_to_workspace: If true, bind-mounts the current host directory to /workspace.
• docker_forward_env: A list of environment variables (e.g., GITHUB_TOKEN) to pass into the container.
• container_persistent: If true, the filesystem state is kept between sessions.

SSH and Remote Backends

The ssh backend executes commands on a remote server, requiring TERMINAL_SSH_HOST and TERMINAL_SSH_USER environment variables. It features connection reuse with a 5-minute keepalive and supports a persistent shell.

Cloud-based backends like Modal and Daytona provide serverless or managed workspace execution. Modal supports filesystem snapshots tracked in ~/.hermes/modal_snapshots.json, while Daytona manages workspaces with a 10GiB disk limit and the ability to stop/resume instances named hermes-{task_id}.

Persistent Shell Behavior

Hermes can maintain a single long-lived bash process across multiple tool calls, preserving the working directory, shell variables, and exported environment variables.

• Default State: Enabled by default for ssh, disabled for local.
• Override: Can be forced via TERMINAL_LOCAL_PERSISTENT=true.
• Fallback: Commands requiring stdin_data or sudo automatically fall back to one-shot execution mode because the persistent shell’s input stream is reserved for the IPC protocol.

Resource Limits

For all containerized backends (docker, modal, daytona, singularity), Hermes allows explicit resource capping:

• container_cpu: Default 1 core.
• container_memory: Default 5120 MB (5GB).
• container_disk: Default 51200 MB (50GB).

Related

• Hermes Agent
• Security Boundary
• sokrates-ctl
• NixOS