Integration
Hermes Agent Signal Setup: Connect a Private AI Agent
Set up Hermes Agent with Signal using signal-cli, a linked device, allowlisted users, group controls, cron delivery, and an end-to-end gateway test.
Quick answer
Hermes connects to Signal through a local signal-cli daemon running in HTTP mode. Install signal-cli and Java 17+, link it as a secondary device, start the daemon on 127.0.0.1:8080, then run hermes gateway setup. Keep DMs behind pairing or SIGNAL_ALLOWED_USERS, leave groups disabled until you explicitly allow them, and prove the setup with one real Signal reply.
signal-cli, linked device, allowlists, and smoke test · Avoid maintaining daemon and gateway uptime yourself
Best for
Solo operators who want a private phone interface through Signal Note to Self.
Security-conscious teams that already use Signal and can maintain a dedicated linked device.
Mobile approvals, incident summaries, cron reports, and concise operational requests.
People who want Signal transport while keeping Hermes tools, memory, and credentials isolated in one profile.
Features
- ✓Real-time inbound messages over signal-cli Server-Sent Events (SSE)
- ✓Outbound replies through signal-cli JSON-RPC
- ✓DM access through explicit E.164 allowlists or Hermes pairing codes
- ✓Groups disabled by default until
SIGNAL_GROUP_ALLOWED_USERSis configured - ✓Images, audio, video, and documents as native Signal attachments
- ✓Native formatting, quoted replies, reactions, and typing indicators on current signal-cli builds
- ✓Phone-number redaction in gateway logs and optional PII redaction before model calls
- ✓Cron delivery through a deliberate
SIGNAL_HOME_CHANNELtarget
Setup path
- 1Install Java 17+ and
signal-cli. On macOS, runbrew install signal-cli; on Linux, install the current signal-cli release rather than expecting an apt or snap package. - 2Link the daemon as a secondary Signal device with
signal-cli link -n "HermesAgent", then approve it from Signal → Settings → Linked Devices on your phone. - 3Start the local daemon with
signal-cli --account +YOUR_NUMBER daemon --http 127.0.0.1:8080. Keep the HTTP endpoint bound to loopback unless you have a deliberate private-network design. - 4Verify signal-cli before involving Hermes:
curl http://127.0.0.1:8080/api/v1/checkshould return version information. - 5Run
hermes gateway setup, choose Signal, keep the default HTTP URL when local, enter the linked E.164 account number, and configure allowed users. - 6Start or restart the gateway with
hermes gateway restart, then inspecthermes gateway statusand recent~/.hermes/logs/agent.logentries. - 7Send one harmless DM from an allowlisted number or use Note to Self when
SIGNAL_ACCOUNTis your own linked number. Count the setup as working only after Signal receives the reply. - 8Add
SIGNAL_HOME_CHANNELfor scheduled delivery orSIGNAL_GROUP_ALLOWED_USERSfor specific groups only after the private smoke test passes.
How the Hermes Signal gateway actually works
Signal is not a hosted bot API inside Hermes. A separate signal-cli process links to your Signal account and exposes a local HTTP daemon. Hermes keeps an SSE connection open for incoming messages and uses JSON-RPC for replies. That product boundary matters: Hermes can be healthy while signal-cli is stopped, unlinked, or running under a different account.
- •Signal phone app remains the primary device; signal-cli is a linked secondary device.
- •The normal local endpoint is
http://127.0.0.1:8080, not a public internet port. - •Hermes needs
SIGNAL_HTTP_URLandSIGNAL_ACCOUNT; signal-cli owns the linked-device session.
DM pairing, allowlists, and group access
Treat a Signal chat as an input surface to a tool-using agent, not as an ordinary chatbot. Set SIGNAL_ALLOWED_USERS for known E.164 numbers or UUIDs, or let unknown DM users receive a pairing code that you approve with hermes pairing approve signal CODE. Group messages are ignored by default and should stay that way until a real use case justifies explicit group IDs.
- •
SIGNAL_ALLOWED_USERS=+15551234567creates a narrow DM allowlist. - •No DM allowlist uses Hermes pairing;
SIGNAL_ALLOW_ALL_USERS=trueis broader and should be used cautiously. - •
SIGNAL_GROUP_ALLOWED_USERSaccepts specific group IDs;*means every group and is rarely the right first setup.
Signal limitations to know before choosing it
Signal is strong for private final answers, approvals, alerts, and file delivery, but it cannot edit a sent message. Hermes therefore suppresses live tool-progress bubbles and progressive streaming on Signal. Use the CLI or an editing-capable gateway when watching each tool call matters; use Signal when a concise final answer and privacy-focused transport matter more.
- •Typing indicators work, but per-tool progress bubbles do not.
- •Signal has no thread primitive for continuable cron handoffs, so Hermes falls back to the origin DM pattern.
- •Native formatting and quoted replies depend on a current signal-cli build; older versions can fall back to plaintext.
Note to Self versus a dedicated bot number
For a solo setup, signal-cli can link to your own Signal number and Hermes can answer inside Note to Self. That is the fastest private test because no second account is required. A dedicated number is cleaner for teams or long-running operations because the bot identity, linked-device session, allowlists, and incident recovery stay separate from a personal account.
- •Solo test: link your own number and send a Note to Self message.
- •Team operation: prefer a dedicated Signal identity and a dedicated Hermes profile.
- •In both cases, protect
~/.local/share/signal-cli/because it contains account credentials.
Cron reports and always-on operation
Set SIGNAL_HOME_CHANNEL only after ordinary replies work. A successful cron execution is not delivery proof: verify the configured target, the running gateway, the signal-cli daemon, and the actual message in Signal. Self-hosters own Java and signal-cli updates, linked-device health, daemon supervision, Hermes gateway uptime, provider credits, logs, and backups.
- •Use
hermes cron listto confirm the job andhermes gateway statusto confirm the delivery process. - •Send one manual catch-up report when a repaired daily job missed its intended delivery window.
- •Choose FlyHermes when the business requirement is managed uptime rather than maintaining this service chain.
Common setup issues
Cannot reach signal-cli— startsignal-cli --account +YOUR_NUMBER daemon --http 127.0.0.1:8080, then verify/api/v1/checkbefore restarting Hermes.- Messages are not received — confirm the sender is in
SIGNAL_ALLOWED_USERSusing E.164 format, or complete DM pairing instead of assuming the device link grants access. - Group messages are ignored — this is the safe default; add exact group IDs to
SIGNAL_GROUP_ALLOWED_USERSonly when group access is intended. - The connection keeps dropping — verify Java 17+, inspect signal-cli logs, and make sure the linked device is still valid. Hermes retries the SSE connection with backoff but cannot repair an unlinked account.
- Duplicate messages appear — ensure only one signal-cli daemon and one Hermes gateway instance are handling the linked number.
- No live tool progress appears — Signal cannot edit sent messages, so Hermes intentionally delivers typing indicators and the final response without progress bubbles.
- Cron runs but Signal gets nothing — verify
SIGNAL_HOME_CHANNEL, gateway uptime, the active profile, provider health, and one real manual message to the same target.
Keep building the workflow
Hermes gateway troubleshooting
Debug a connected gateway that still does not receive or deliver real messages.
Hermes cron scheduling
Schedule reports, target a delivery channel, and verify that the message actually arrived.
Hermes profiles for isolated bots
Separate Signal credentials, tools, skills, memory, and sessions from other agents.
Run Hermes from your phone
Compare Signal, Telegram, Discord, browser access, and managed mobile operation.
Pricing and managed cloud
Compare self-hosted daemon and gateway maintenance with the managed FlyHermes path.
FAQ
Does Hermes Agent connect directly to Signal?
Hermes uses an external signal-cli daemon in HTTP mode. The adapter receives messages over SSE and sends replies through JSON-RPC.
Do I need a second Signal phone number?
No. You can link signal-cli to your own number and use Note to Self for a solo setup. A dedicated number is cleaner for team or production use.
What Signal environment variables does Hermes use?
The required variables are SIGNAL_HTTP_URL and SIGNAL_ACCOUNT. Common security and delivery settings are SIGNAL_ALLOWED_USERS, SIGNAL_GROUP_ALLOWED_USERS, SIGNAL_ALLOW_ALL_USERS, and SIGNAL_HOME_CHANNEL.
Why does the Signal bot ignore group messages?
Groups are disabled by default. Configure specific IDs in SIGNAL_GROUP_ALLOWED_USERS, or * only if you deliberately want every joined group.
Can Hermes show live tool progress in Signal?
No. Signal cannot edit already-sent messages, so Hermes suppresses progress bubbles and streaming previews. Typing indicators and final replies still work.
Can Signal deliver Hermes cron reports?
Yes. Set SIGNAL_HOME_CHANNEL or an explicit Signal delivery target, keep signal-cli and the Hermes gateway running, and verify the actual message rather than relying only on job status.
Should I self-host Signal access or use FlyHermes?
Self-host when you want to own the linked device, daemon, gateway, provider keys, and logs. Choose FlyHermes when managed uptime and phone access matter more than operating that infrastructure yourself.