Hermes Agent setup

Pushary sends Hermes Agent notifications and approvals to your phone. A Python plugin adds Pushary tools to Hermes, makes Pushary the transport for Hermes's dangerous-command approvals, and routes Hermes's questions to your phone. You get a push when Hermes marks a run as failed, and you can approve or deny a flagged command from your lock screen while Hermes runs.

Set it up

npx pushary@latest setup

On Windows PowerShell, run npx.cmd pushary@latest setup. The CLI needs Node.js 20.17+, 22.13+ or 23.5+.

hermes plugins enable pushary
hermes config set security.approval.transport pushary
hermes config set security.approval.transport_fallback builtin

hermes gateway restart

On a Mac you can use Pushary Isle instead. Connecting your agents there writes the same plugin to ~/.hermes/plugins/pushary, turns it on with the same Hermes commands, and saves your key in ~/.pushary/config.json, where the plugin reads it. It needs Hermes installed, with the hermes command working.

Install from the Hermes plugin catalog

Pushary is listed in the Hermes Agent plugin catalog, so Hermes can install it for you:

hermes plugins install pushary

The catalog installs the release Nous reviewed, pinned to a commit. On Hermes v2026.9.11, run hermes update before installing: that release can read the catalog but lacks the redaction function the pinned plugin needs, so its approval cards would arrive without the command. Then select Pushary as the approval transport, as shown in Set it up by hand. If the install did not ask for your API key, save it in Hermes:

hermes config set PUSHARY_API_KEY pk_xxx.xxx

The catalog's release can be older than the one setup installs. Check version in ~/.hermes/plugins/pushary/plugin.yaml, or in the catalog entry linked above before you install. A copy older than 0.8.1 cannot tell Pushary when Hermes marks a run as failed, so the push for that run says Hermes finished. A catalog copy leaves Hermes's clarify questions in Hermes's own prompt; a copy that setup or the Mac app installed sends them to your phone. If setup or the Mac app finds a catalog copy in ~/.hermes/plugins/pushary, it keeps it and only changes the settings. From 0.8.0, a catalog copy reads your key only through Hermes, as the catalog requires, so save it with hermes config set PUSHARY_API_KEY. Never install a second copy over an existing one.

What setup changes on your computer

The settings in ~/.hermes/config.yaml after setup:

plugins:
  enabled:
    - pushary
security:
  approval:
    transport: pushary
    transport_fallback: builtin

Setup does not turn off Hermes's clarify tool. While the plugin setup or the Mac app installed is loaded, it sends clarify questions to pushary_ask. If the plugin is missing, or it is a catalog copy, Hermes asks them in its own prompt. If an older Pushary setup added clarify to agent.disabled_toolsets, setup takes it out again, unless it kept a catalog copy.

If an older Pushary setup installed hermes-plugin-pushary into Hermes's Python with pip, setup removes that copy, so Hermes loads the one in ~/.hermes/plugins/pushary.

Check that it works

npx pushary@latest doctor

Doctor checks your key and plan, that the plugin is in ~/.hermes/plugins/pushary and enabled, that approvals go through Pushary, and that questions go through Pushary. It also says whether the running Hermes has loaded the plugin: the plugin writes a file to ~/.hermes/plugin-data/pushary/loaded/ when Hermes loads it. If doctor says to restart Hermes, run hermes gateway restart. Doctor sends a real test push. Add --roundtrip to send a test question too.

Then ask Hermes to do something its dangerous-command check flags, such as deleting a scratch folder. Your phone buzzes with Hermes's four choices.

Approve Hermes's dangerous commands from your phone

Hermes already detects dangerous commands and asks a person before it runs them. With security.approval.transport: pushary, that question goes to your phone instead of a terminal nobody is watching. You get the same four choices Hermes offers in the terminal:

How long your phone has depends on your approval mode. In Always, it is Hermes's own approvals.timeout (300 seconds by default). In When away, your phone has the push window, then Hermes's own prompt takes over.

transport_fallback: builtin makes the transport safe to leave on. If your key is missing, your mode is In agent, or no device can be reached, Pushary steps aside (withdrawing any question it already sent) and Hermes asks in its own prompt. If cancellation says stop, or Pushary cannot confirm the withdrawal, the command is denied. A network failure while Pushary waits never reopens approval silently. Remove the transport_fallback line and an unreachable Pushary becomes a denial instead.

Gate named tools with PUSHARY_GATE_TOOLS

To gate specific tools rather than Hermes's dangerous-command set, list them in PUSHARY_GATE_TOOLS. The check runs in the plugin's blocking pre_tool_call hook.

export PUSHARY_GATE_TOOLS="terminal,write_file"
export PUSHARY_GATE_TIMEOUT_MS=25000

Hermes abandons any pre_tool_call callback that outlives plugins.hook_callback_timeout (30 seconds by default). The plugin keeps its wait inside that limit. PUSHARY_GATE_TIMEOUT_MS defaults to 55000 and is capped by it. Raise plugins.hook_callback_timeout to give your phone longer, up to the plugin's own limit of 55 seconds.

When Pushary is also the selected transport, the transport wins. The hook hands the call to Hermes's own approval gate, which gets the full 300-second window and the four choices. Always allow on such a call creates a standing rule for the whole tool name, including future calls with different arguments. Choose Allow once when you mean only the call on screen.

Hermes approvals off (dangerously skip permissions)

Hermes's approvals.mode: off turns off its native approval enforcement. Hermes then raises no dangerous-command approvals, so the Pushary transport has nothing to send. Plain MCP, the plugin's question tools and the skill only make questions cooperative: the agent decides whether to ask, so they are not an enforced gate. PUSHARY_GATE_TOOLS with no transport selected asks Pushary directly from the plugin's own hook. With the transport selected, it hands the call to Hermes's approval gate instead.

