What a terminal backend decides
When Hermes runs a shell command, the terminal backend decides where that command actually executes. The agent itself (its reasoning, memory and config) stays wherever you installed Hermes; only the commands move. You choose with terminal.backend in ~/.hermes/config.yaml, and the documented options are local, docker, ssh, modal, daytona, vercel_sandbox and singularity. The default is local, and commands time out after terminal.timeout seconds (180 by default).
This choice matters more than it looks, because it changes both your safety boundary and how approval prompts behave.
The options at a glance
- local: commands run directly on your machine as your user. No isolation, but full access to your real files and tools. Dangerous-command approval checks are active.
- docker: commands run inside a long-lived container (by default one container shared across sessions). The container drops Linux capabilities, sets no-new-privileges and limits processes. Approval checks are skipped because the container is treated as the boundary.
- ssh: commands run on a remote machine. Connection details come from environment variables (TERMINAL_SSH_HOST and TERMINAL_SSH_USER are required; TERMINAL_SSH_PORT and TERMINAL_SSH_KEY are optional). Approval checks stay on.
- modal and daytona: hosted cloud sandboxes, needing MODAL_TOKEN_ID/MODAL_TOKEN_SECRET or DAYTONA_API_KEY respectively.
- vercel_sandbox: Vercel's sandbox, needing VERCEL_TOKEN, VERCEL_PROJECT_ID and VERCEL_TEAM_ID.
- singularity: Apptainer/Singularity containers, common on shared research clusters; requires apptainer or singularity on your PATH.
What persists and what doesn't
For container and cloud backends, persistence is about files, not running processes. Docker reuses one container by default (container_persistent: true). Modal snapshots and restores the filesystem; Daytona stops and resumes sandboxes rather than deleting them. The docs are explicit that persistence "does not promise that the same live sandbox, PID space, or background processes will still be running later." If your workflow depends on a long-running server inside the sandbox, plan to restart it.
Checkpoints, Hermes's optional pre-edit snapshots, are not available on container backends at all, so /rollback cannot help you there.
How to choose
A simple rule of thumb from the docs' security guidance: if you are working on your own projects at your own desk, local is the most convenient and the approval prompts are your safety net. If you are running untrusted code, letting a bot accept messages from other people, or running unattended jobs, move commands into a container. The official tips go as far as recommending docker for untrusted code so that destructive commands stay inside the container, and the production checklist lists terminal.backend: docker alongside resource limits and a fixed terminal.cwd.
Pick ssh when the work has to happen on a specific remote server, such as a build box or a home server, and you want Hermes's own state to stay on your laptop. Pick a cloud sandbox when you don't want to maintain Docker yourself, or need disposable environments.
Two things that are easy to confuse
Running Hermes in Docker is different from using Docker as a terminal backend. The official hermes-agent image runs the whole agent in a container with your data mounted at /opt/data; the docker backend keeps Hermes on the host and sends only commands into a sandbox container. You can combine them, but configure them separately.
Profiles are not sandboxes either. A separate profile gives you separate config and memory, but on the local backend the agent still has your user account's file access. If isolation is the goal, the backend is what provides it.
Common setup snags
- Docker backend not connecting: run docker info, add your user to the docker group (sudo usermod -aG docker $USER, then newgrp docker) and test with docker run hello-world.
- Tools such as node missing on the local backend: Hermes takes its environment from a login shell; list extra init files such as
~/.nvm/nvm.shunder terminal.shell_init_files. - Secrets: variables whose names contain KEY, TOKEN, SECRET or PASSWORD are stripped from child processes. Pass specific ones through with terminal.env_passthrough.
Related guides
- Where Hermes Agent runs: host vs work environment
- Hermes Agent security: approvals, allowlists, sandboxing
- Hermes Agent terminal can't find files or programs
- Hermes Agent permissions for real workflows
Primary sources
Spotted something wrong or out of date? Tell us on X at @HermesWatcher (opens in a new tab) and we will fix it.
New Hermes Agent updates every day on X. Follow @HermesWatcher