Signal Gateway for Private Rocky Workflows

Hermes connects to Signal through a separately installed signal-cli daemon running in HTTP mode. The adapter receives events over Server-Sent Events and sends replies through JSON-RPC, keeping the Signal-specific transport outside the core agent loop.

Official documentation: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/signal

Architecture and fit

Signal is a strong fit for privacy-sensitive operator conversations because the service uses end-to-end encryption by default. Hermes still runs tools on the machine hosting the gateway, so encrypted transport does not eliminate endpoint risk. Authorization, local account storage, tool permissions, and host security remain important.

signal-cli links as a secondary device. The phone remains the primary Signal device, while the daemon exposes a loopback HTTP endpoint for Hermes. A single-number setup can use Signal’s Note to Self conversation.

Setup checklist

Install a current signal-cli build and Java runtime.
Link it as a named secondary device.
Start the daemon on a loopback-only address.
Verify the daemon’s check endpoint before configuring Hermes.
Run hermes gateway setup and select Signal.
Set the account in E.164 format.
Add allowed users or use the pairing flow.
Leave groups disabled unless specific group IDs are approved.
Configure a home channel only after direct messaging is proven.

Access and media boundaries

Direct messages are denied unless an allowlist, pairing decision, or explicit allow-all policy authorizes the sender. Group processing is a separate control: with no group allowlist, group messages are ignored. That separation prevents a private DM setup from silently becoming a room-wide agent.

The adapter supports files, images, audio, and video. Treat attachment support as an ingestion boundary. Scan or restrict unexpected files according to the host’s risk profile, and never assume encrypted delivery makes an attachment safe to open.

Common pitfalls

Running two daemons for the same Signal account and receiving duplicates.
Binding the daemon to a public interface without a network-layer reason.
Using a number without its + country code.
Allowing all groups because one test room failed to respond.
Expecting editable live tool-progress messages on a platform that cannot edit sent messages.
Forgetting that phone numbers and local signal-cli account data remain sensitive on the gateway host.

Verification steps

Query the local daemon check endpoint.
Start Hermes and confirm the Signal adapter reaches a healthy state.
Send a harmless Note to Self or allowed-user message.
Confirm a non-allowed sender is rejected or offered the intended pairing path.
Test one small attachment in each required direction.
Restart signal-cli and verify the adapter reconnects.
Confirm unapproved groups remain silent.
Review logs for redaction and ensure full phone numbers are not exposed.

A reliable Signal deployment proves both transport recovery and authorization behavior. Privacy comes from the complete system, not from the messenger name alone.