Terminal Backends: Local, Docker, and SSH Execution

What a Terminal Backend Actually Controls

Every earlier module assumed Hermes could run shell commands, read and write files, and execute code, without asking where that execution actually happens. That’s the terminal backend’s job: it determines whether the agent’s hands and feet are your local machine, an isolated container, a remote server, or (next lesson) a serverless sandbox.

# ~/.hermes/config.yaml
terminal:
  backend: "local"   # local | docker | ssh | modal | daytona | singularity

This is a deliberately separate axis from model choice and tool configuration. You can run the exact same agent, same model, same MCP servers, against three different terminal backends depending on the trust level of the task at hand.

Local

The default. Commands run directly on your machine, with your user permissions.

hermes config set terminal.backend local

Fastest, simplest, and appropriate when you trust the agent with the same access you’d give yourself, generally fine for personal development work, less appropriate for anything public-facing (Module 6’s messaging bots) or running unattended.

Docker

Runs the agent’s shell, file, and code-execution calls inside an isolated container instead of directly on your host.

docker version   # verify Docker is working before switching
hermes config set terminal.backend docker

If docker version fails, either fix your Docker installation or fall back to local:

hermes config set terminal.backend local

The Docker backend starts a single long-lived container on first use (docker run -d ... sleep 2h) and routes every subsequent terminal, file, and execute_code call through docker exec into that same container. This matters in practice: working-directory changes, installed packages, and files written to /workspace all carry over from one tool call to the next, across /new, /reset, and even the delegate_task sub-agents from Lesson 12, for the lifetime of the Hermes process. It behaves like a persistent development environment, just isolated from your host filesystem.

SSH

Runs commands on a remote server you control, useful for keeping execution on infrastructure you already trust, without running Hermes itself on that box.

export TERMINAL_SSH_HOST=my-server.example.com
export TERMINAL_SSH_USER=deploy
hermes config set terminal.backend ssh

Both TERMINAL_SSH_HOST and TERMINAL_SSH_USER are required; Hermes logs a clear, specific error identifying whichever one is missing if you forget one. This is the backend to reach for when you want the agent working against a specific remote environment, a staging server, a GPU box, a machine with data that shouldn’t be copied elsewhere, rather than wherever Hermes itself happens to be running.

Singularity / Apptainer

For HPC and research-computing environments where Docker isn’t available or permitted, Singularity (also known as Apptainer) offers container isolation under a different runtime:

hermes config set terminal.backend singularity

Validating Your Choice

hermes doctor

checks backend-specific requirements: Docker daemon reachability, SSH host/user variables, or Singularity availability, and reports exactly what’s missing before you discover it mid-task.

Choosing a Backend by Trust Boundary

The next lesson covers two more backends, Modal and Daytona, that add serverless persistence: an environment that behaves like Docker’s stateful container, but hibernates when idle instead of running continuously.

Exercise: switch your terminal backend to Docker, run hermes doctor to confirm it’s healthy, then ask the agent to install a small package (e.g. a Python library) and use it in a follow-up request in the same session. Confirm the package is still available without reinstalling, that persistence is the Docker backend’s defining behavior.