Hermes Gateway

hermes_gateway connects Paperclip to a remote Hermes API server over HTTP or HTTPS. Use it when Hermes Agent is already running somewhere — another host, a cloud VM, or a separate process — and exposes its API server. Paperclip calls the Hermes REST/SSE API directly to create runs, stream events, and stop runs on timeout.

This is a first-class built-in adapter as of v2026.626.0. You configure it through the standard Paperclip agent config form, the same way you would configure claude_local or codex_local.

For the older external Hermes agent invitation flow (pre-v2026.626.0), see Bring Your Own Agent.

When To Use

• Hermes Agent runs on a different host or inside a separate process and exposes its API server.
• You want to connect Paperclip to a cloud-hosted or team-shared Hermes instance.
• You need to call multiple Hermes servers from one Paperclip deployment.
• You are building a multi-machine setup where Hermes and Paperclip run independently.

When Not To Use

• You want Paperclip to launch Hermes as a local child process. Use hermes_local instead.
• The Hermes API server is not enabled on the target host.

Config Fields

How It Works

When Paperclip triggers a run for a hermes_gateway agent, the adapter does the following:

1. Creates a run via POST /v1/runs. The request includes an Idempotency-Key equal to the Paperclip run id, which lets you correlate Hermes runs back to Paperclip records.
2. Streams events from GET /v1/runs/{run_id}/events (SSE). If the stream disconnects unexpectedly, the adapter waits eventReconnectMs and reconnects. It also polls GET /v1/runs/{run_id} as a fallback when the SSE stream is unavailable.
3. Stops the run with POST /v1/runs/{run_id}/stop if the timeout is reached before the run completes.

Security

API key storage. The apiKey field maps to Hermes' API_SERVER_KEY. Paperclip stores it as a secret reference and never writes it to plain-text config. If the field shows that a secret is stored, do not repaste the key unless you are intentionally rotating it.

HTTP vs HTTPS. Loopback addresses (127.0.0.1, localhost) can use plain HTTP. Any other host should use HTTPS or a private overlay network (such as Tailscale or a VPN). If you need to connect to a non-loopback host over plain HTTP during development, enable dangerouslyAllowInsecureRemoteHttp — but disable it before production.

Extra headers. The headers field is for non-secret auxiliary headers only. The adapter generates the authentication and session headers itself; any attempt to include security-critical headers via headers will be ignored.

Session Key Strategy

The sessionKeyStrategy field controls the X-Hermes-Session-Key header, which Hermes uses to group runs into a session and provide memory continuity between them.

The default issue strategy is the safest choice. It keeps each Paperclip issue's work in its own Hermes session so that one task's context does not leak into another.

Example

{
  "adapterType": "hermes_gateway",
  "adapterConfig": {
    "apiBaseUrl": "https://hermes.internal.example.com",
    "apiKey": {
      "type": "secret_ref",
      "secretId": "hermes-api-key",
      "version": "latest"
    },
    "sessionKeyStrategy": "issue",
    "timeoutSec": 600,
    "eventReconnectMs": 2000,
    "paperclipApiUrl": "https://paperclip.internal.example.com",
    "instructions": "You are an engineering assistant. Work carefully and post status updates as you go."
  }
}

For a local development setup where Hermes and Paperclip both run on the same machine:

{
  "adapterType": "hermes_gateway",
  "adapterConfig": {
    "apiBaseUrl": "http://127.0.0.1:9119",
    "apiKey": {
      "type": "secret_ref",
      "secretId": "hermes-api-key",
      "version": "latest"
    },
    "sessionKeyStrategy": "issue",
    "timeoutSec": 300
  }
}

Troubleshooting

Runs do not start and the adapter reports a connection error

Check that the Hermes API server is running and that apiBaseUrl is reachable from the Paperclip backend — not just from your browser. If Paperclip is inside Docker and Hermes is on the host, 127.0.0.1 will point to the container, not the host. Use host.docker.internal or a LAN address instead.

The API key field says a secret is stored

That is expected. Paperclip masks stored adapter secrets. Do not repaste the key unless you are rotating it.

HTTP connection refused for a non-loopback host

Non-loopback plain HTTP is blocked by default. Either switch the apiBaseUrl to an HTTPS URL, or enable dangerouslyAllowInsecureRemoteHttp for development use only.

Events stream keeps reconnecting

A high reconnect rate usually means the SSE stream drops frequently — often a proxy timeout, a load balancer with short keepalive limits, or an unstable network. Try increasing eventReconnectMs to reduce churn, and check whether a proxy between Paperclip and Hermes is terminating long-lived connections early.

Runs complete in Hermes but Paperclip shows no results

The adapter polls GET /v1/runs/{run_id} as a fallback when the SSE stream is lost. If both the stream and the poll fail, verify that apiBaseUrl resolves correctly and that the Hermes API server is healthy. Check the Paperclip run log for the last error from the adapter.

Cross-task memory bleed between issues

Switch sessionKeyStrategy to issue (the default). If it is already set to issue, confirm that the Hermes instance is correctly scoping sessions by key. Setting the strategy to run gives fully isolated sessions if you need a harder guarantee.

Next Steps

• Hermes Local — run Hermes as a local child process on the same machine instead.
• Bring Your Own Agent — for the external agent invitation flow and the broader model of connecting third-party agents to Paperclip.
• Agent Adapters — how Paperclip adapters work in general.