# How to set up Hermes Agent on Signal

> Link Signal through signal-cli, restrict access, start both processes and send a first message, with notes on media and keeping the host online.

Canonical: https://hermeswatcher.com/learn/hermes-agent-signal-setup  
Section: Learn · Messaging & the gateway  
Last reviewed: Oct 29, 2026  
Basis: Explained from the official Hermes Agent docs and repository (Nous Research). Steps follow the linked official sources.

## 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](https://hermeswatcher.com/learn/messaging-gateway-explained.md).

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](https://github.com/AsamK/signal-cli#installation) 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](https://hermeswatcher.com/learn/run-hermes-agent-24-7.md).

## 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](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md).

## Official docs

Reviewed Oct 29, 2026 against the official Hermes docs.

[Official Hermes Signal docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/signal)

## Related guides

- [All messaging platforms](https://hermeswatcher.com/messaging.md)
- [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md)
- [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md)
- [How to run Hermes Agent 24/7 on a VPS or home server](https://hermeswatcher.com/learn/run-hermes-agent-24-7.md)

## Related tools

- [Signal: a private, end-to-end encrypted channel to your agent](https://hermeswatcher.com/tools/signal.md)
- [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md)
- [Command approvals: decide what the agent may run unattended](https://hermeswatcher.com/tools/approvals-security.md)

## Sources

- [Signal setup](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/signal)
- [Signal setup source snapshot](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/website/docs/user-guide/messaging/signal.md)
- [Messaging gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging)
- [Gateway access policy source](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/gateway/authz_mixin.py#L730-L773)
- [signal-cli installation requirements](https://github.com/AsamK/signal-cli/blob/master/README.md#installation)
- [plugins/platforms/signal/setup.py](https://raw.githubusercontent.com/NousResearch/hermes-agent/main/plugins/platforms/signal/setup.py)

---

HermesWatcher is an independent guide. It is not affiliated with or endorsed by Nous Research. The [official Hermes Agent documentation](https://hermes-agent.nousresearch.com/docs) and [repository](https://github.com/NousResearch/hermes-agent) from Nous Research are the authority; each page here lists the official sources it was written from. If this site and the official docs disagree, trust the official docs. Index for agents: https://hermeswatcher.com/llms.txt