# How to Build a Hermes Agent Signal Bot With End-to-End Encryption

Signal is the only major messaging platform where every message between you and your AI agent stays end-to-end encrypted by default. This guide walks through setting up Nous Research Hermes Agent on Signal using signal-cli, configuring group chats and voice notes, and solving the file persistence problem that most self-hosted agent setups ignore.

Source: https://fast.io/resources/hermes-agent-signal-bot-encrypted-messaging/
Last reviewed: 2026-05-17

## Why Signal for Your AI Agent

Most AI agent messaging guides point you toward Telegram or Discord. Both are solid platforms, but neither encrypts agent conversations end-to-end by default. Telegram only encrypts "secret chats" (not bot conversations), and Discord doesn't offer E2E encryption at all. If your agent handles anything sensitive, like financial data, medical questions, internal documents, or personal notes, that's a real gap.

Signal encrypts every message with the Signal Protocol, including messages to and from bots. When you connect [Hermes Agent](https://github.com/nousresearch/hermes-agent) to Signal, your prompts and the agent's responses travel through the same encryption that protects billions of private conversations. No server-side logs, no plaintext storage, no third-party access.

Nous Research Hermes Agent is an open-source (MIT-licensed) autonomous AI agent with persistent memory, installable skills, scheduled automations, and connections to over 20 messaging platforms. The Signal gateway supports text, group chats, voice note transcription, disappearing messages, and file attachments up to 100 MB. Your phone number stays private since the bot operates through its own linked account.

The tradeoff is setup complexity. Signal doesn't have a public bot API like Telegram's BotFather. You need signal-cli, a Java-based command-line client, to register a bot account and run a local HTTP daemon that Hermes connects to. It takes about 15 minutes if you follow the steps below, and the result is an agent conversation channel that no one else can read.

## Prerequisites: What You Need Before Starting

Before configuring anything, gather these requirements:

**System requirements:**

- Java 17 or later (signal-cli is a Java application)
- Python 3.10+ (for Hermes Agent)
- A server, VPS, or always-on machine to run the signal-cli daemon and Hermes

**Signal requirements:**

- A phone number for the bot (separate from your personal Signal account)
- Signal installed on your phone for the initial device linking step

**Optional but recommended:**

- [Whisper](https://github.com/openai/whisper) or a compatible speech-to-text model if you want voice note transcription
- An API key for your preferred LLM provider (Nous Portal, OpenRouter, OpenAI, or a local model endpoint)

A quick note on phone numbers: signal-cli links as a secondary device to an existing Signal account, similar to how Signal Desktop works. You can use a cheap prepaid SIM or a VoIP number that receives SMS. If your VoIP provider blocks Signal verification codes, try voice verification instead. Using your personal number is possible but not recommended, since the bot will share that account's message history and contacts.

### Install signal-cli

On macOS:

```bash
brew install signal-cli
```

On Linux, download the latest release from the [signal-cli GitHub repository](https://github.com/AsamK/signal-cli) and extract it:

```bash
curl -L -o signal-cli.tar.gz https://github.com/AsamK/signal-cli/releases/latest/download/signal-cli-0.13.11-Linux.tar.gz
tar xf signal-cli.tar.gz -C /opt
ln -sf /opt/signal-cli-0.13.11/bin/signal-cli /usr/local/bin/signal-cli
```

Verify the installation:

```bash
signal-cli --version
```

If Java isn't found, install it first. On Ubuntu: `sudo apt install openjdk-17-jre`. On macOS: `brew install openjdk@17`.

## Register the Bot and Link to Signal

With signal-cli installed, you have two paths for account setup. Device linking is faster and works well for testing. Dedicated registration gives you a clean bot-only account for production.

### Path A: Link as a Secondary Device (Recommended for Getting Started)

This approach links signal-cli to your bot's existing Signal account, the same way Signal Desktop connects to your phone.

Generate a linking URI:

```bash
signal-cli link -n "HermesAgent"
```

This prints a `tsdevice:/` URI. Convert it to a QR code using any tool (qrencode, an online generator, or your terminal if it supports inline images). Then open Signal on the phone with the bot's number, go to **Settings**, then **Linked Devices**, then **Link New Device**, and scan the QR code.

Once linked, verify the connection:

```bash
signal-cli -a +15551234567 receive
```

Replace `+15551234567` with your bot's phone number in E.164 format (country code, no dashes).

### Path B: Register a New Number

If you have a fresh SIM that hasn't been used with Signal before:

```bash
signal-cli -a +15551234567 register
```

Signal sends an SMS verification code. Enter it:

```bash
signal-cli -a +15551234567 verify 123-456
```

If SMS doesn't arrive, request a voice call instead:

```bash
signal-cli -a +15551234567 register --voice
```

Some registrations also require a CAPTCHA. If you see a captcha error, open the Signal registration page in a browser, complete the CAPTCHA, and copy the `signalcaptcha://` URI. Then re-run register with the token. Complete this quickly since captcha tokens expire within minutes.

### Start the signal-cli Daemon

The daemon exposes an HTTP API that Hermes Agent connects to:

```bash
signal-cli -a +15551234567 daemon --http 127.0.0.1:8080
```

Test that it's running:

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

A successful response means signal-cli is ready to send and receive messages. Keep this process running in the background (use `tmux`, `screen`, or a systemd service for production deployments).

## Configure Hermes Agent for Signal

With signal-cli running, install Hermes Agent and connect it to the daemon.

### Install Hermes Agent

```bash
pip install "hermes-agent[messaging]"
```

For the full package with voice support and all messaging platforms:

```bash
pip install "hermes-agent[all]"
```

### Set Environment Variables

Add these to your `~/.hermes/.env` file or export them in your shell:

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

`SIGNAL_ALLOWED_USERS` is a comma-separated list of phone numbers (E.164 format) that the bot will respond to. This is a security control. Without it, anyone who has your bot's number can interact with your agent. Set it to the phone numbers of people who should have access.

For group chat support, add:

```bash
SIGNAL_GROUP_ALLOWED_USERS=*
```

Setting this to `*` allows the bot to respond in all groups it's added to. For tighter control, list specific group IDs instead.

### Interactive Setup (Alternative)

Hermes also offers a guided setup wizard:

```bash
hermes gateway setup
```

Select **Signal** from the list of available platforms. The wizard prompts for the same values (daemon URL, account number, allowed users) and writes them to your config file.

### Verify the Connection Start the Hermes Agent messaging gateway:

```bash
hermes gateway start
```

Send a test message from your personal Signal account to the bot's number. You should see the agent process the message and respond. If nothing happens, check these common issues:

- **Daemon not running:** Confirm signal-cli daemon is active and the HTTP endpoint responds to `curl`
- **Wrong phone format:** All numbers must include the country code with a `+` prefix. `+15551234567` works, `5551234567` does not
- **Allowlist mismatch:** Your personal number must be in `SIGNAL_ALLOWED_USERS`
- **Java version:** signal-cli requires Java 17 or later. Older versions fail silently on some operations

## Advanced Features and Privacy Controls

Once basic messaging works, Signal's privacy features give your agent conversations capabilities that other platforms can't match.

### Voice Note Transcription

When someone sends a voice note to the bot, Hermes can transcribe it and process the text through the agent pipeline. This requires a speech-to-text backend. If you have Whisper configured, voice messages in MP3, OGG, WAV, or M4A format are automatically transcribed before reaching the agent. The bot responds with text by default, though you can configure TTS for spoken responses.

### Disappearing Messages

Signal's disappearing messages work with the Hermes gateway. If a conversation has a disappearing message timer set, both the user's messages and the agent's responses delete after the specified duration. This is useful for sensitive queries where you don't want conversation history lingering on either device. The agent's persistent memory still captures context from the conversation (unless you configure it not to), but the raw messages vanish from Signal.

### File Attachments

The gateway handles files in both directions. Users can send images (PNG, JPEG, GIF, WebP), audio files, and documents up to 100 MB. The agent can send files back as attachments. Formatting converts automatically: markdown in the agent's response renders as native Signal styling with bold, italic, strikethrough, and spoiler tags.

### Typing Indicators and Reactions

The bot displays typing indicators while processing a message, so the user knows the agent is working. Emoji reactions on messages also pass through to the agent as context.

### Single-Number Setup

If you don't want a separate phone number for the bot, Signal's "Note to Self" feature offers a workaround. Messages you send to yourself route through signal-cli with built-in echo-back protection. This is convenient for personal use but doesn't support group chats or multi-user access.

### Access Control

Beyond the basic allowlist, you can set `SIGNAL_ALLOW_ALL_USERS=true` to skip access control entirely. This is a security risk for most deployments, but makes sense for a public-facing assistant where anyone should be able to interact. Phone numbers are automatically redacted in logs (showing as `+155****4567`), which helps with privacy compliance.

## Persisting Agent Files With Fastio

Here's a problem that surfaces after your Signal bot runs for a while: Hermes Agent generates files during conversations. Research reports, code exports, data analysis results, skill artifacts. On a local machine, those files sit in the agent's working directory. If the server restarts, the disk fills up, or you migrate to a different host, they're gone. On a $5 VPS, disk space is measured in gigabytes, not terabytes.

The standard approach is to mount cloud storage. S3 works but requires IAM configuration and doesn't give you a browsable interface for reviewing what your agent produced. Google Drive and Dropbox work for personal use but don't handle agent-to-human handoff cleanly.

[Fastio](https://fast.io) is built for this pattern. It provides persistent workspaces where agents store files and humans retrieve them through a normal web interface. Fastio offers a 14-day Business Trial (card required; see [/pricing/](/pricing/)). Your agent writes files to Fastio through the [MCP server](/storage-for-agents/) or REST API, and you browse them from any device.

What makes this useful for a Hermes Signal deployment:

- **Persistent storage across sessions:** Files survive server restarts, redeployments, and host migrations
- **Built-in search:** [Intelligence Mode](https://fast.io/product/ai/) auto-indexes uploaded files for semantic search. Ask questions about your agent's output without downloading anything
- **Ownership transfer:** Your agent creates a workspace, builds content, then transfers ownership to you or a client. The agent retains admin access for future updates
- **MCP-native access:** Fastio exposes Streamable HTTP at `/mcp` and legacy SSE at `/sse`, so Hermes can use it as a tool directly through the [MCP skill](/storage-for-agents/)
- **Shareable links:** Send a branded share link through Signal. The recipient opens it in a browser, no account required for receiving

To connect Hermes to Fastio, start a 14-day Business Trial at [fast.io/pricing](https://fast.io/pricing/) and configure the MCP endpoint in your agent's tool list. Files your agent generates during Signal conversations persist in the workspace, searchable and shareable without touching the VPS filesystem.

## Frequently asked questions

### Is Hermes Agent on Signal encrypted?

Yes. Signal uses the Signal Protocol for end-to-end encryption on all messages, including those sent to and from bots. When Hermes Agent connects through signal-cli, every message between you and the agent is encrypted in transit and at rest. No server (including Signal's) can read the plaintext content of your conversations.

### Can Hermes Agent work in Signal group chats?

Yes. Group chat support requires setting the SIGNAL_GROUP_ALLOWED_USERS environment variable. Set it to * to allow the bot in all groups, or list specific group IDs for tighter control. The bot responds to messages in the group and maintains separate conversation context per group.

### How do I set up signal-cli for Hermes Agent?

Install signal-cli (brew install signal-cli on macOS, or download from GitHub for Linux). You need Java 17 or later. Link it to a Signal account by running signal-cli link, scanning the QR code in Signal's Linked Devices settings, then starting the HTTP daemon with signal-cli daemon --http 127.0.0.1:8080. Point Hermes at the daemon by setting SIGNAL_HTTP_URL in your environment.

### What is the most private way to use an AI agent?

Running an AI agent through Signal gives you end-to-end encrypted messaging, which most other platforms don't provide for bot conversations. For maximum privacy, pair Signal with a self-hosted LLM (like a local Llama model) so your prompts never leave your network. Hermes Agent supports local model endpoints alongside cloud providers like OpenRouter and OpenAI.

### Does the Signal bot need a separate phone number?

A separate number is recommended but not required. You can use Signal's Note to Self feature with your personal number, which routes messages through signal-cli without needing a second SIM. However, this limits you to single-user access and no group chat support. For production use, a prepaid SIM or VoIP number dedicated to the bot is the better approach.

### Can the Signal bot handle voice messages?

Yes. When a user sends a voice note, Hermes can transcribe the audio using Whisper or a compatible speech-to-text model and process the transcribed text through the agent pipeline. Supported audio formats include MP3, OGG, WAV, and M4A. The bot responds with text by default, though text-to-speech can be configured for spoken responses.

## About Fast.io

Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server at https://mcp.fast.io/mcp, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli.