Skip to main content

Set up Wisp inside Hermes

This page takes you from a working Hermes Agent to Hermes handing its private tasks to Wisp. What the integration does, and what it protects, is on Wisp inside Hermes.

Pick your setup​

Your situationSetupYou need
Hermes runs on your Mac or your Linux machine, and you have a terminal thereOne machineabout 5 minutes
Hermes runs on a VPS, and your private files and accounts should stay on another machine (a Mac mini at home, a second server)Two machinesa way to reach that machine over https or SSH
You talk to Hermes only from Telegram or Slack, and have no terminal on its machineFrom a chatthe chat

One machine or two​

One machineTwo machines
Where your private files and Wisp's keys areon Hermes's machine, behind a sandboxon another machine; Hermes's disk has none of them
What keeps Hermes outan OS sandbox around every Hermes process (Seatbelt on macOS, bubblewrap on Linux)the network: Hermes reaches only Wisp's /mcp endpoint
Against a model set on escapingdoes not hold: an app or script started outside the sandbox can read the files, and on macOS computer use drives apps the sandbox does not coverholds: there is nothing to escape to
Hermes's model switching the plugin offpossible, and seen only by wisp doctorchanges nothing: the files were never there
Hermes's own MCP serversintegrate moves them into Wisp for youyou add them in Wisp and remove them from Hermes by hand
Upkeepone command; restart Hermes after each new Private Foldera second machine kept on and reachable; an https address or a tunnel
Hermes on Windowsnoyes, as the Hermes side

Both share the limits of the credential: whoever holds it can ask Wisp anything, and a prompt-injected Hermes can approve Wisp's Confirmations itself (Known limits).

Which to choose. Two machines is the safer one: the files and the keys are simply not where Hermes runs, and no sandbox has to hold. Choose it when the data matters most (health, money, legal papers). One machine is fine when you mainly want Hermes's model and its .env kept away from your accounts, and you trust the machine itself.

Whichever you pick:

  • Run Hermes as its own regular user, not root. On one machine the sandbox cannot keep root out. On a VPS, where you often log in as root, create a user for Hermes (adduser hermes) and install and run Hermes as that user.
  • Keep the machine that holds Wisp yours alone: a computer at home, or a server only you log in to. Your files and Wisp's keys are on it.
  • Prefer Tailscale Serve for two machines: no open port and no domain. With an SSH tunnel, restrict its key, or Hermes gets a shell on Wisp's machine.
  • Keep confirmations on for what moves data out: sending mail or messages, writing files. Allow a tool beforehand (wisp permissions set <tool> allow) only for what a cron job needs.
  • Delete the moved keys from Hermes's .env, as integrate lists them: until then Hermes still holds them.
  • Limit who talks to your Hermes. Anyone Hermes lets in, in a group chat too, uses Wisp as you.
  • Prefer /wisp <task> when even the conclusion should not reach Hermes's model.
  • On one machine: check wisp doctor now and then, and restart Hermes after wisp private add.

Before you start​

  • Hermes Agent v0.21.6 or later. Check with hermes --version, and update with hermes update.
  • macOS or Linux for Wisp. Hermes on Windows works only as the Hermes side of two machines.
  • A Wisp account with a prepaid balance. The tasks Hermes hands to Wisp are paid from it, as any CLI use is: see Billing. wisp integrate hermes warns when it is empty.
  • On Linux, run Hermes as a regular user, not root. Wisp's sandbox cannot keep root out.

One machine​

Wisp and Hermes run side by side, as the same user. wisp integrate hermes sets up every Hermes profile in one go.

1. Install Wisp​

curl -fsSL https://usewisp.io/runtime/install.sh | sh

The installer asks two questions. Answer yes to both:

  • Start the Runtime in the background now and at every login? [Y/n] — Hermes needs Wisp running whenever Hermes does.
  • Log in now? [Y/n] — opens the browser to sign in. On a server without a browser it prints a link instead: open it on any device, sign in, and paste back the address the browser lands on (see Sign in).

Then open a new terminal, or run the source … line the installer prints at its end. Until then the shell does not find wisp.

Check that it is up:

wisp status
# ready (wisp 0.1.17, serve)

Install, update, uninstall covers the installer's options and the service.

2. Wire Wisp into Hermes​

wisp integrate hermes

For each Hermes profile, it lays out Wisp's plugin, enables it, and connects it to this Runtime with one credential named hermes. Every change to Hermes's config goes through Hermes's own CLI; your skills, plugins, cron jobs and settings stay as they are.

