Hermes Terminal Backends: Choose and Troubleshoot Where Commands Run

A Hermes terminal backend decides where every shell command, code execution, file operation, package install, and test actually runs. The effective backend may be your Mac or Linux host, a Docker sandbox, an SSH server, Modal, Daytona, or a Singularity/Apptainer environment. Choosing the wrong one can make a healthy agent look broken because it sees the wrong files, network, credentials, or runtime.

This guide owns one job: choose the right Hermes terminal backend, prove which backend is active, and diagnose cases where Hermes appears to use Docker even though config.yaml says local.

The six backend choices#

Local#

local runs commands directly on the Hermes host. It is the fastest choice for a trusted personal machine and the easiest way to work on an existing local repository. It also has the broadest blast radius: the agent can touch files and commands available to the Hermes user. Use OS permissions, a dedicated profile, tool approvals, and a clean Git worktree when the task is risky.

hermes config set terminal.backend local
hermes config get terminal.backend

Docker#

docker runs tool work in a container boundary. Choose it for dependency isolation, disposable builds, or tasks that should not run directly on the host. Docker must be installed and reachable by the user that actually runs Hermes. A gateway service account without Docker socket access will fail even when Docker works in your interactive shell. Continue with the Docker terminal backend guide and the Docker troubleshooting checklist.

SSH#

ssh sends tool execution to a remote machine. It is useful when the repository, GPU, database, or deployment runtime lives elsewhere. Verify host-key trust, least-privilege credentials, remote working directory, and non-interactive PATH before giving the agent a real task. Use the SSH terminal backend setup for the exact connection checklist.

Modal and Daytona#

Modal and Daytona are remote execution backends for workloads that benefit from disposable cloud compute or managed workspaces. They add provider authentication, remote lifecycle, network, and persistence boundaries. Do not choose them merely because they sound more scalable; use them when a local or SSH runtime cannot satisfy the workload. See the Modal setup guide or Daytona setup guide.

Singularity / Apptainer#

Singularity is the HPC-oriented option for environments where Docker is unavailable or inappropriate. It is useful on research clusters with scheduler, image, mount, and GPU policies. Follow the Singularity backend guide and verify the exact cluster rules before enabling unattended jobs.

Verify the effective backend#

Do not stop at the value written in config.yaml. Prove the complete path used by the active profile and process.

hermes config path
hermes config get terminal.backend
hermes doctor
hermes chat -q 'Run pwd and uname -a, then report the execution environment.'

Check five facts in the result: active profile, working directory, operating system, expected files, and expected network/runtime access. Then test one representative operation such as reading a repository file or running its smallest test. A successful config write does not prove that an old gateway process, another profile, or an environment override is not still selecting a different backend.

Why Hermes can appear stuck on Docker#

A fresh August 2026 Discord support case captured the confusing symptom precisely: hermes config get terminal.backend returned local, but terminal, execute_code, and file operations later behaved as Docker-bound. The final diagnosis was not memory injection and not an agent secretly changing infrastructure. A stale TERMINAL_ENV value was entering the long-running gateway environment during reload. The gateway reload path was fixed upstream, but the case provides a durable troubleshooting order.

1. Update first. Run hermes update, then start a new session on the updated process.
2. Confirm the active profile and config path. A correct value in one profile does not control another profile.
3. Read the configured value. Run hermes config get terminal.backend.
4. Look for environment overrides. Check the profile .env, machine-managed environment files, the service definition, and the live process environment for TERMINAL_ENV. Do not print unrelated secrets.
5. Remove duplicate sources. Prefer terminal.backend in config.yaml as the single user-level source unless an environment override is intentionally required.
6. Reload the long-running runtime. CLI sessions, dashboard/backend processes, and messaging gateways can retain old in-memory configuration.
7. Run an end-to-end proof from the same channel and profile that failed. A local shell test does not prove a Matrix, Telegram, Discord, or Desktop-backed turn uses the same environment.
8. Capture diagnostics before changing more variables. On current Hermes, hermes debug share --nous can provide a redacted diagnostics report for support.

