Hermes A2A Gateway

English | Tiếng Việt

Hermes A2A Gateway connects Codex Desktop to Hermes on a private server. The clientowns a durable local inbox and optional SSH tunnel; the broker owns a PostgreSQLledger and dispatches work to the server's loopback Hermes A2A endpoint.

Release: v0.7.0. Package, command and MCP registration are nowhermes-a2a-gateway. The Python namespace is hermes_a2a_gateway and configurationuses HERMES_A2A_GATEWAY_*. This release removes the old local gateway modes,legacy executable aliases, setup skills and Hermes → Codex plugin.

Codex Desktop -- MCP --> client daemon + SQLite inbox
                            | direct HTTPS or HTTPS inside owned SSH tunnel
                       TLS proxy --> broker + PostgreSQL
                                         | loopback A2A
                                       Hermes

This is an independent community project, not an official OpenAI or Nous Researchproduct. Codex Desktop is the first verified integration; other runtime adaptersand arbitrary Hermes-initiated Desktop jobs are not implemented.

Install and use

Install the same release wheel on both machines; a Git clone is unnecessary.Start with the release download/checksum instructions.

Machine or task	Guide
Private server running Hermes	Server installation and operation (Vietnamese)
Workstation running Codex Desktop	Client installation and five-tool usage (Vietnamese)
Direct LAN/VPN or managed SSH connection	SSH configuration, retries and diagnostics (Vietnamese)
Existing v0.6 or legacy installation	Migration, removal and rollback

Only four commands are installed:

hermes-a2a-gateway broker
hermes-a2a-gateway client
hermes-a2a-gateway client-mcp
hermes-a2a-gateway client-doctor

Configure the private client launcher as documented, then register its MCP facade:

codex mcp add hermes-a2a-gateway -- \
  "$HOME/.config/hermes-a2a-gateway/launch" client-mcp
codex mcp get hermes-a2a-gateway

Set tool_timeout_sec = 90 in the existing [mcp_servers.hermes-a2a-gateway]Codex configuration table, as shown in the client guide.

The daemon must be running before using tools. SSH belongs to the daemon, not toindividual MCP calls or Desktop tasks. Server credentials and encryption keys stayin protected configuration, outside MCP arguments.

MCP tool	Purpose
`gateway_submit`	Submit once and return an operation handle; explicit wait 0–60 seconds
`gateway_get`	Retrieve an existing operation/result in its originating Desktop task
`gateway_wait`	Wait up to 60 seconds on the same operation without resubmitting
`gateway_cancel`	Request best-effort cancellation
`gateway_upload_artifact`	Upload an explicitly selected regular file

For long work, submit with wait_seconds: 0, keep operation_id, and get/wait onthat handle. Explicit waits such as 20 are valid even when the configured defaultis 15. Only UTF-8 text/plain attachments are passed to Hermes in this profile;local repository files are not automatically synchronized.

Durability and limits

TLS verification, device bearer authentication and loopback Hermes are requiredfor remote deployment. SSH mode additionally verifies host keys and binds itslocal forward to loopback. It never disables HTTPS to recover from an error.
Network reconnect uses bounded retries. SSE resumes from a persisted cursor andoperations are reconciled by exact identities. An ambiguous Hermes mutation ornative queue insertion is never blindly repeated.
A late result may queue a reference in its original Desktop task. Queue ACK isnot proof of consumption. Offline/unloaded-host wake is not guaranteed; usegateway_get/gateway_wait when necessary.
One owner, separately authorized devices, one broker dispatcher, one daemon perinbox. This is not a public multi-tenant service or an HA cluster.
Payloads are encrypted with external keys and expire. Default payload/artifact TTLis one day; result/event retention is seven days. Keep backups and keys togetherunder a separate retention policy. Do not replace an existing encryption key.
Cancellation is best-effort. Human-input continuation through the broker is notimplemented. Native delivery is version/schema gated.
CPython 3.11 and clean wheels are tested on macOS/Linux. The Unix-socket clientdoes not support Windows. Native Desktop behavior must be verified separatelyfrom package installation or simulated reconnect tests.

See the wire contract, deployment reference,release notes, v0.7 verification,and historical evidence.

Development

git clone https://github.com/phamviet86/hermes-a2a-gateway.git
cd hermes-a2a-gateway
python3.11 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/python -m compileall -q src tests scripts
.venv/bin/ruff check .
.venv/bin/ruff format --check .
.venv/bin/mypy src
# Set HERMES_A2A_GATEWAY_TEST_POSTGRES_DSN to a disposable PostgreSQL 16 database.
.venv/bin/pytest --cov=hermes_a2a_gateway --cov-report=term-missing

Tests use fake peers; live model tasks are opt-in and never run in CI. SeeAGENTS.md, CONTRIBUTING.md, CHANGELOG.md,and SECURITY.md. Licensed under Apache-2.0.

Hermes A2A Gateway