hermes acp
hermes-acp
python -m acp_adapter

hermes acp --version
hermes acp --check

hermes acp --setup-browser

hermes acp --setup-browser --yes

Connecting Editors

Connect VS Code

1. Install the ACP Client extension.
2. Open the ACP Client panel from the Activity Bar.
3. Select Hermes Agent from the built-in agent list.
4. Connect and start chatting.

Optional manual definition: add to VS Code settings under acp.agents:

{"Hermes Agent": {"command": "hermes", "args": ["acp"]}}

Connect Zed

1. Open the Agent Panel.
2. Add a custom agent server with the following configuration:

   {"agent_servers": {"hermes-agent": {"type": "custom", "command": "hermes", "args": ["acp"]}}}
   

3. Start a new Hermes external-agent thread.

Prerequisite: configure Hermes provider credentials with hermes model, or set them in ~/.hermes/.env or ~/.hermes/config.yaml.

Connect JetBrains

1. Use an ACP-compatible plugin.
2. Point it at hermes acp or hermes-acp.

Connect Buzz Desktop

1. Ensure Hermes is installed normally; Buzz discovers it automatically (Settings → Runtimes).
2. If discovery fails, ensure hermes-acp or hermes is on the login-shell PATH:

   command -v hermes-acp || command -v hermes
   

3. Recent installs write both launchers into ~/.local/bin. Run hermes update to add hermes-acp to older installs.
4. Manual fallback: configure the Buzz agent command as hermes with args ["acp"].

Configure Model in Buzz Desktop

In Buzz Desktop v0.5.1+, the model menu shows all models from authenticated providers. Entry IDs follow the format provider:model (e.g., openrouter:z-ai/glm-5.1) or custom:<name>:<model> for custom OpenAI-compatible endpoints.

Picking a model applies to that agent's session only; it does not change the Hermes-wide default. Use hermes model for that.

Keep Buzz Agents Owner-Only

Leave "Who can talk to this agent" set to "Owner only". Do not select "Anyone" — it grants shell access to all channel authors without prompting.

Note: approvals.mode: manual does not prevent auto-approval by Buzz. platform_toolsets.acp cannot drop the terminal tool. Use !shutdown from the owner to stop the agent in any mode; Buzz ignores it from others.

Parameters

HERMES_ACP_SKIP_CONFIGURED_MCP

Set to exactly 1 to skip starting globally configured MCP servers from config.yaml before the ACP JSON-RPC loop. Hosts that own MCP themselves can use this to avoid delays from unrelated servers. Only global discovery is skipped; MCP servers from session/new are still registered.

Not required. Default is unset/0/false, which keeps default behavior.

BUZZ_RELAY_URL

WebSocket URL of the Buzz relay (e.g., wss://community.example.com). Required for the Buzz bridge.

BUZZ_PRIVATE_KEY

Nostr private key for the Hermes agent identity. Do not commit or paste. Required for the Buzz bridge.

BUZZ_API_TOKEN

API token for relay authentication (only if relay enforces token auth). Do not commit or paste. Conditionally required.

BUZZ_ACP_AGENT_COMMAND

Command to launch Hermes (e.g., 'hermes'). Required for the Buzz bridge.

BUZZ_ACP_AGENT_ARGS

Arguments for the command (e.g., 'acp'). Required for the Buzz bridge.

BUZZ_ACP_RELAY_OBSERVER

Set to 'true' to publish encrypted kind 24200 observer frames to the agent's owner for live activity logging in Buzz Desktop. Not required.

BUZZ_ACP_AGENT_OWNER

Restricts which Buzz users can prompt the agent (owner-only respond gate). Not required.

Constraints and Caveats

• ACP sessions are tracked only while the server is running. List, load, resume, and fork operations are scoped to the current process.
• The working directory binds the editor's cwd to the Hermes task ID. File and terminal tools run relative to the editor workspace, not the server process cwd.
• Approval prompts may be answered programmatically by the host (e.g., Buzz Desktop auto-approves). Treat this as unattended execution regardless of the approvals setting.
• On timeout or error, the approval bridge denies the request.
• allow_session approval is scoped to the current ACP session only. It is cleared when the session ends or the editor restarts.
• allow_always writes a permanent allowlist entry that persists across restarts.
• allow_once applies only to the current tool call.
• The Buzz bridge auto-approves permission requests with allow_once. Terminal and execute_code run without prompting.
• Neither approvals.mode: manual nor platform_toolsets.acp can prevent Buzz from auto-approving or narrow the toolset.
• Do not set host integration variables like HERMES_ACP_SKIP_CONFIGURED_MCP by hand in .env or config.yaml.
• Browser tools require Node.js 22 LTS and npm packages; they are not part of the Python wheel.
• The Buzz bridge discovers channels automatically via membership. There is no separate channel list in Hermes config.
• Observer frames are ephemeral on the relay. The Desktop must be online before the turn starts for durable history.
• The model picker shows only models from providers with configured credentials. A missing model means missing credentials.
• Picking a model in Buzz Desktop does not change the Hermes-wide default.
• Buzz creates every agent with "Owner only" by default. Selecting "Anyone" grants shell access to all channel authors without warning.
• Use a dedicated Nostr keypair for each agent. Do not reuse a human keypair.
• Do not commit or paste private keys or API tokens.
• For a persistent Buzz bridge, run it under a service manager as the same OS user that owns the Hermes home.

Failure Modes

ACP Agent Does Not Appear in Editor

Possible causes:

• The host command is not pointing to hermes acp.
• Hermes is not on the PATH.
• The ACP extra is not installed.

ACP Starts but Immediately Errors

Run the following diagnostic commands:

hermes acp --version
hermes acp --check
hermes doctor
hermes status

Missing Credentials

Configure credentials with hermes model or edit ~/.hermes/.env. Use hermes acp --setup for interactive setup.

Buzz Desktop Discovery Fails

Ensure hermes-acp or hermes is on the login-shell PATH. Run hermes update. Manually configure the command and args.

Browser Tools Fail

Node.js or npm packages are not installed. Run hermes acp --setup-browser.

Examples

VS Code Example

Open the ACP Client panel, select Hermes Agent, connect, and start chatting.

Zed Example

Add a custom agent server with command 'hermes' and args ['acp'], then start a new thread.

Buzz Desktop Example

Open Settings → Runtimes. Hermes appears automatically. If not, configure the command as 'hermes' with args ['acp'].

Buzz Bridge Example

Set the environment variables and run buzz-acp. The bridge discovers channels automatically.

Model Picker Example

In Buzz Desktop v0.5.1+, select a model from the menu. Entry IDs look like openrouter:z-ai/glm-5.1.

Session-Scoped Approval Example

In the editor, pick "Allow for session" to approve matching commands for the current session only.