Hermes Agent MCP for Claude Opus 4.8: build a compliant local code sandbox in 2026

Hermes Agent (NousResearch/hermes-agent) ships first-class Model Context Protocol (MCP) integration: you declare mcp_servers in ~/.hermes/config.yaml, Hermes spawns stdio servers such as @modelcontextprotocol/server-filesystem, and the model receives tools named with the mcp_<server>_<tool> prefix. Pair that with Claude Opus 4.8 (released May 28, 2026; API id claude-opus-4-8) and a local code sandbox where the agent can read a scoped repo, run npm test, and attempt guarded auto-fix loops without touching your entire home directory.

Official references: Hermes MCP user guide, MCP docs in the repo, and modelcontextprotocol.io. If you are comparing harnesses on Apple hardware, read Hermes Agent vs OpenClaw on macOS and Mac mini M4. After long sessions inflate context, tune memory with Hermes trajectory_compressor on Mac mini M4. For 24/7 messaging gateways, see Hermes Agent Docker on a cheap VPS with Telegram.

Disclosure: MacHTML offers optional cloud Mac mini rental for staging agent configs; this guide focuses on MCP and sandbox patterns and does not require a Mac.

Why MCP with Hermes in the Claude Opus 4.8 era

Before MCP, agents either pasted whole repositories into context or ran unconstrained shell commands on the host. Both patterns fail compliance reviews. MCP gives you a contractual tool surface: a filesystem server exposes only directories you list; Hermes maps each tool as mcp_<server>_<tool> so operators can audit calls in logs. When Anthropic shipped Claude Opus 4.8 on May 28, 2026, longer reasoning traces and stronger patch quality made “read → test → fix” loops practical—but only if the harness limits blast radius.

Hermes already runs skills, cron, and gateways from one ~/.hermes tree. Adding MCP means you do not fork a second agent framework for document search or repo introspection. You keep terminal.backend: docker for shell execution while MCP handles structured reads and metadata. That split is the core of a compliant local code sandbox: MCP for observation, Docker terminal for mutation, and tools.include / tools.exclude for explicit allowlists.

Opus 4.8 rewards agents that can iterate on failing tests. A typical loop: list project files via MCP, read the failing spec, propose a patch through the terminal tool, run npm test, and stop if tests pass or a retry budget is exhausted. Without scoped MCP roots, the model might read ~/.ssh or cloud credentials; with server-filesystem roots pointed at /srv/sandbox/app only, those paths never appear in the tool schema.

MCP also decouples upgrades. When Nous Research publishes a new Hermes image, your mcp_servers block survives as long as stdio command paths remain valid. Reload servers with /reload-mcp in Telegram or CLI chat without restarting the gateway—critical when you iterate on a staging Mac mini before promoting config to a VPS.

You can browse reviewed entries with hermes mcp install or hand-write stdio commands. Hermes also supports hermes mcp serve so other MCP hosts can call Hermes tools while Hermes calls filesystem MCP—useful when Claude Code and a Telegram gateway share one sandbox policy.

Finally, MCP interoperates with the wider ecosystem: community servers for Git, browsers, and databases attach the same way. Start with filesystem scope for code sandboxes; add servers only after security review.

Compliance teams often ask for evidence. MCP tool calls are discrete JSON-RPC operations with parameters you can log—unlike opaque “run shell” transcripts. Pair those logs with Docker terminal audit trails and you have a defensible story for internal AI governance reviews in 2026.

Developers migrating from IDE copilots should expect different ergonomics: Hermes is session-oriented and gateway-friendly. You might drive the same sandbox from Telegram on a phone while a Mac mini runs the gateway, or from a local CLI during feature work. The MCP config travels with ~/.hermes; the interface changes, not the security boundary.

Architecture: Hermes, MCP servers, and Docker terminal

