hermes-gpt

hermes-gpt is a standalone MCP sidecar for Hermes Agent. It imports selected local Hermes Agent internals at runtime and exposes them to MCP clients without modifying Hermes Agent source files.

This is a local-dev release. It is not a hosted service, not a fork of Hermes Agent, not a generic remote dev container, and not a replacement for DevSpace.

Security posture

By default, hermes-gpt is designed for a trusted local machine:

• HTTP binds to 127.0.0.1 by default.
• Tools advertise noauth so ChatGPT can use Developer Mode with No Authentication; optional bridge auth is enforced by the HTTP endpoint itself.
• Public HTTP can be protected with HERMES_GPT_HTTP_TOKEN using query parameters or an HTTP Bearer token header.
• Reads are limited by HERMES_GPT_READ_ROOTS and writes are confined to HERMES_GPT_SAFE_ROOT.
• Write is create-only; patch, terminal execution, memory writes, and session search are disabled or hidden by default.

Do not expose this server publicly without HERMES_GPT_HTTP_TOKEN or an equivalent outer authentication layer. Prefer a stable Cloudflare named tunnel or reserved ngrok domain over quick trycloudflare.com URLs when ChatGPT connector URLs must survive restarts.

Prerequisites

• Python 3.10+
• A local Hermes Agent install
• MCP Python SDK and Uvicorn

Install dependencies:

cd ~/hermes-gpt
python -m pip install -r requirements.txt

Local MCP clients

Stdio mode is for local MCP clients that support subprocess MCP servers:

cd ~/hermes-gpt
python server.py

Example client command:

{
  "command": "python",
  "args": ["C:\\Users\\asimo\\hermes-gpt\\server.py"]
}

Local HTTP

HTTP mode uses FastMCP streamable HTTP:

cd ~/hermes-gpt
python server.py --http --host 127.0.0.1 --port 7677

Local endpoint:

http://127.0.0.1:7677/mcp

If you bind to anything other than loopback in the default local-dev profile, the server prints a warning. This warning means the configuration is not release-safe.

ChatGPT local testing

ChatGPT developer mode expects a remote MCP endpoint. Do not enter a localhost URL such as http://127.0.0.1:4750; ChatGPT fetches the MCP configuration through its connector path, where 127.0.0.1 is not your machine.

For short local testing only:

cd C:\Users\asimo\hermes-gpt
python server.py --http --host 127.0.0.1 --port 4750

In another terminal:

& "C:\Program Files (x86)\cloudflared\cloudflared.exe" tunnel --url http://127.0.0.1:4750 --http-host-header 127.0.0.1:4750

For token-protected local testing, start the server with a stable bridge token:

HERMES_GPT_HOST_IDENTITY=Dell \
HERMES_GPT_HTTP_TOKEN=placeholder-token \
HERMES_GPT_SAFE_ROOT=/path/to/sandbox \
HERMES_GPT_READ_ROOTS=/path/to/read/root \
HERMES_GPT_ENABLE_WRITE=1 \
python server.py --http --host 127.0.0.1 --port 4750

In ChatGPT, configure:

• Protocol: Streaming HTTP
• MCP server URL: https://<your-host>/mcp?hermes_token=placeholder-token
• Authentication: No Authentication

The token is intentionally part of the server URL because many ChatGPT connector flows cannot set custom headers. Do not publish real connector URLs. Remove and recreate the connector if ChatGPT cached older tool metadata.

Tool gates

Default visible tools:

• hermes_server_config() — host identity, read roots, write root, auth status, and safety modes without revealing token values.
• hermes_self_test() — local bridge diagnostics for roots, token, write sandbox, and sensitive-path blocking.
• hermes_tree(path=".", depth=2, limit=100) — shallow directory tree.
• hermes_read_file(path, offset=1, limit=500)
• hermes_search_files(pattern, target="content", path=".", file_glob=None, limit=50); target="path" is accepted as a filename-search alias.
• hermes_list_files(path=".", limit=50)
• hermes_view_image(path) — returns PNG/JPEG/WebP/GIF as MCP image content.
• hermes_skill_list()
• hermes_skill_view(name)

Opt-in tools and actions:

Capability	Env var	Default
Create-only sandbox write	HERMES_GPT_ENABLE_WRITE=1 + HERMES_GPT_SAFE_ROOT=/path/to/sandbox	Hidden
Memory add, replace, remove	HERMES_GPT_ENABLE_MEMORY_WRITE=1	Disabled
Session search	HERMES_GPT_ENABLE_SESSION_SEARCH=1	Hidden
Terminal command execution	HERMES_GPT_ENABLE_TERMINAL=1	Hidden

Terminal timeout is capped at 120 seconds even when enabled.

CodexPro-inspired bridge knobs

Setting	Purpose
HERMES_GPT_HOST_IDENTITY	Human label such as Dell or Pedro returned by hermes_server_config.
HERMES_GPT_HTTP_TOKEN	Enables query/Bearer token enforcement on HTTP/SSE transports.
HERMES_GPT_REQUIRE_HTTP_TOKEN=1	Reject HTTP traffic if no token is configured.
HERMES_GPT_READ_ROOTS	os.pathsep-separated read-only roots visible to read/search/tree/image tools.
HERMES_GPT_PATH_ALIASES	Public-to-local path aliases, e.g. /linus1=/home/imac-hermes/linus1/shared.
HERMES_GPT_SAFE_ROOT	The only directory where write tools may create files.

See HERMESPRO_PLAN.md for Dell/Pedro deployment examples and the hybrid design rationale.

Remote profile

--profile remote is intended for public/tunneled testing. Configure HERMES_GPT_HTTP_TOKEN before exposing it through a public URL:

HERMES_GPT_HTTP_TOKEN=placeholder-token python server.py --http --profile remote --host 127.0.0.1 --port 7677

For temporary no-auth experiments only, you can bypass the remote-profile guard with both:

HERMES_GPT_UNSAFE_REMOTE_NOAUTH=1
python server.py --http --profile remote --i-understand-this-is-unsafe

Do not use the no-auth bypass for release.

Release checklist

Before publishing:

• No *.pem files.
• No *.log or *.err.log files.
• No __pycache__/ or *.pyc.
• python -m py_compile server.py passes.
• pytest passes.
• Server binds to loopback by default.
• Terminal, write tools, memory writes, and session search are disabled by default.

Current capability notes

The feasibility probe passed in this environment:

• Hermes source root: C:\Users\asimo\AppData\Local\hermes\hermes-agent
• File tools: available
• Terminal tool: available, gated by HERMES_GPT_ENABLE_TERMINAL=1
• Memory tool: available
• Skill discovery: available through local and bundled skill directories
• Session search: available through SessionDB.search_messages
• FastMCP stdio: available
• FastMCP streamable HTTP: available

See FEASIBILITY.md for probe details and exact signatures.

License

MIT. See LICENSE.