# hermes-gpt

![Hermes GPT branding](assets/hermes-gpt-branding.jpg)

`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:

```bash
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:

```bash
cd ~/hermes-gpt
python server.py
```

Example client command:

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

## Local HTTP

HTTP mode uses FastMCP streamable HTTP:

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

Local endpoint:

```text
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:

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

In another terminal:

```powershell
& "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:

```bash
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:

```bash
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:

```bash
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`.