Developer → Hermes CLI / gateway chat
              ↳ config.yaml
                   ├─ model: claude-opus-4-8
                   ├─ mcp_servers (stdio) → @modelcontextprotocol/server-filesystem
                   ├─ tools.include / tools.exclude
                   └─ terminal.backend: docker  → sandbox container for bash/npm
              ↳ Tool names exposed to model: mcp_sandbox_fs_read_file, run_terminal_cmd, …

Hermes loads mcp_servers at startup (and on /reload-mcp). Each entry specifies a command—often npx -y @modelcontextprotocol/server-filesystem with allowed directories. The agent loop merges MCP tools with built-in tools; only entries in tools.include reach Opus 4.8 if you set an allowlist.

Tool prefix: Hermes namespaces MCP tools so logs show which server answered. Expect names like mcp_sandbox_fs_read_file rather than generic read_file. Use hermes mcp list on the host to verify registration after editing YAML.

Terminal backend: Set terminal.backend: docker in config.yaml (or TERMINAL_BACKEND=docker in Docker deployments) so npm test, git, and formatters run inside an ephemeral or persistent sandbox container—not on the gateway host kernel. Mount your repo into both the MCP root list and the container workspace for consistent paths.

Guarded auto-fix: Combine allowlists with skill instructions: cap retry count, forbid rm -rf, require diff review for production branches. Opus 4.8 can follow those guardrails when they are repeated in the system prompt and skill metadata.

Layer	Responsibility	Typical config
MCP filesystem	Read/list/search within roots	mcp_servers + server-filesystem paths
Hermes terminal	Run tests, apply patches	terminal.backend: docker
tools.include	Drop dangerous built-ins	Explicit tool names only
Model	Reasoning + tool choice	claude-opus-4-8

Security model for MCP + shell tools

Treat MCP roots as read boundaries, not write boundaries. The filesystem MCP server may still expose write tools depending on version—use tools.exclude to drop mcp_*_write* if policy requires read-only staging. Never point roots at ~/.hermes, ~/.ssh, or cloud credential directories.

Docker terminal isolation is mandatory for team gateways. A compromised prompt should not escape to the host package manager. Pin CPU and memory limits like production gateway guides. One gateway per ~/.hermes mount remains the rule—duplicate gateways corrupt sessions.

Rotate API keys in ~/.hermes/.env separately from MCP config. Restrict who can run /reload-mcp and admin slash commands on Telegram. For Opus 4.8, monitor token burn during auto-fix loops; pair with /compress or trajectory compression when contexts exceed budget.

Audit logs: enable verbose tool logging during staging. Verify each mcp_* call targets paths under your repo root. Reject skills that instruct the model to exfiltrate environment variables.

Secrets belong in .env files excluded from MCP roots. If you must read .env.example, whitelist that single file rather than the parent directory. For monorepos, scope MCP to the package subdirectory under active development so Opus 4.8 does not traverse unrelated services.

Network egress from sandbox containers should default deny except package registries required for npm test. Document allowed domains in your runbook appendix so security reviewers can sign off without reading every skill file.

Step-by-step runbook

1. Install Hermes with MCP extra — Use the install script, then add the MCP optional dependency. Confirm npx and Node 20+ on PATH.

   curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
   source ~/.zshrc
   cd ~/.hermes/hermes-agent && uv pip install -e ".[mcp]"
   hermes doctor

2. Pin Claude Opus 4.8 — Set the model id Anthropic documented for Opus 4.8. Verify with /model in chat after adding your API key to ~/.hermes/.env.

   # ~/.hermes/.env
   ANTHROPIC_API_KEY=sk-ant-...
   # ~/.hermes/config.yaml excerpt
   models:
     default: claude-opus-4-8

3. Create an isolated sandbox directory — Clone a disposable test repo; run npm ci on the host or inside Docker.

   sudo mkdir -p /srv/sandbox/app
   sudo chown "$USER":"$USER" /srv/sandbox/app
   git clone https://github.com/your-org/your-test-repo.git /srv/sandbox/app
   cd /srv/sandbox/app && npm ci