default: laid the Wisp plugin out in /Users/you/.hermes/plugins/wisp
default: hermes wisp connect http://127.0.0.1:3008/mcp
default: Hermes's MCP servers: gmail, deepwiki
default: move which into Wisp? Their names, separated by spaces; Enter for none

The question about MCP servers is optional. If Hermes already reaches a private account through an MCP server (Gmail, Notion, a broker), name it and Wisp takes it over: Hermes then no longer holds its keys. Press Enter to skip, and do it later with wisp integrate hermes --connectors. What happens to each server is on Moving Hermes's MCP servers into Wisp. --skip-connectors skips the question outright.

It ends with what to do next, and the known limits for your OS.

3. Linux only: the fix before the restart​

On Linux, Wisp's sandbox around Hermes is bubblewrap, required here, not only for bash_run's sandbox. On Ubuntu 23.10 and later, AppArmor also blocks it for regular users. You do not have to work this out: integrate checks both, and if bubblewrap is missing or blocked, it prints one more step:

Before the restart: Hermes runs unsandboxed on this machine until this is fixed: …

Run the command it names, exactly as printed. It installs bubblewrap, adds a small AppArmor profile for it, or removes bubblewrap's setuid bit. A line that names no command gives bubblewrap's own error instead. If your user has no sudo (common on a VPS you reach with an SSH key), run it as root, without its leading sudo.

4. Restart Hermes​

The plugin, and its sandbox, take effect when Hermes starts:

hermes gateway restart --all

Also quit any hermes CLI you have open. Until every Hermes process has stopped once, it runs without the sandbox.

5. Check it​

wisp doctor
# ✓ hermes default: plugin enabled, connected to http://127.0.0.1:3008/mcp
hermes mcp test wisp

Then, in Hermes (the CLI, or Telegram):

  • /wisp Which connectors do you have? — Wisp answers directly, with no Hermes model involved.
  • Ask Hermes to list ~/.wisp. Its tool call is refused with This goes through Wisp — use ask_wisp., and a script Hermes writes cannot read it either: on Linux the folder reads as empty, on macOS the read is refused (Operation not permitted).

6. Tell Wisp what is private​

Wisp now protects its own data and your Desks (~/Wisp). Add the rest:

wisp connectors auth notion-remote # an account Hermes should reach only through Wisp
wisp private add ~/Documents/Finance # a folder Hermes may not open
hermes gateway restart --all # a new Private Folder applies at Hermes's next start

See Connectors for every account Wisp can hold (Gmail, Calendar and Drive appear once Wisp is signed in, and need only wisp connectors auth <name>), and Private Folders.

More than one Hermes profile​

wisp integrate hermes covers every profile it finds. --profile <name> covers only that one. A profile you create later is not covered until you run wisp integrate hermes again (it is safe to run any number of times, and repairs rather than duplicates). A profile made with hermes profile create <name> --clone copies the plugin along with the rest, and is covered at once.

Two machines​

The Runtime runs on one machine, which holds your files and accounts and stays on: a VPS, or a Mac mini at home. Hermes runs on another, and gets only Wisp's plugin, the Runtime's address and a credential that opens Wisp's /mcp endpoint and nothing else. Nothing of Wisp's is on Hermes's disk, so there is no sandbox to set up there.

The Runtime always listens on 127.0.0.1, so Hermes reaches it through one of these:

Way inPick it when
Tailscale Serveboth machines can join the same tailnet. The easiest: no domain, no open port
Caddy with a domainthe Runtime's machine has a public name and ports 80 and 443
An SSH tunnelneither of those; you keep a tunnel up yourself

1. Install Wisp on the Runtime's machine​

As in One machine: the installer, yes to the service and to logging in, then wisp status says ready.

2. Give the Runtime an address Hermes can reach​

Tailscale Serve​

Install Tailscale on both machines, in one tailnet. Once per tailnet, in Tailscale's admin console, turn on HTTPS certificates and Serve. (Without them, tailscale serve prints Serve is not enabled on your tailnet with a link that turns it on.)

On the Runtime's machine:

tailscale serve --bg 3008

It prints the machine's https address, such as https://mac-mini.tail1234.ts.net. Its name, mac-mini.tail1234.ts.net, is <name> below.

Caddy with a domain​

Point a DNS name, such as wisp.example.com, at the Runtime's machine, and put a Caddy site in front of the Runtime. Caddy gets the certificate itself:

wisp.example.com {
reverse_proxy 127.0.0.1:3008
}

wisp.example.com is <name> below. You do not need to edit allowedHosts by hand: the next step adds the name.

An SSH tunnel​

