Prompt Paul Chrome extension
← Back to Prompt Paul Prompt Paul guide

Hermes Agent gateway

Connect Prompt Paul to Hermes.

Use the Hermes API gateway to bring a trusted, self-hosted agent into Prompt Paul. This guide covers setup, connection checks, common errors, and the safety decisions that come with host-level tools.

Before you start

  • Make sure the Hermes Agent gateway is running.
  • Know the gateway API URL and API key, if the gateway requires one.
  • Know the Hermes profile name if you use a named profile.
  • Use a gateway only on a network that you trust. Hermes can run high-risk tools on the host computer.
1

Use the API gateway URL

Hermes can provide two different web services: the API gateway accepts requests from Prompt Paul, while the dashboard provides a browser interface. Enter the API gateway URL in Prompt Paul, not the dashboard URL. A dashboard URL returns HTML; Prompt Paul needs JSON from API routes.

Enter the base gateway URL without /health or /v1/capabilities. Prompt Paul adds those paths when it tests the gateway. Use the URL and port published by your Hermes deployment; a local installation may use a different URL from a hosted or container installation. 

https://your-hermes-host.example
2

Configure Prompt Paul

  1. Open Prompt Paul Options.
  2. Create or select a connection profile.
  3. Set Connection type to Hermes Agent gateway.
  4. Enter the Hermes API gateway URL.
  5. Enter the gateway API key if the gateway requires one.
  6. Leave Hermes profile blank unless you created a named profile.
  7. Confirm that you trust the remote Hermes network when you use a remote URL.
  8. Select Save Settings, then Test Hermes connection.

The API key is optional only when the gateway does not require Bearer authentication. A trusted network does not always remove the gateway's authentication requirement.

Allow Prompt Paul browser access

Hermes rejects browser requests by default when API_SERVER_CORS_ORIGINS is empty. A command-line request may work while Prompt Paul receives an empty HTTP 403 response. This is a CORS origin policy failure, not proof that the Prompt Paul API key is wrong.

Get the exact Prompt Paul origin from the Options page or side-panel DevTools console. Run this only in an extension page, not in an ordinary website tab: 

chrome.runtime.getURL('').replace(/\/$/, '')

The result has this form:

chrome-extension://YOUR_PROMPT_PAUL_EXTENSION_ID

Add that exact value to the Hermes API_SERVER_CORS_ORIGINS allowlist. Keep existing entries and do not use *. Restart the Hermes API service after the change, then reload Prompt Paul from chrome://extensions.

Optional dashboard-agent request

If the Hermes dashboard has terminal access, you can ask its agent to make the change. Replace the placeholder with the origin returned by the command above: 

Configure Hermes Agent for Prompt Paul.

      1. Inspect the current API_SERVER_CORS_ORIGINS configuration.
      2. Add this exact origin, preserving existing entries:
         chrome-extension://YOUR_PROMPT_PAUL_EXTENSION_ID
      3. Do not print, change, or expose API_SERVER_KEY or any other secret.
      4. Do not use a wildcard origin.
      5. Show me the proposed configuration change and ask for confirmation before editing files or restarting containers.
      6. After confirmation, apply the change and restart only the Hermes API service.
      7. Verify that a request from the Prompt Paul origin is accepted.

Replace the placeholder extension ID after pasting. The agent should report that the origin was added, existing entries were preserved, the API key was unchanged, the Hermes service is running, and the origin's preflight request was accepted. A dashboard login does not replace this API-server CORS setting.

3

Test the gateway

Open this URL in a browser, replacing the placeholder with your gateway URL:

https://your-hermes-host.example/health

The gateway should return JSON, such as:

{ "status": "ok" }

The gateway root can return 404: Not Found. This is normal: the root path is not a web page. A response from /health proves that the API gateway is reachable.

If the gateway requires authentication, use an API client that can send this header to test protected routes: 

Authorization: Bearer YOUR_API_KEY

Common errors

The selected Hermes profile was not found.

The profile name does not exist on the Hermes gateway. Clear the Hermes profile field, save the connection, and test it again. Add a profile name only when that name exists in Hermes.

Hermes endpoint is required.

The endpoint is empty, or the new endpoint has not been saved. Enter the base API gateway URL, select Save Settings, and then select Test Hermes connection.

Unexpected token '<' or an HTML response

Prompt Paul received an HTML page instead of JSON from the gateway. Change the endpoint to the Hermes API gateway URL. Do not use the dashboard URL.

Hermes capability discovery failed (HTTP 401)

The gateway received no valid API key. Check the gateway configuration and copy the gateway API key into Prompt Paul. Do not use the dashboard username or password as the gateway API key.

Hermes session creation failed (HTTP 403)

If /health works and a server-side API test succeeds, but Prompt Paul gets an empty 403 during session creation, check the browser origin allowlist:

  1. Run the chrome.runtime.getURL command above in Prompt Paul DevTools.
  2. Confirm the exact chrome-extension://... value is in API_SERVER_CORS_ORIGINS.
  3. Confirm Hermes was restarted after the configuration change.
  4. Reload Prompt Paul from chrome://extensions and retry.

Do not replace the API key based on this error alone. Hermes can return 401 for an invalid key but 403 for a browser origin that is not allowed.

This site cannot be reached

Check these items:

  • The Hermes Agent gateway is running.
  • The API gateway URL is correct and uses the right http or https scheme.
  • The API port is published for network access.
  • Your device can reach the host and a firewall allows the API port.

Test /health instead of the gateway root. A 404 at the root means that the port is reachable; a connection error means that the service or network path is not reachable.

Failed to execute 'fetch' on 'WorkerGlobalScope': Illegal invocation

This error can occur with an older Prompt Paul build. Reload or update the extension, then test the saved Hermes profile again.

Security notes

  • Treat the gateway API key as a secret. Do not put it in the URL.
  • Do not paste the API key into support chats, screenshots, or public files. Rotate it if you expose it.
  • HTTP does not encrypt traffic. Use HTTP only through a trusted private overlay or VPN; use HTTPS for other networks.
  • Keep the dashboard and API gateway private. Do not publish them to the public internet.
  • Hermes tools can access files, run commands, and affect the host computer. Review every approval request.