Hermes Agent
Hermes Agent with Paperclip: connect Hermes agents
Updated 20 November 2026
Paperclip is an open-source app for running AI agents as a team. A Hermes agent can join it in more than one way, and the right one depends on where Hermes runs. This page lays out each route, what it needs, where the model is set, and the errors the sources list.
Facts come from Paperclip’s own documentation, including its Hermes adapter reference, its Hermes Gateway reference, its agent adapters guide and its blog post on inviting a Hermes agent, and from the README of hermes-paperclip-adapter, all read on 20 November 2026. Check your Paperclip version against the requirements below.
What Paperclip is
The Paperclip documentation describes agents that sit on an org chart, take tasks, report to a manager, and run within company permissions, budgets and approval requirements. Its site says you can run Paperclip on your own infrastructure, and the footer calls it open source under the MIT licence.
The piece that matters here is the adapter. The agent adapters guide calls it the bridge between Paperclip and the AI system that runs an agent: it tells Paperclip how to launch the agent, how to hand it work and how to get results back. For Hermes there are two built-in adapters, hermes_local and hermes_gateway, plus an invite flow that sets up the second one for you, plus a separate npm package.
The routes at a glance
| Route | Where Hermes runs | What it needs |
|---|---|---|
hermes_local | On the same machine as Paperclip | Hermes installed there, and Python 3.10 or newer |
hermes_gateway, filled in by hand | Another host, a cloud VM or a separate process | Hermes API server enabled, apiBaseUrl and apiKey |
| Invite prompt | Hermes already running and able to reach Paperclip | Paperclip v2026.626.0 or later, and someone who can approve the join |
hermes-paperclip-adapter | On the Paperclip machine, like the local adapter | Hermes installed, Python 3.10 or newer, one model API key, and registering the package in your Paperclip server |
When each one fits, going by the sources:
- Same machine, you want Paperclip to start Hermes. Use
hermes_local. - Hermes already runs elsewhere and has its API server. Use
hermes_gateway. The gateway reference says it only connects to a Hermes that is already running. - You would rather paste one prompt than fill in fields. Use the invite flow, which ends in a
hermes_gatewayagent. - You want to use the separate adapter package described in its README. Read the package section below.
Route 1: the built-in local adapter
The Hermes adapter reference says hermes_local runs Hermes on the same machine as Paperclip and ships with Paperclip, so no plugin install is needed. It also says Hermes itself must be installed there, with Python 3.10 or newer. The reference suggests pip install hermes-agent, which is the command Paperclip’s environment test gives, and on Linux, macOS or WSL2 it points to the Hermes installer. For installing Hermes on its own, see install Hermes Agent.
Paperclip runs Hermes in single-query mode (hermes chat -q), lets it work with its tools, and Hermes exits when the task is done. The reference lists these settings:
model: optional, inprovider/modelform, passed to Hermes with-m.provider: defaults toauto; the reference says to usually leave it there.timeoutSec(default1800) andgraceSec(default10, the wait after SIGTERM before the process is killed).toolsets(comma-separated, for exampleterminal,file,web) andmaxTurnsPerRun.persistSession(defaulttrue, resumes with Hermes’s--resume),worktreeModeandcheckpoints, both off by default.quiet,verbose,promptTemplateandpaperclipApiUrl.
Where the model is set. The reference says Hermes manages its own model: set it in ~/.hermes/config.yaml or through Hermes’s own configuration and leave the adapter’s model field empty. Fill model only to pin a different one for a single agent.
Route 2: the gateway adapter for Hermes elsewhere
The Hermes Gateway reference says hermes_gateway connects Paperclip to a remote Hermes API server over HTTP or HTTPS, and has been a built-in adapter since v2026.626.0. Paperclip creates runs through POST /v1/runs, streams events from GET /v1/runs/{run_id}/events, polls GET /v1/runs/{run_id} if the stream is unavailable, and stops a run with POST /v1/runs/{run_id}/stop when the timeout passes. Turning on the Hermes side is covered in the Hermes Agent API server guide.
apiBaseUrl(required): the Hermes API server address. It accepts the dashboard root or a chat URL such ashttp://127.0.0.1:9119/chatand maps it to/api.apiKey(required): the HermesAPI_SERVER_KEY, not yourPAPERCLIP_API_KEY. Paperclip stores it as a secret reference.sessionKeyStrategy: sets theX-Hermes-Session-Keyheader.issue(default) gives one session per Paperclip issue,agentone per agent,runa new one each run, andnonesends no header.timeoutSec(default600) andeventReconnectMs(default2000).paperclipApiUrl: a Paperclip address that the remote Hermes host can reach.headersfor non-secret extra headers, andinstructionsfor stable instructions sent separately from each task.
Where the model is set. The gateway page lists no model field. The model is whatever the remote Hermes is configured with, so set it on that Hermes.
Security. The reference allows plain HTTP only for loopback addresses (127.0.0.1, localhost). Any other host should use HTTPS or a private network such as Tailscale or a VPN. dangerouslyAllowInsecureRemoteHttp is described as a development-only escape hatch to turn off before production.
Route 3: the invite prompt
Paperclip’s blog post (6 July 2026) describes this as the path for a Hermes install that already exists and can reach Paperclip. On the Agents page you choose New Agent, then Invite an external agent, then Hermes, and copy the one-time invitation prompt. You paste it to your running Hermes agent in whatever chat you already use with it.
- What the prompt tells Hermes to do. Check it can reach Paperclip with
GET <base-url>/api/health. On a clean install, enable its API server by starting Hermes withAPI_SERVER_ENABLED=trueand a fresh randomAPI_SERVER_KEYand runninghermes gateway run --replace --accept-hooks; the API server defaults to port8642. Then submit a join request withadapterType: "hermes_gateway",apiBaseUrl,apiKeyandpaperclipApiUrl. - Approval. Owners and Admins approve the request in the Join Request Queue at
/inbox/requests. The post says to check the adapter type, the name and capabilities, and the source IP first. Operators can send invites but cannot approve them. - After approval. Approving only lets Hermes into the company. You then give it a title and a manager (Reports to) on its Harness / Runtime page, and assign a small first task to confirm it works.
- Context in the invite. To include a role or first instructions, create the invite through the API with
agentMessage. The post says only board users with invite permission and the company’s CEO agent can do that.
Network reachability has to work both ways: the Hermes host must reach Paperclip, and the Paperclip server must reach the Hermes API address.
Route 4: the hermes-paperclip-adapter package
The NousResearch repository hermes-paperclip-adapter is a separate adapter that lets Hermes run as a managed employee in a Paperclip company. Its README says to install it with npm install hermes-paperclip-adapter and register it in your Paperclip server’s adapter registry (server/src/adapters/registry.ts) as hermes_local. Its prerequisites are Hermes installed, Python 3.10 or newer and at least one model API key.
The installation instructions apply to different adapters. The README describes installing and registering the package. Paperclip’s Hermes adapter reference says hermes_local is built in and needs no plugin install. The two pages do not explain the difference, so check which Paperclip version you run and read its docs before installing anything. The built-in adapter is the one Paperclip documents today.
The README’s settings also differ from the reference. It gives model a default of anthropic/claude-sonnet-4 and timeoutSec a default of 300, lists a narrower set of providers, and shows maxIterations and enabledToolsets in its example, where the reference lists maxTurnsPerRun and toolsets. Treat the README as describing the package and the reference as describing the built-in adapter.
Errors and fixes the sources list
- Connection error, runs do not start. Check the Hermes API server is running and that
apiBaseUrlis reachable from the Paperclip server, not only from your browser. If Paperclip is in Docker and Hermes is on the host,127.0.0.1points at the container; usehost.docker.internalor a LAN address. See Hermes Agent in Docker for the container side. - Loopback address refused. The address is resolved on the Paperclip server, not on your laptop. Run the Hermes API server there, or use an address that server can reach.
- Plain HTTP refused for a non-loopback host. Switch to HTTPS, or for development only use
dangerouslyAllowInsecureRemoteHttp. - Event stream keeps reconnecting. The reference says this often points to a proxy timeout, a load balancer with short keepalive limits or an unstable network. Try increasing
eventReconnectMsto reduce churn. - Run finishes in Hermes but Paperclip shows nothing. If both the stream and the poll fail, check that
apiBaseUrlresolves and the Hermes API server is healthy, then read the Paperclip run log. - API key field says a secret is stored. That is expected; do not paste the key again unless you are rotating it. Separately, if Hermes saved its newly claimed Paperclip API key with a literal
...or[redacted], it saved a masked preview. Generate a new invite and have Hermes rejoin, saving the key from the raw claim response before anything prints it. - No onboarding URL reachable. The blog post says to add a hostname with
pnpm paperclipai allowed-hostname <host>, restart Paperclip and generate a fresh prompt. - Memory carrying across tasks. Keep
sessionKeyStrategyonissue, or userunfor fully isolated sessions.
Paperclip and ReadyHermes
We have not tested Paperclip with ReadyHermes and do not promise it works. A ReadyHermes assistant runs on our servers, so the local adapter does not fit: it needs Hermes installed on the same machine as Paperclip. A ReadyHermes assistant does have an OpenAI-compatible API endpoint you can turn on under Bot tools, then API endpoint (see the Hermes Agent API guide), but we have not connected Paperclip to it.
If you run Paperclip, the routes above are for a Hermes you control. ReadyHermes is for a Hermes Agent that stays on and answers in your chat apps. Plans start from US$3.99 a month (Lite) or US$6.99 (Pro), with US$1 of AI included every month and a 1-hour free trial. See managed Hermes Agent hosting.
Questions
How do I connect Hermes Agent to Paperclip?
There are four routes in the sources: the built-in hermes_local adapter for Hermes on the same machine, the built-in hermes_gateway adapter for a Hermes API server elsewhere, a one-time invite prompt that you paste to a running Hermes, and the separate hermes-paperclip-adapter npm package. Pick by where Hermes runs.
Do I need to install anything in Paperclip to use Hermes?
Paperclip's Hermes adapter reference says hermes_local is built in and needs no plugin install, though Hermes itself and Python 3.10 or newer must be on the machine. For the separate hermes-paperclip-adapter package, its README says to install the package with npm and register it in the server. Check your Paperclip version and its docs.
Where do I set the model for a Hermes agent in Paperclip?
For hermes_local, the reference says Hermes manages its own model: set it in ~/.hermes/config.yaml and leave the adapter's model field empty, or fill model as provider/model to pin one for a single agent. The hermes_gateway page lists no model field, so set it on the remote Hermes.
What does the gateway adapter need from Hermes?
A running Hermes API server, an apiBaseUrl Paperclip can reach and the Hermes API_SERVER_KEY as apiKey, not your Paperclip key. Plain HTTP is allowed only for loopback addresses; other hosts should use HTTPS or a private network such as Tailscale or a VPN.
Can I use Paperclip with ReadyHermes?
We have not tested it and do not promise it works. The local adapter needs Hermes on the same machine as Paperclip, which a ReadyHermes assistant is not. ReadyHermes has an OpenAI-compatible API endpoint you can turn on, but we have not connected Paperclip to it.