Keep ssh -L running on Hermes's machine as a service (autossh under systemd or launchd), so Hermes reaches the Runtime at http://127.0.0.1:3008 there:

autossh -M 0 -N -o ServerAliveInterval=30 -L 3008:127.0.0.1:3008 wisp-tunnel@runtime-host
Restrict the tunnel's key

Hermes's model can read any key on its machine, and an ordinary SSH key is a shell on the Runtime's machine: the files Wisp is there to keep away from Hermes. Use a key that can forward that one port and do nothing else. In ~/.ssh/authorized_keys on the Runtime's machine:

restrict,port-forwarding,permitopen="127.0.0.1:3008" ssh-ed25519 AAAA… hermes-tunnel

With a tunnel, leave --public-url out in the next step, and use http://127.0.0.1:3008 where the steps say https://<name>. wisp tokens create then suggests an https name and --public-url: ignore that hint.

3. Make Hermes's credential​

On the Runtime's machine:

wisp tokens create --name hermes --host-agent --public-url https://<name>
# <name> added to allowedHosts in the Runtime's config file; the running Runtime answers to it once restarted.
# Host Agent Credential: Q2xhdWRlIHdyb3RlIHRoaXMgZXhhbXBsZSB0b2tlbg
#
# Shown once. On Hermes's machine: `hermes plugins install ConfidentialCrabComputing/wisp-hermes-plugin/wisp --enable`,
# then `hermes wisp connect https://<name>/mcp` and paste it at the prompt.

It is shown once: keep it for step 5. Then restart the Runtime, so it answers to <name>:

systemctl --user restart wisp # Linux
launchctl kickstart -k "gui/$(id -u)/io.usewisp.runtime" # macOS

4. Install the plugin beside Hermes​

On Hermes's machine:

hermes plugins install ConfidentialCrabComputing/wisp-hermes-plugin/wisp --enable

Hermes warns that the source is custom (not from its catalog) and installs it. An older Hermes whose scanner rates the plugin CAUTION asks Install anyway? [y/N]: answer y. The plugin's code is public, at wisp-hermes-plugin, and its README lists what the scanner flags and why.

5. Connect it​

hermes wisp connect https://<name>/mcp
# Wisp Host Agent Credential (printed by `wisp tokens create --name hermes --host-agent`):
# (paste it; nothing is shown)
hermes mcp test wisp

connect reads the credential without echo, so it never lands in your shell history. It refuses a plain http:// address anywhere but loopback.

A running Hermes picks up the new server by itself within seconds; hermes gateway restart makes it immediate. In Telegram, /wisp and /wisp_model reach the bot's command menu after one /restart (then close and reopen the chat); typed, they work at once.

Then​

  • Check it as in One machine, with /wisp Which connectors do you have?. wisp doctor has nothing to check on Hermes's machine.
  • Name what is private on the Runtime's machine: wisp connectors add …, wisp private add …, or in Wisp Desktop connected to that machine, Settings → Knowledge → Private Folders. Hermes never had those files; a Private Folder there tells Wisp's answers to Hermes not to hand its files over verbatim. Hermes's routing rule names it from Hermes's next start.
  • The Runtime's machine must be on and reachable whenever Hermes needs Wisp. While it is not, Hermes says Wisp is not answering, and does not do Wisp's tasks another way.
  • Moving Hermes's MCP servers into Wisp is part of the one-machine setup. Here, add those accounts in Wisp as Connectors, then remove them from Hermes's config and delete their keys from Hermes's .env.

From a chat​