Do not let the agent diagnose its own backend from conversational memory alone. The effective config, process environment, and real tool output are the evidence.

Local shell vs gateway service: prove both#

A common trap is testing only the interactive shell. A user service can inherit a different PATH, home directory, profile, Docker socket permission, or environment than the shell where hermes config get was run. Test the runtime from the same entry point that failed:

• CLI failure: start a new CLI session and run the proof command.
• Telegram, Discord, Matrix, or Slack failure: send the proof task through that channel after the gateway reload.
• Dashboard/Desktop failure: reconnect to the intended backend and verify the active profile before testing.
• Scheduled job failure: inspect the job's profile, provider/model pinning, last status, and delivery result as well as the terminal backend.

For Linux user services, compare the service definition and live process environment without dumping the whole environment. Filter specifically for TERMINAL_, Hermes home/profile, PATH, and the service command. Credentials should remain redacted.

Backend failure matrix#

Config says local, tools use Docker#

Update Hermes, remove unintended TERMINAL_ENV overrides, reload the actual long-running process, start a new session, and test from the original channel/profile. If it persists, capture a redacted diagnostics report before editing more files.

Docker exits before any command runs#

Confirm the effective backend is really Docker. Then verify Docker is installed, the daemon is healthy, and the Hermes user can access it. If Docker was never intended, set terminal.backend to local instead of trying to repair an unnecessary container dependency.

SSH works manually but Hermes cannot connect#

Check the non-interactive user, key path, host key, remote PATH, working directory, and whether the profile running Hermes can read the credential. A successful connection from another shell or user does not prove the Hermes process can connect.

Commands run but files are missing#

Print pwd, list the expected project root, and identify the backend before modifying mount or path config. In Docker, confirm the host path is mounted. In SSH/cloud backends, confirm the repository exists on the remote runtime.

Backend changed after an update or setup wizard#

Run hermes config get terminal.backend, inspect the config path for the active profile, and check environment overrides. Do not infer backend state from old chat history or memory. Tool/config changes may require a new session; long-running gateway or dashboard processes require a full reload.

Safe first task after switching#

Use a read-only proof before package installs or writes:

Report the current working directory, operating system, active user, and whether the expected project directory exists. Do not change files or install anything.

Then run one tiny project-specific command, such as a version check or the smallest unit test. Only after both checks pass should you allow broad package installs, deployment commands, or scheduled execution.

Self-hosted ownership vs managed outcome#

Terminal backends are one of the real operating costs of self-hosting. A local machine can sleep, Docker needs images and permissions, SSH needs credential and host maintenance, and cloud/HPC backends need provider-specific lifecycle controls. The Hermes cost calculator helps count those costs. Self-host when that control is valuable; choose FlyHermes when browser/mobile access and managed uptime matter more than owning each execution boundary.

Recommended next steps#

• Install or repair the base runtime with the Hermes Agent installation guide.
• Configure a disposable sandbox with the Docker backend guide.
• Operate a remote machine with the SSH backend guide.
• Secure an always-on host with the Hermes server hardening guide.
• Verify bot/platform symptoms with gateway troubleshooting.
• Compare the managed route on FlyHermes pricing.

Update failures can be backend failures#

When a Hermes update appears to break terminal tools, verify whether the selected backend is local, Docker, SSH, or Modal before blaming the model. Recent Docker-image and install/update threads show this exact confusion. Pair this guide with Hermes update command hangs, Docker install, and security hardening so backend changes are deliberate.

The browser and terminal can fail in different namespaces#

A local, Docker, or SSH terminal backend does not automatically place Chrome in the same network namespace. Record where Hermes, the browser daemon, and the CDP endpoint run, then test from that boundary. The Hermes browser automation troubleshooting guide explains stale ports, localhost mistakes, named-session isolation, and safe recovery.

Do not confuse the Docker backend with Docker installation#

The Docker terminal backend keeps Hermes and its gateways on the host while execution runs in a sandbox. Running the whole application in the official image is a separate architecture. The Docker vs native installation guide shows when each boundary is the better choice.