hermes-bridge

Hermes Bridge API

The Hermes Bridge API serves as a lightweight REST + SSE bridge that connects Hermes Agent to mobile applications and HTTP clients. Designed with compatibility in mind, it operates efficiently alongside Agentfy, an iOS application, and is provider-agnostic, eliminating the need for complex WebSocket or custom handshake processes.

Key Features

• Effortless Interaction: Chat with any Hermes agent via simple HTTP requests. The API supports token-by-token streaming using Server-Sent Events (SSE).
• Multi-Agent Support: Manage multiple agents by creating, editing, and listing them, ensuring isolated session handling for each.
• Skill Management: Explore the catalog of skills available in ~/.hermes/skills/, and attach or detach skills to agents with ease.
• Dynamic Model Routing: Access and switch between different models for an agent on the fly.
• Secure API Key Management: The API provides a mechanism to read and write API keys securely from ~/.hermes/.env, keeping sensitive information hidden from mobile clients.
• TTS Proxy Functionality: Utilize ElevenLabs or OpenAI for text-to-speech and transcription services directly routed server-side.
• Session Persistence: Save message history in the Hermes SQLite database with options for importing and exporting data efficiently.
• Device Pairing: Simplify the connection process with a QR-code pairing mechanism for the Agentfy app.

Requirements

To utilize the Hermes Bridge API, ensure the following:

• Python version 3.11+ (compatible with the Hermes installation)
• A valid Hermes Agent installation at ~/.hermes/hermes-agent, which will be imported at runtime.

Running the API

Establishing the bridge is straightforward. The repository provides an installation script that checks for your Hermes setup and installs the necessary components:

git clone https://github.com/jcnh74/hermes-bridge.git
cd hermes-bridge
./install.sh

To verify the setup, use the command:

hermes-bridge doctor

To start the Hermes Bridge API, perform:

hermes-bridge start

The API responds on the route http://localhost:8765/api/v1, providing health checks and status updates on the agents.

API Overview

Some key API endpoints include:

• Health Check: GET /health - Returns the health status of the API and feature flags.
• Agent Management: GET /agents - List all available Hermes agents, while POST /agents creates new agents.
• Session Handling: POST /sessions establishes a session with an agent, enabling real-time message exchanges.

Connecting to Agentfy

In Agentfy, establish a connection to the bridge API by either using the API URL directly or leveraging a QR code for quick pairing. Ensure proper tunneling or proxy setup if accessing it over the internet to maintain security and integrity.

Architecture Summary

The architecture of the Hermes Bridge integrates seamlessly with existing Hermes installations, maintaining shared configurations and data. By adhering to this design, the API inherits the robust pipeline of the Hermes Agent, ensuring consistent functionality and performance without including Hermes resources directly.

Security Considerations

Given the sensitive nature of API interactions, it is recommended to keep API keys stored securely within the ~/.hermes/.env directory. When deploying the Hermes Bridge, avoid direct exposure to the public internet and instead leverage authenticated tunnels or reverse proxies for secure access.