Hermes can install Wisp itself, in its own terminal, when you ask it from Telegram or Slack. It follows the steps in the plugin's README, which are written for it.

  1. Send Hermes:

    Install Wisp, https://github.com/ConfidentialCrabComputing/wisp-hermes-plugin
  2. Sign in when it asks. Hermes sends you a sign-in link in a code block. Open it, sign in, and send back the address your browser lands on (http://127.0.0.1:…/callback?code=…; that page does not load, which is fine). Do it within 5 minutes, or ask Hermes to start the sign-in again.

  3. The turn ends while Hermes reloads. On Linux, Hermes enables the plugin and restarts into the sandbox in the middle of that turn, so the turn is lost. Your next message gets ⏸️ This conversation is paused …: send /discard, then ask something that needs Wisp, such as /wisp Which connectors do you have?. If the chat stays locked (one opened just before), or on macOS, send /restart instead.

  4. On Linux, if Hermes gives you a command to run as root (bubblewrap, or its AppArmor profile), run it on the server as root, then send /restart. Until then Hermes runs without the sandbox.

  5. For the command menu, send /restart once and reopen the chat: /wisp and /wisp_model appear in Telegram's menu after the bot's next start.

Things to know about this path:

  • Hermes runs the installer with no terminal to ask on, so it installs the Runtime as a service and skips the question about MCP servers. Move them later, from a terminal: wisp integrate hermes --connectors.
  • Once Wisp is inside Hermes, Hermes can no longer sign Wisp in: the sandbox keeps it from Wisp's login. If Wisp loses its sign-in later, run wisp login in a terminal on that machine (over SSH for a server).
  • Hermes does not read ~/.wisp or ~/.config/wisp while installing, even when a step fails: they hold Wisp's secrets. It asks wisp status and reads Wisp's log instead.

Undo it​

On one machine:

wisp integrate hermes --remove
hermes gateway restart --all

It disconnects every profile, switches the MCP servers it moved back on in Hermes (their Wisp Connectors stay), removes the plugin, and revokes the hermes credential. With --profile <name> it undoes only that profile and keeps the credential the others use.

On two machines, on Hermes's machine:

hermes wisp connect --remove
hermes plugins remove wisp

and on the Runtime's machine, wisp tokens revoke hermes.

Troubleshooting​

What you seeWhat to do
wisp: command not found right after installingOpen a new terminal, or run the source … line the installer printed. Or call it as ~/.wisp/bin/wisp.
Hermes is not on PATHInstall Hermes Agent, or run integrate from a shell where hermes works.
Hermes v… is too old for Wisp's pluginhermes update, then run integrate again.
the Runtime is not running in ~/.wispStart it: systemctl --user start wisp on Linux, launchctl kickstart -k "gui/$(id -u)/io.usewisp.runtime" on macOS, or wisp serve. wisp doctor names the cause.
Wisp is not signed inwisp login (wisp login --manual on a server).
the prepaid balance is emptywisp billing topup <amount>. See Billing.
The service stops right after installing, on a Linux server shared with other usersAnother user's Runtime holds port 3008. Give yours another port in runtime.json (see Change the port), restart it, and run integrate again.
Hermes starts with Wisp's zone is unprotected: …The sandbox did not start, and the line says why. On Linux it is almost always bubblewrap or AppArmor: run the fix wisp doctor names, then restart Hermes.
wisp doctor says the Wisp plugin is disabled, or another hermes <profile> problemRun the fix it prints: wisp integrate hermes --profile <profile>, then restart Hermes.
Hermes says Wisp is not answering, or ask_wisp is not availableThe Runtime is stopped or restarting (every wisp update restarts it), or unreachable. Hermes reconnects by itself within about 10 seconds of it coming back (a gateway's other profiles, within 5 minutes); an open Hermes Session gets ask_wisp back from its next message. If hermes mcp test wisp passes and Hermes still says so, hermes gateway restart.
Every task fails with Private Folder … was moved or … is unreadableWisp refuses Hermes's tasks until it can tell the folder is in place. Do what the message says: wisp private add <where it is now>, or wisp private remove <old path>, or unlock its parent folder.
Two machines: hermes mcp test wisp fails with HTTP 400The Runtime does not answer to that name yet: make the credential with --public-url https://<name> (step 3), and restart the Runtime.
Two machines: tailscale serve says Serve is not enabled on your tailnetOpen the link it prints and enable Serve and HTTPS certificates, then run it again.
hermes wisp connect refuses the addressUse https://…, or http://127.0.0.1:… through a tunnel. Plain http to another machine would send the credential in clear.
Telegram has no /wisp in the menuSend /restart, then close and reopen the chat. Typed, /wisp works anyway; /commands lists every command.
A Wisp confirmation was denied while you were awayHermes denies what nobody answers within its 5 minutes (approvals.timeout). Ask again. See Confirmations.
A Hermes cron job's Wisp task fails on a denied toolNobody is there to answer. Allow that tool beforehand: wisp permissions set <tool> allow.
wisp private add says Hermes keeps reading …: the sandbox cannot close a folder Hermes starts fromThe folder holds code Hermes runs from (its venv, its install), so the sandbox leaves it open to Hermes; only Wisp's own tools refuse it. Keep private files outside it, and wisp private remove <folder>.
A removed Private Folder is still closed to HermesA removal applies once integrate rewrites its record: wisp integrate hermes, then restart Hermes.
On Linux, sudo fails inside HermesExpected: setuid programs cannot work inside the sandbox. Run commands that need root outside Hermes.
A script using the agentToken from runtime.json gets 401On a machine with Wisp inside Hermes, that token changes at every Hermes start. Give the script a named token.