Skip to main content

Hermes Gateway

The Hermes Gateway plugin lets the Hermes agents you run on your own Hermes gateway answer in Timon like any other agent: in the chat, in missions and in Kanban tasks other than code. The gateway can run on another machine. Each Timon account connects its own gateway with its own key; Timon never shares one account's gateway with another.

This is different from the Hermes backend, which starts hermes-acp on the machine that runs Timon. Use the gateway when Hermes lives elsewhere, or when it should keep its own tools, memory and models.

Prepare your Hermes gateway​

  1. Hermes 0.21.0 or later; 0.21.6 or later is recommended. From 0.21.6 on, an answer whose stream is cut (a network blip) resumes where it stopped. With 0.21.0 to 0.21.5, Timon still gets the final answer, but the text stops appearing live after a cut.

  2. The API server needs aiohttp. It is not one of Hermes' core dependencies: without it, hermes gateway starts without its API server, and nothing answers on its port. Install the messaging extra of Hermes (or aiohttp itself) in Hermes' environment.

  3. Enable the API server in ~/.hermes/.env:

    API_SERVER_ENABLED=true
    API_SERVER_KEY=<a key of at least 16 characters>

    Hermes refuses to start its API server with a shorter key. Then start the gateway with hermes gateway; it listens on http://127.0.0.1:8642 by default.

  4. Named profiles are reached under /p/<profile>/, each with its own key, set in that profile's own .env (profiles/<profile>/.env). The default profile's key does not open another profile.

Reach it from Timon​

The gateway listens on its own machine's loopback by default. If Timon runs elsewhere, make the gateway reachable without exposing it to the internet:

  • Tailscale (recommended): serve the gateway's port on your tailnet (tailscale serve), and use its https://<machine>.<tailnet>.ts.net address, or its Tailscale IP.
  • A reverse proxy with HTTPS that forwards the Authorization header.

Timon accepts plain http:// only for an address on your own machine, your local network or Tailscale.

Connect it​

  1. Turn the plugin on: it ships with Timon, switched off. An administrator enables Hermes Gateway from the Plugins page, or runs timon plugin enable hermes-gateway (see Plugins).

  2. In Settings → Secrets → Connections, choose Add a connection and pick Hermes Gateway:

    • the gateway's address (https://…, or http://… for a local or Tailscale address, with This service is on my machine or local network ticked);
    • Hermes profile: leave it empty for the default profile, or give the profile name;
    • API server key: the API_SERVER_KEY of that profile.

    Add one connection per Hermes profile you want in Timon.

  3. An administrator approves the address (in the same pane). Test then checks that the gateway answers, that the key is accepted, and that Hermes is recent enough.

  4. Open Settings → Hermes Gateway: each gateway shows its state (connected and Hermes version, waiting for approval, turned off, unreachable). Create the agents creates one Timon agent per connected profile, named hermes.<profile>.

Creating the agents needs an administrator account: only an administrator may put a new agent on a backend whose tool approvals do not go through Timon's own permission levels. Once created, anyone may talk to them, and each person reaches their own gateway with their own key. Someone with no Hermes connection is told so in the chat.

What works​

  • Replies stream into the chat, tool calls appear with a short preview of what they did, and sub-agents Hermes starts show as their own cards.
  • When Hermes asks to run a risky command, an Allow / Deny card appears. Allow lets that one command through; Deny blocks it and Hermes carries on without it. On an autonomous mission with nobody to answer, the card ends in a refusal after the usual delay.
  • Stop ends the current answer on the gateway too; the conversation goes on.
  • The conversation lives in Hermes: a mission that resumes reopens the same Hermes session, and Timon asks Hermes to keep a separate memory for each Timon account.
  • Timon restarts (an update, a reboot) do not lose an answer in progress: the mission picks the Hermes run up again, and an approval card that was open is shown again.
  • The gateway restarts: Hermes ends the answer in progress. The chat says so, shows what Hermes had already written, and you send your message again to continue.
  • When the gateway is busy (too many answers at once), your message waits for a free slot.

What does not work​

  • Closing a Kanban task. A task other than code runs, and Hermes' answer stays in its mission, but a Hermes agent cannot mark the task done or write its report: Timon closes it as done once the mission has been idle for a while, with a note that the agent reported nothing.
  • Code tasks. A Hermes agent works on the gateway's machine, not in Timon's folder: a Kanban task of type code or merge assigned to it is blocked with the reason.
  • Attached files. Hermes would drop them without a word, so Timon refuses the message instead. Images are not sent either: the chat says so.
  • Timon's tools. Kanban, messages to other agents and memory are not available to Hermes agents: Hermes loads its tools from its own configuration, and has no way to receive a per-mission access to Timon.
  • "Allow for the session" or "always allow". The card allows or refuses one command at a time.
  • Missions with no account behind them, such as a Kanban task nobody owns or a routine: there is no account, hence no gateway, to run them on.
  • The model is chosen in Hermes, per profile, not in Timon.