4. Register the filesystem MCP server — Edit ~/.hermes/config.yaml with scoped roots and tools.include.

   mcp_servers:
     sandbox_fs:
       command: "npx"
       args:
         - "-y"
         - "@modelcontextprotocol/server-filesystem"
         - "/srv/sandbox/app"
       tools:
         include:
           - read_file
           - list_directory
           - search_files

5. Enable Docker terminal backend — Align MCP root and container bind mount.

   terminal:
     backend: docker
     container_persistent: true
     container_memory: 5120
     docker_volumes:
       - "/srv/sandbox/app:/workspace"

6. Verify MCP registration — From the host:

   hermes mcp list
   # In chat: /reload-mcp

7. Run the npm test loop — Prompt explicitly: read failing test output via MCP, patch in sandbox, rerun npm test, stop after N attempts.

   hermes chat "List top-level files, run npm test in /workspace, fix failing tests under src/ only, max 3 attempts."

8. Promote config to gateway or VPS — Copy the validated ~/.hermes tree to Docker bind mount per the VPS Telegram guide. Keep TERMINAL_BACKEND=docker and re-run hermes mcp list inside the container.

Document the retry budget and forbidden commands in a skill file checked into the repo so every teammate inherits the same guarded auto-fix policy. Re-run the runbook after each Hermes image upgrade because MCP server CLIs occasionally add new tool names that require tools.include updates.

Troubleshooting

MCP tools missing after config edit

Run /reload-mcp or restart the CLI session. Confirm npx can launch @modelcontextprotocol/server-filesystem manually from the same user. Check hermes mcp list for spawn errors. Typos in mcp_servers keys change the mcp_* prefix—update tools.include to match.

npm test passes locally but fails in Docker terminal

Align mount paths: MCP may read /srv/sandbox/app while the container sees /workspace. Use the same host path in docker_volumes and run tests with /workspace inside the container. Install Node inside the sandbox image or use a persistent container where dependencies are preinstalled.

Opus 4.8 ignores guardrails and edits outside scope

Remove write MCP tools from tools.include, narrow filesystem roots, and add skill text that forbids paths outside the repo. Switch to read-only MCP for production branches; use terminal only in ephemeral sandboxes.

OAuth MCP login hangs during a live session

Do not rely on short config auto-reload windows. Exit the session, run hermes mcp login <server> from a fresh terminal, then /reload-mcp after credentials are stored.

For harness comparison, memory compression, and 24/7 Telegram on a VPS, see Hermes Agent vs OpenClaw on macOS and Mac mini M4, Hermes trajectory_compressor on Mac mini M4, and Hermes Agent Docker on a cheap VPS with Telegram. Before you upsize silicon, compare M5 Pro Fusion vs M6 2nm leaks for bandwidth and buy-now vs wait. This page adds a Model Context Protocol (MCP) filesystem sandbox tuned for Claude Opus 4.8 coding loops.

FAQ

Do MCP tools replace Hermes terminal tools?

No. MCP filesystem tools complement the built-in terminal. Keep terminal.backend: docker for shell commands and use MCP for scoped read and list operations.

What model id should I set for Claude Opus 4.8?

Use claude-opus-4-8 in config.yaml or /model after Anthropic’s May 28, 2026 release announcement.

How do I reload MCP without restarting the gateway?

Send /reload-mcp in chat or run hermes mcp list from the host to verify servers registered under mcp_servers.

Can I run this sandbox on a VPS?

Yes. Mount ~/.hermes, enable TERMINAL_BACKEND=docker, and scope MCP to the project directory on the bind mount. See the Docker VPS article for gateway hardening.

How does tools.include interact with MCP?

When tools.include is set, only listed tools are exposed to the model. Add each mcp_* tool name reported by hermes mcp list; omit built-ins you do not want in production.

Is Hermes MCP the same as OpenClaw MCP guides on MacHTML?

No. OpenClaw articles focus on Node gateways and remote Mac automation. This guide covers Hermes-native mcp_servers, tool prefixes, and /reload-mcp on NousResearch/hermes-agent.