Blog / channel guide

Hermes Agent Signal Setup with signal-cli

To run Hermes Agent on Signal, either register a dedicated phone number through signal-cli or link the assistant as a secondary device to an existing account, then connect that session to Hermes Agent. Linking requires scanning a QR code once and keeps your primary device as the source of truth.

Updated Sep 11, 20269 min read

Deployment route

01
Choose between a dedicated number and linked device
A dedicated number gives the assistant its own identity. Linking keeps your existing account and adds the assistant as a secondary device.
02
Prepare the signal-cli session
Install signal-cli or use the managed runtime that bundles it, then register a number or link the device and unlock the local session store.
03
Complete verification
Enter the registration or linking code, and confirm the device appears in the Signal settings of your primary phone.
04
Deploy Hermes Agent with Signal selected
Choose a model, select Signal as the channel, and provide the session data the runtime needs to send and receive.
05
Send a direct message to the assistant
Write from a known contact, confirm the assistant replies, and check that the reply lands in the same conversation.
06
Decide on group behaviour deliberately
Leave groups disabled until the direct message path is stable, then enable one group at a time and watch how the assistant responds to mentions.

Four-step path

How do you connect Hermes Agent to Signal?

Five checkpoints: choose a number strategy, install or provision signal-cli, link or register the account, deploy with the session, then send a verified direct message.

Step 01
Choose between a dedicated number and linked device
A dedicated number gives the assistant its own identity. Linking keeps your existing account and adds the assistant as a secondary device.
Step 02
Prepare the signal-cli session
Install signal-cli or use the managed runtime that bundles it, then register a number or link the device and unlock the local session store.
Step 03
Complete verification
Enter the registration or linking code, and confirm the device appears in the Signal settings of your primary phone.
Step 04
Deploy Hermes Agent with Signal selected
Choose a model, select Signal as the channel, and provide the session data the runtime needs to send and receive.
Step 05
Send a direct message to the assistant
Write from a known contact, confirm the assistant replies, and check that the reply lands in the same conversation.
Step 06
Decide on group behaviour deliberately
Leave groups disabled until the direct message path is stable, then enable one group at a time and watch how the assistant responds to mentions.

What do you need before running Signal?

You need either a phone number you control for registration or an existing Signal account you can link as a secondary device, plus a runtime that can keep the signal-cli session persistent.

Signal ties an account to a phone number, which is the main difference from Telegram or Slack. Decide up front whether the assistant owns its own number or shares your identity as a linked device.

Should the assistant use a dedicated number or a linked device?

Use a dedicated number when you want a separate identity, cleaner audits, and no dependency on your phone. Link a device when you want the assistant to answer as you from an existing account.

Dedicated number: clearer ownership, no phone dependency, separate contact card.
Linked device: replies appear as you, which can confuse recipients.
Linked devices must be re-linked if the primary device is unregistered.
Either way, keep the session store backed up and protected.

Why does the Signal session keep breaking?

Signal sessions break when the runtime restarts without a persistent volume, when the account is re-registered on another device, or when the session store is deleted during a redeploy.

Always back the signal-cli session store with persistent storage.
Never register the same number on two conflicting accounts.
Re-link rather than re-register if the assistant was a secondary device.
Re-check the connection after every runtime restart or redeploy.

Why is the Signal assistant silent?

The most frequent causes are an expired linked session, a registration that was superseded on another device, or a runtime that lost its session volume during a restart.

Confirm the assistant still appears in the Signal linked devices list.
Check the runtime logs for a session or registration error.
Verify the session volume is mounted and writeable.
Send a direct message before testing groups or disappearing-message chats.

How private is a Signal-based assistant?

Signal protects the transport, but the assistant still processes message text on your infrastructure or your provider's. Privacy depends on where the runtime and the model run, not only on the messenger.

If the content is sensitive, prefer a deployment you control and keep the assistant out of conversations it does not need to read. Transport encryption does not reduce what the model sees.

Which primary sources support this page?

Product behavior is checked against the current deployment flow. These external links provide the upstream project or channel documentation used for setup details.

Direct answers

Frequently asked questions

Do I need a separate phone number for Signal?

Not always. You can link the assistant as a secondary device to an existing account, but a dedicated number gives cleaner ownership and fewer conflicts.

Can Hermes Agent work in Signal groups?

Yes, once the session is stable and the assistant is added to a group. Start with direct messages before enabling group behaviour.

What happens if I unlink the device?

The assistant loses access immediately. Re-link the device or register the number again, then redeploy so the runtime picks up the new session.

Is the message content end-to-end encrypted end to end?

Signal encrypts the transport between devices. The assistant still decrypts and processes message text, so protect the runtime and the session store.

Key takeaways

To run Hermes Agent on Signal, either register a dedicated phone number through signal-cli or link the assistant as a secondary device to an existing account, then connect that session to Hermes Agent. Linking requires scanning a QR code once and keeps your primary device as the source of truth.
Start with one model, one channel, and one controlled test conversation.
Use managed hosting when deployment speed matters more than operating the server yourself.

Continue the setup

Blog guide

Hermes Agent iMessage Setup via BlueBubbles

Connect Hermes Agent to iMessage with BlueBubbles on a Mac. Covers server setup, Apple ID choices, API password, webhooks, and delivery troubleshooting.

Read next

Blog guide