Local-first MCP Sidecar • Python • FastMCP

Two-way bridge between Hermes and Codex.

Hermes GPT v0.5.0 connects your local Hermes Agent to ChatGPT, Cursor, Claude Desktop, and Codex CLI. A standalone companion sidecar that imports Hermes internals at runtime to let you search files, execute local commands, read memories, view skills, and delegate work to Codex — safely, without copying files or code.

Install Server View GitHub Repo

Runtime Bridge FastMCP + SSE Supports both stdio mode for local editors and HTTP streaming SSE transport for remote ChatGPT developer connections.

Security posture Tiered Operator Policy Tiered safety levels (read_only up to owner). Mutating calls require explicit opt-in apply modes and dry-run override tags.

Hermes Home Auto-detected Automatically scans AppData / local paths on Windows and UNIX systems to load Hermes Agent internals dynamically.

System Architecture

Sidecar runtime integration.

Hermes GPT acts as a lightweight sidecar. It runs locally alongside your Hermes Agent installation, calling tools dynamically and passing the structured outputs back to your LLM clients.

01 Client Request

You ask ChatGPT to "list my skills" or "run build". ChatGPT resolves this request into a Model Context Protocol tool call.

02 SSE/Stdio Bridge

The call is routed to Hermes GPT. Stdio for local apps like Cursor, or HTTP SSE through a secure Cloudflare tunnel for ChatGPT.

03 Dynamic Import

Hermes GPT locates the local Hermes Agent directory, imports its core python tool code, and runs the action locally.

04 Gated Response

Execution is evaluated against your active Operator Level (e.g. read_only, skills, workspace) and server apply mode before returning results.

Interactive Sandbox

Live MCP tunnel & safety gate simulator.

Toggle local environment configurations and simulate how ChatGPT requests local commands, reads files, and fetches skills through the FastMCP server.

1. Configure Environment Security Gates

HERMES_GPT_OPERATOR_LEVEL Define permitted action tiers

HERMES_GPT_OPERATOR_APPLY_MODE Toggle dry-run previews vs direct writes dry_run

2. Select MCP Tool to Execute

ChatGPT (MCP client)

Welcome! I'm connected to your local machine via the Hermes GPT MCP server. Select a tool above and run the simulation to see how I fetch data from your local environment.

local-server.py (FastMCP SSE)

[SYSTEM] Server started on 127.0.0.1:4750

[SYSTEM] Tunnel active: https://hermes-gpt-tunnel.trycloudflare.com/mcp

[WAITING] Waiting for incoming ChatGPT requests...

Capabilities

Built for secure, headless local automation.

Hermes GPT is engineered with zero-trust local constraints. It stays out of your project directories and relies on loopback controls to protect your machine.

Zero-Config Sidecar

Does not install as a fork of Hermes Agent or copy files. It imports your active local installation at runtime, preventing code drift.

Double Transport Mode

Supports stdio mode for local IDE integrations (Cursor, Claude Desktop) and SSE transport for streaming web hooks.

SQLite Session Indexing

Connects directly to your local Hermes state database to search past chats using SQLite FTS5 index logic, gated behind security switches.

Tiered Safety Gating

Action tiers (from read_only to workspace and owner) restrict mutating tools unless the server apply mode is explicitly set to direct.

Local-dev Warning Engine

Binds to loopback (127.0.0.1) by default. If bound to a public interface without authentication enabled, the server alerts you on startup.

Operator Diagnostics Suite

Proactive health checks (hermes_operator_doctor), state snapshots (hermes_operator_snapshot), release readiness assessment (hermes_release_doctor), and safe dry-run-first recovery (hermes_operator_recover). Structured error envelopes provide {success, ok, error, layer, code, safe_message, suggested_action, trace_id} on every failure, with PASS/WARN/FAIL/UNSUPPORTED statuses and automatic secret/path redaction.

How to setup

Get up and running in minutes.

Hermes GPT runs in Python. Install dependencies, run the server, and add the config block to your editor or web clients.

PowerShell / Bash

# Clone the repository
git clone https://github.com/asimons81/hermes-gpt.git
cd hermes-gpt

# Install required dependencies
python -m pip install -r requirements.txt

# Run the local server in stdio mode (default)
python server.py

Run verification

The server will launch in stdio mode by default, scanning for your local Hermes installation. Set the HERMES_HOME environment variable if you have a custom folder location.

Claude Desktop / Cursor config.json

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

Desktop Config

To connect local apps like Cursor or Claude Desktop, append this configuration block to your JSON settings file. Make sure to use the absolute path to your server.py file.

Terminal 1: Start SSE Server

python server.py --http --host 127.0.0.1 --port 4750

Terminal 2: Start Cloudflare Tunnel

cloudflared tunnel --url http://127.0.0.1:4750 --http-host-header 127.0.0.1:4750

Connecting ChatGPT Web

Because the ChatGPT web client runs remotely in the cloud, you must expose your local Hermes GPT server through a tunnel. Copy the generated trycloudflare.com URL and configure a Streaming HTTP connection in ChatGPT developer mode.

Changelog

Release history & updates.

Keep track of server version additions, security overrides, and feature releases.

v0.5.0 2026-07-10

Two-Way Codex Bridge

Codex can opt into a namespaced Hermes Operator toolset, while trusted Hermes GPT clients can run asynchronous, policy-gated Codex tasks and reviews. Core stays the default; updates and mutations stay check-first and dry-run-first.

v0.4.0 2026-07-09

Tool Surface Expansion

Added env-gated Hermes tool wrappers: hermes_vision_analyze, hermes_web_search, hermes_web_extract. Added hermes_cron_create operator tool with full field support. Shipped first external contribution — macOS gateway PID fallback from gateway_state.json. Expanded gateway diagnostics fields. Fixed Vercel deploy and flaky test. Published to PyPI, GitHub Release, and GitHub Actions publish workflow.

v0.3.0 2026-06-25

Operator Reliability Release

Added four new operator diagnostics tools: hermes_operator_doctor (deep health check), hermes_operator_snapshot (single state summary), hermes_release_doctor (release readiness with PASS/WARN/BLOCKED classification), and hermes_operator_recover (conservative dry-run-first recovery). Introduced structured error envelopes with {success, ok, error, layer, code, safe_message, suggested_action, trace_id} and PASS/WARN/FAIL/UNSUPPORTED status vocabulary across all operator surfaces.

v0.2.0 2026-06-21

Operator & Owner Modes

Introduced tiered Operator and Owner safety postures (read_only, cron, skills, skills_config, workspace, owner) expanding the interface to 39 tools. Added dry-run previews for mutating operations, break-glass acknowledgements, cron tools, workspace scoped file actions, configuration editing, and audit logging.

v0.1.0 2026-06-18

Initial local-dev release

Added FastMCP stdio and streamable HTTP server support. Imports local Hermes file read/search, memory search, and skill list/view capabilities. Provides opt-in environment safety gates for terminal, writes, patches, and session history searches.