Hermes notifications and tools

The plugin registers 8 native Hermes tools:

Automatic notifications:

• Failed runs: when Hermes marks a turn as failed, the push for that turn reads "Hermes run failed" with the reason Hermes gives, instead of "Hermes finished". It follows your updates setting, like every turn-end push. A tool call that fails along the way, such as a grep that finds nothing, does not reach your phone, because Hermes recovers from it. A provider error that stops Hermes before it finishes the turn, such as a rejected API key, sends no push.
• Session end: set PUSHARY_AUTO_NOTIFY_SESSION_END=1 to get a summary with tool and error counts when a session ends. Completed sessions use task-completion routing.

Hermes redacts gated argument summaries, targets and the reason a turn failed before they are shortened or sent. If the host redactor is missing or fails, that detail is left out.

For questions, pushary_ask does its first wait and one server-directed poll per call; use pushary_wait with the same id while pending. Follow answered, status and handoffAction (or nextAction). Do not create a duplicate question or cancel a pending one because a poll ended. Cancel a live question before moving it to the current chat, stop if cancellation says stop, and if cancellation loses a race, poll once for one second and honor the winning answer. Silence is never approval.

Environment variables

When to use Pushary and when to use Hermes's chat platforms

Hermes can also talk to you through chat platforms such as Telegram, Discord and Slack. Use Pushary when you have no active chat open, when a quick decision should reach your lock screen, when a background task or cron job finishes, or when Hermes flags a dangerous command. Use the active chat platform when you are already in the conversation and the question is part of it.

Set it up by hand

Hermes now manages its own Python, and it does not support installing plugins into it with pip. Install Pushary as a folder plugin instead.

Copy the pushary_plugin folder from Pushary/hermes-plugin-pushary to ~/.hermes/plugins/pushary:

git clone --depth 1 https://github.com/Pushary/hermes-plugin-pushary /tmp/hermes-plugin-pushary
mkdir -p ~/.hermes/plugins
cp -R /tmp/hermes-plugin-pushary/pushary_plugin ~/.hermes/plugins/pushary

Turn it on with Hermes's own commands:

hermes config set security.approval.transport pushary
hermes config set security.approval.transport_fallback builtin
hermes plugins enable pushary

Save your key in Hermes. A copy you placed by hand reads the key only through Hermes, not from ~/.pushary/config.json:

hermes config set PUSHARY_API_KEY pk_xxx.xxx

Restart Hermes with hermes gateway restart, then run npx pushary@latest doctor.

A copy made by hand does not send Hermes's clarify questions to your phone, and setup will not overwrite it. To switch to setup later, delete ~/.hermes/plugins/pushary first.

Use MCP instead of the plugin

You can connect Hermes to the Pushary MCP server instead. Add this to ~/.hermes/config.yaml:

mcp_servers:
  pushary:
    url: https://pushary.com/api/mcp/mcp
    headers:
      Authorization: "Bearer ${PUSHARY_API_KEY}"

Then install the Pushary skill, so Hermes knows when to notify you and how to choose between Pushary and the active chat platform:

hermes skills tap add Pushary/pushary-skill
hermes skills install pushary

The MCP route gives Hermes the agent tools under their MCP names (send_notification, ask_user, wait_for_answer, cancel_question and propose_scope). It has none of the plugin's automatic notifications and no approval transport.

Turn it off

There is no pushary disconnect for Hermes. Use Hermes's own commands instead, then restart Hermes:

• To send approvals back to the terminal, run hermes config unset security.approval.transport.
• To turn the plugin off, run hermes plugins disable pushary. Hermes then asks its clarify questions in its own prompt again.

npx pushary@latest clean removes Pushary from this computer, for every agent. For Hermes it removes the plugin folder with hermes plugins remove pushary if Pushary installed it, puts the approval settings back from ~/.pushary/setup/hermes-plugin.json, and deletes that record and the older hermes-config.json. A copy from the Hermes plugin catalog stays in place, switched off unless it was on before setup. While Pushary Isle is installed, clean leaves a Hermes setup the app connected, and the key the app saved for it, to the app. Add --dry-run to see what it would change first.

Troubleshooting

Pushary stopped working after hermes update

Hermes now runs from Python it manages itself, so the pip copy that older Pushary setups installed no longer loads. Run npx pushary@latest setup --agents hermes to move to the plugin folder. npx pushary@latest upgrade does the same when it installs a newer version. On a Mac, update Pushary Isle and reopen it: it moves Hermes over when it starts. Then run hermes gateway restart.

Setup says the Hermes CLI was not found

Setup looks for hermes on your PATH, then in ~/.local/bin, /opt/homebrew/bin and /usr/local/bin. Install Hermes, check that hermes runs in a new terminal, then run setup again.

Setup says a pushary plugin it did not install is in the way

~/.hermes/plugins/pushary holds a plugin that neither Pushary nor hermes plugins install put there. Remove that folder, then run setup again.

Setup says Hermes would not report its settings

Setup reads Hermes's settings with hermes config get. Run hermes update, then run setup again.

Setup wrote the plugin but Hermes refused a settings change

Run hermes plugins enable pushary, then run setup again. Or run the commands in Set it up by hand yourself.

Doctor says to restart Hermes

The plugin is installed, but the running Hermes started before it, or still runs an older Pushary plugin. Run hermes gateway restart, and start a new terminal session if you use one.

Doctor says approvals stay in the terminal

security.approval.transport is not pushary in ~/.hermes/config.yaml. Run npx pushary@latest setup --agents hermes again, or set it by hand.

Next steps