How to set up Hermes Agent on Signal

What you need

Hermes connects through signal-cli, an external client linked to your Signal account. A daemon, a process that stays running, passes messages between Signal and the Hermes gateway. This is a bridge setup rather than a Signal bot account API.

For background, see Hermes Agent messaging gateway explained.

Linking signal-cli adds a device that can decrypt incoming Signal messages on this computer. Use a dedicated Signal account to keep personal chats separate. Messages sent to Hermes are processed by its configured model provider and tools.

If another service on this computer already uses port 8080, choose another port and use it consistently wherever this guide shows 8080.

• Hermes Agent installed with a model provider configured.
• Signal on your phone and the phone number for the account you will link.
• signal-cli installed using its own installation instructions. Hermes lists Java 17+, but the current signal-cli README requires JRE 25 for its Java build. Follow the requirements for the release you install.
• A host that stays awake and online, with both signal-cli and the Hermes gateway running when you want replies.

Install and link signal-cli

Use the installation instructions at signal-cli installation instructions↗ (opens in a new tab) for your operating system. Keep signal-cli current: its maintainers warn that old releases can stop working after Signal server changes.

Run the linking command below. On your phone, open Signal, go to Settings, then Linked Devices, and choose Link New Device. Follow the linking prompt using the QR code or URI produced by signal-cli. Your phone remains the primary device.

Link the secondary device

signal-cli link -n "HermesAgent"

Protect the session data in ~/.local/share/signal-cli/ like a password. It contains account credentials. Do not share it or include it in a support screenshot.

Start the Signal bridge

Replace +15551234567 with your Signal account number in E.164 format: a plus sign, country code and number. Start the daemon, leave it running, then check it from a second terminal.

The example listens on 127.0.0.1, also called loopback. Only programs on that computer can connect to this address. Keep this local setup for the first connection.

Terminal 1: run signal-cli

signal-cli --account +15551234567 daemon --http 127.0.0.1:8080

Terminal 2: check the daemon

curl http://127.0.0.1:8080/api/v1/check

The official docs describe a response containing signal-cli version information. If the check cannot reach the daemon, resolve that before configuring Hermes.

Connect it to Hermes

Run the gateway wizard and select Signal. It checks for signal-cli, asks for the HTTP address, tests the connection, then asks for the account number and allowed users. The allowed-users prompt defaults to the account number.

Alternatively, edit ~/.hermes/.env using the example below. Replace both example phone numbers: SIGNAL_ACCOUNT is the linked account, while SIGNAL_ALLOWED_USERS names the people allowed to use the agent.

Gateway wizard

hermes gateway setup

~/.hermes/.env (manual alternative)

SIGNAL_HTTP_URL=http://127.0.0.1:8080
SIGNAL_ACCOUNT=+15551234567
SIGNAL_ALLOWED_USERS=+15551234567,+15559876543

Choose who can talk to it

An allowlist is an explicit list of people allowed to use the agent. Set SIGNAL_ALLOWED_USERS to comma-separated E.164 phone numbers or Signal UUIDs. Grant access only to people you trust with the agent's tools, which can include terminal access.

DM pairing is another route. If your policy offers an unknown direct-message sender a code, review the request locally before approving it. With a restrictive allowlist or policy, unknown senders can be ignored instead. Do not expect a pairing code in every configuration.

In hermes gateway setup, answer No to “Enable group messaging?” unless you need groups. If you answer Yes, enter specific group IDs. Pressing Enter with no existing group list saves *, allowing all groups.

• Leave SIGNAL_ALLOW_ALL_USERS unset for this setup.
• Leave SIGNAL_GROUP_ALLOWED_USERS unset to ignore group messages. Despite its name, this setting takes group IDs. Add only specific trusted group IDs if you need groups; * monitors every group the account belongs to.
• A group setting and a sender's permission are separate checks. Do not treat permission to monitor a group as permission for every member to operate the agent.

Approve a code only after checking the sender

hermes pairing approve signal CODE

Start the gateway and send your first message

With signal-cli still running, start Hermes in another terminal. Send a short text from an allowed account to the linked Signal account.

If you linked your own number, use Signal's Note to Self from your phone. The platform docs describe this route when SIGNAL_ACCOUNT matches your number. Include your number in the allowlist.

Run the gateway in the foreground

hermes gateway

Look for the inbound message in the gateway output and a reply on your phone. Ctrl+C stops the foreground gateway.

What it can do

The gateway comparison table lists images, files and typing indicators for Signal. It does not mark voice, threads, reactions or streaming as supported. The Signal page gives more detail and differs from that table on audio and reactions.

• The Signal page describes incoming images, documents and audio. Incoming voice transcription needs Whisper configured. Outgoing audio is sent as an attachment, alongside support for images, video and documents.
• The page states a 100 MB attachment limit in either direction and warns that Signal rate-limits uploads.
• It also describes native formatting, quoted replies and reactions, with plaintext fallback on older signal-cli versions. A quoted reply does not establish support for separate threaded conversations.
• Long replies are split into numbered messages. Signal cannot edit sent messages, so Hermes suppresses live tool-progress bubbles even when verbose mode is enabled.

Keep it running

The bot is silent while its computer sleeps or is switched off. Keep the Hermes host awake and online whenever you need replies. A background service does not prevent sleep.

Both processes must stay running: the Hermes gateway and the separate signal-cli daemon. Installing the Hermes service does not manage signal-cli for you. The Signal docs suggest a service or a persistent terminal session for the daemon.

After the foreground check, stop that gateway before using the service. These service commands are for the Hermes host.

Install the gateway service

hermes gateway install

Start it

hermes gateway start

Check it

hermes gateway status

The gateway uses systemd on Linux, launchd on macOS, or a logon Scheduled Task on Windows. A Windows task does not supervise a later gateway crash. Check status if replies stop.

A sleeping or switched-off host cannot process requests or send replies. For hosting choices, see How to run Hermes Agent 24/7 on a VPS or home server.

If it doesn't answer

• Repeat the local daemon check. Confirm the daemon's account number matches SIGNAL_ACCOUNT and its address matches SIGNAL_HTTP_URL.
• Check the sender's full phone number, including + and country code, against the allowlist. Group messages are ignored until their group IDs are configured.
• Check signal-cli logs and the installed release's Java requirements if the connection drops. For duplicates, make sure only one signal-cli instance is listening on the account.
• Check that Hermes is using the intended profile. Saved credentials do not mean a gateway is running; an explicit disabled platform setting overrides credentials. See Hermes Agent bot not responding in your chat app.

Official docs

Reviewed Oct 29, 2026 against the official Hermes docs.

Official Hermes Signal docs↗ (opens in a new tab)

Related guides

• All messaging platforms
• Hermes Agent messaging gateway explained
• Hermes Agent bot not responding in your chat app
• How to run Hermes Agent 24/7 on a VPS or home server

Spotted something wrong or out of date? Tell us on X at @HermesWatcher↗ (opens in a new tab) and we will fix it.

New Hermes Agent updates every day on X. Follow @HermesWatcher