The terminal and process Tools: Power and Risk

+15 Mana ✨
Hermes Security and Approvals(DOCUMENTATION)

Introduction

The terminal tool runs shell commands. That sentence sounds modest, and yet terminal is the single most powerful tool Hermes ships with. It can install packages, run tests, push to git, format disks, and call any command line tool you have. It is also the tool most likely to wreck your machine if used carelessly. The process tool is its companion for long-running tasks.

This pair sits at the top of the risk gradient: execute.

Key Concepts

  • Execute operation: A tool call that runs arbitrary code. The blast radius is whatever the underlying shell can do.
  • terminal: One-shot shell commands. The filesystem persists between calls.
  • process: Manages long-running background processes: start, poll logs, send input, wait, kill.
  • Dangerous command approval: Hermes intercepts terminal calls that match a dangerous pattern and prompts for approval (Section 3.5).

Real World Context

When you ask Hermes to run the test suite, that is terminal({ command: 'pnpm test' }). When you ask it to start the dev server in the background and watch for errors, that is process({ action: 'start', command: 'pnpm dev' }) followed by process({ action: 'logs', ... }). Without these two tools, Hermes is read-only and cannot actually build anything. With them, it can do almost anything you can do at the command line.

Deep Dive

The terminal tool runs a command, waits for it to finish, and returns stdout, stderr, and the exit code. Two important properties:

  1. The filesystem persists. A command that creates /tmp/foo.txt is observable from the next call. This is what makes multi-step terminal workflows possible.
  2. The environment varies by backend. Hermes can run terminal commands on the local machine, over SSH, or inside a Docker, Singularity, Modal, Daytona, or Vercel sandbox. The sandbox choice is the difference between affecting your real machine and affecting an ephemeral container.

The process tool exists because some commands run forever (pnpm dev, a Python server). With terminal alone, you would wait forever for the call to return. process decouples lifecycle from a single call: it starts the command, returns a handle, and lets the agent poll logs, send input, or kill the process later.

What makes terminal and process high-risk:

  • They run arbitrary code. Whatever the shell can do, the agent can do.
  • They can mutate anything reachable from the shell. Files, databases (via clients), remote services (via curl, ssh, gh).
  • They have a blast radius set by the backend, not the tool. A terminal call on the local backend can wipe ~; the same call inside a Docker backend can wipe only the container.

Hermes's response to this is the approval system (covered in Section 3.5):

  • Most commands run without approval.
  • Dangerous patterns (recursive deletes, formatting, piping web content to a shell) trigger an approval prompt.
  • A hardline blocklist refuses some commands regardless of approval (rm -rf /, fork bombs, disk zeroing).
  • The --yolo flag or /yolo toggle bypasses the prompt for the rest of the session (but not the hardline blocklist).

When running Hermes in a container backend, the dangerous-command check is skipped because the container itself is the security boundary.

Common Pitfalls

  1. Forgetting the backend matters more than the command: rm -rf node_modules is fine in a container, recoverable on a clean repo, and devastating on a directory with uncommitted work. The same call. Different blast radius.
  2. Using terminal for things a safer tool could do: cat should be read_file, grep should be search_files, sed -i should be patch. Reach for terminal last.

Best Practices

  1. Run gateways in a container backend: When Hermes is exposed to remote users (Discord, Telegram), set terminal.backend: docker so any terminal call has a contained blast radius.
  2. Audit dangerous command approvals: Read the prompt carefully. If you find yourself approving the same dangerous pattern often, consider adding it to your command allowlist deliberately.

Summary

  • terminal runs shell commands. process manages long-running background processes.
  • Together they form the execute tier of the risk gradient.
  • Blast radius is set by the backend: local, SSH, or container.
  • Hermes wraps them in an approval system to catch dangerous patterns before they run.

Code Examples

yaml
# One-shot command via terminal
tool_call:
  name: terminal
  arguments:
    command: pnpm test --filter=auth

# Long-running dev server via process
tool_call:
  name: process
  arguments:
    action: start
    command: pnpm dev
    name: dev-server

# Later, check the logs without blocking
tool_call:
  name: process
  arguments:
    action: logs
    name: dev-server
    tail: 50
✓ Completed