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.

What’s New in v0.3.0

v0.3.0 is the Operator Reliability Release. It makes Hermes GPT self-diagnosing, safely recoverable, and release-checkable.

• New operator diagnostics tools:

  • hermes_operator_doctor — read-only deep health check across operator, gateway, config, env, cron, skills, policy, audit, and connector surfaces.

  • hermes_operator_snapshot — single current-state summary.

  • hermes_release_doctor — release readiness checks with PASS / WARN / BLOCKED classification.

  • hermes_operator_recover — conservative dry-run-first recovery sequence.

• All operator-facing failures now return a structured error envelope: {success, ok, error, layer, code, safe_message, suggested_action, trace_id}.

• Diagnostic and recovery statuses use PASS / WARN / FAIL / UNSUPPORTED.

• Connector re-registration is explicitly reported as unsupported unless a real supported command/API exists.

• hermes_operator_recover is dry-run by default and requires apply=true for mutations.

Related MCP server: hermes-mcp

What’s New in v0.2.0

v0.2.0 adds tiered Operator / Owner Mode so trusted MCP clients can see the full Hermes GPT surface while the default posture stays safe.

• Default mode remains read-only.

• Recommended always-on connector/tunnel mode is dry_run.

• Direct mutation requires both:

  • HERMES_GPT_OPERATOR_APPLY_MODE=direct

  • the mutating tool call sets dry_run=false

• Owner Mode requires the exact break-glass acknowledgement:

  • HERMES_GPT_OWNER_ACK=I_UNDERSTAND_THIS_CAN_MUTATE_MY_MACHINE

• Operator Mode is not a sandbox.

• Do not expose publicly without real auth, VPN, Tailscale, or an equivalent private boundary.

What v0.2.0 adds:

• operator policy, status, and audit tools

• cron tools

• skill tools

• config and env tools

• gateway tools

• workspace tools

• owner tools behind explicit acknowledgement

• audit logging with hashes and lengths instead of raw prompt/content

• Hermes data-root normalization for operator profile operations

• packaging fixes so operator modules ship in the release

For the full Operator Mode guide, new-user quickstart, and tunnel safety model, see docs/operator-mode.md.

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 only for local-dev MCP clients.

• Write, patch, terminal execution, memory writes, and session search are disabled or hidden by default.

• Remote/public use should enable OAuth or another ChatGPT-compatible authentication layer before exposing write-capable tools.

Do not expose this server publicly without authentication. A temporary tunnel is acceptable only for short local testing when you understand that any enabled tool is reachable through that URL.

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\\<YOU>\\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\<YOU>\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

In ChatGPT, configure:

• Protocol: Streaming HTTP

• MCP server URL: https://<your-trycloudflare-host>/mcp

• Authentication: No Authentication

If ChatGPT only shows the old 5-tool surface, reconnect or recreate the connector and follow the workflow in docs/operator-mode.md.

Example scripts for local setup live under examples/.

ChatGPT custom app OAuth

For ChatGPT Developer Mode / MCP App setup over a public HTTPS endpoint, use OAuth instead of a raw static bearer token.

In ChatGPT, configure the connector with:

• Protocol: Streaming HTTP

• MCP server URL: https://hermes.tail6c8d50.ts.net/mcp

• Authentication: OAuth

• Registration method: User-Defined OAuth Client

• OAuth client ID: the value of HERMES_GPT_OAUTH_CLIENT_ID

• OAuth client secret: the value of HERMES_GPT_OAUTH_CLIENT_SECRET

• Authorization URL: https://hermes.tail6c8d50.ts.net/oauth/authorize

• Token URL: https://hermes.tail6c8d50.ts.net/oauth/token

• Token endpoint auth method: client_secret_post (client_secret_basic is also supported)

• Scope: hermes unless HERMES_GPT_OAUTH_SCOPE is changed

Required server environment:

HERMES_GPT_OAUTH_ENABLE=1
HERMES_GPT_OAUTH_ISSUER=https://hermes.tail6c8d50.ts.net
HERMES_GPT_OAUTH_CLIENT_ID=chatgpt-hermes-vps
HERMES_GPT_OAUTH_CLIENT_SECRET=<generated secret>
HERMES_GPT_OAUTH_REDIRECT_URI=<exact callback URL from ChatGPT>
HERMES_GPT_OAUTH_SCOPE=hermes

OAuth discovery endpoints:

https://hermes.tail6c8d50.ts.net/.well-known/oauth-protected-resource
https://hermes.tail6c8d50.ts.net/.well-known/oauth-authorization-server

/oauth/authorize is intentionally single-user: when the configured client ID and redirect URI match, it immediately issues a short-lived one-time authorization code and redirects back to ChatGPT. /oauth/token exchanges that code for an in-memory expiring bearer access token.

Keep raw terminal disabled until OAuth has been confirmed working from ChatGPT. Do not set HERMES_GPT_ENABLE_TERMINAL=1 during initial OAuth validation.

Tool gates

Default visible tools:

• hermes_read_file(path, offset=1, limit=500)

• hermes_search_files(pattern, target="content", path=".", file_glob=None, limit=50)

• hermes_memory(action="search", target="memory", content=None, old_text=None)

• hermes_skill_list()

• hermes_skill_view(name)

Opt-in tools and actions:

Terminal timeout is capped at 120 seconds even when enabled.

When HERMES_GPT_AUTH_TOKEN is set, HTTP/SSE requests require:

Authorization: Bearer ***

The root health check and CORS preflight requests remain unauthenticated. The broad HERMES_GPT_ENABLE_* flags still work for backward compatibility, but for tiered, safe operation prefer the Operator / Owner Mode tools documented below.

Hermes GPT Operator Mode

Operator / Owner Mode is a tiered control plane that lets trusted MCP clients (like ChatGPT) operate Hermes safely: cron jobs, skills, profile config wiring, safe non-secret env keys, gateway/runtime status and restart, scoped workspace edits, and (with explicit acknowledgement) owner-level command and file access.

Safety model

• Default behavior is read-only. Mutating operator tools refuse unless operator mode is explicitly enabled.

• Dry-run is the default. Even when operator mode is enabled, every mutating tool defaults to dry_run=True and returns a plan instead of mutating. To actually mutate, you must set HERMES_GPT_OPERATOR_APPLY_MODE=direct AND pass dry_run=False to the tool call.

• Direct mutation requires explicit opt-in. HERMES_GPT_OPERATOR_APPLY_MODE=direct is required for any write to happen.

• Owner Mode requires an additional explicit acknowledgement. Setting HERMES_GPT_OPERATOR_LEVEL=owner alone is not enough; you must also set HERMES_GPT_OWNER_ACK=I_UNDERSTAND_THIS_CAN_MUTATE_MY_MACHINE. Without the exact ack string, owner tools refuse.

• No secrets exposed. Config get redacts secret-looking keys; env tools never return values; skill/cron prompts are logged and surfaced only as prompt_len + prompt_sha256.

• No .env raw read/write. The denied-path policy refuses .env, auth.json, mcp-tokens/, .ssh/, .aws/, vault/, and any secret-looking filename.

• No shell=True anywhere. Every subprocess invocation uses shell=False with a fixed argv.

• No git add -A, no git push, no destructive filesystem operations. Workspace run_test only allows a conservative allowlist (pytest, ruff, mypy, npm test/lint, git status/diff). Owner run_command blocks catastrophic patterns (rm -rf /, del /s, format, curl | bash, git push --force, git add -A, git add ., anything touching .env/vault/token/.ssh).

• Operator Mode is not a sandbox. Use OS-level isolation (container, VM, or a tool like OpenShell) for untrusted input. The operator gates are defense-in-depth, not a security boundary — same stance as Hermes Agent's own SECURITY.md.

• Do not expose remote without real auth. Operator Mode does not add any authentication. Bind to loopback only, or put a real auth layer (VPN, Tailscale, OAuth) in front before exposing on a network.

Operator levels

Levels are ordered; each level includes all capabilities of the levels above it in this list.

Env flags

Examples

Read-only default (no env vars needed):

hermes-gpt

Cron dry-run:

$env:HERMES_GPT_OPERATOR_ENABLED="1"
$env:HERMES_GPT_OPERATOR_LEVEL="cron"
$env:HERMES_GPT_OPERATOR_APPLY_MODE="dry_run"
$env:HERMES_GPT_OPERATOR_ALLOWED_PROFILES="default,hermes-researcher"
hermes-gpt

Skills/config dry-run:

$env:HERMES_GPT_OPERATOR_ENABLED="1"
$env:HERMES_GPT_OPERATOR_LEVEL="skills_config"
$env:HERMES_GPT_OPERATOR_APPLY_MODE="dry_run"
$env:HERMES_GPT_OPERATOR_ALLOWED_PROFILES="default,hermes-researcher,hermes-trt-manager,hermes-nexus-wiki"
hermes-gpt

Workspace direct with allowed path:

$env:HERMES_GPT_OPERATOR_ENABLED="1"
$env:HERMES_GPT_OPERATOR_LEVEL="workspace"
$env:HERMES_GPT_OPERATOR_APPLY_MODE="direct"
$env:HERMES_GPT_OPERATOR_ALLOWED_PATHS="C:\Users\<YOU>\hermes-gpt,C:\Users\<YOU>\AppData\Local\hermes\hermes-agent"
hermes-gpt

Owner Mode (WARNING: can mutate your machine):

$env:HERMES_GPT_OPERATOR_ENABLED="1"
$env:HERMES_GPT_OPERATOR_LEVEL="owner"
$env:HERMES_GPT_OPERATOR_APPLY_MODE="direct"
$env:HERMES_GPT_OWNER_ACK="I_UNDERSTAND_THIS_CAN_MUTATE_MY_MACHINE"
hermes-gpt

Audit log

Every mutating tool call appends a JSONL record to:

• %USERPROFILE%\AppData\Local\hermes\logs\hermes_gpt_operator_audit.jsonl (preferred), or

• <hermes-gpt>\logs\hermes_gpt_operator_audit.jsonl (fallback)

Each record contains: timestamp, tool, level, apply_mode, dry_run, success, changed, summary, error, profile(s), path summary, job_id / skill_name / key (when relevant), and prompt_len + prompt_sha256 / content_len + content_sha256 for skill/cron content. The audit log never records full prompts, full config values, raw .env contents, vault contents, or command output likely to contain secrets. Read it with the hermes_operator_audit_tail tool.

Owner Mode warning

Owner Mode can mutate your machine. Use it only on a trusted local machine. It is not a sandbox — it is the explicit break-glass path for the local owner. Even in Owner Mode, secret paths (.env, auth.json, .ssh/, mcp-tokens/, etc.) remain denied; no secret override is shipped in this release.

When HERMES_GPT_AUTH_TOKEN is set, HTTP/SSE requests require:

Authorization: Bearer *** root health check and CORS preflight requests remain unauthenticated.

## Remote profile

`--profile remote` requires either static bearer-token auth or OAuth auth:

```bash
HERMES_GPT_AUTH_TOKEN=<secret> python server.py --http --profile remote
# or
HERMES_GPT_OAUTH_ENABLE=1 python server.py --http --profile remote

For temporary experiments only, you can bypass this block with both:

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

Do not use this 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\<YOU>\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.