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

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 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.

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 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:

brew install signal-cli

On Linux, download the latest release from the signal-cli GitHub repository and extract it:

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:

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.

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:

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:

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:

signal-cli -a +15551234567 register

Signal sends an SMS verification code. Enter it:

signal-cli -a +15551234567 verify 123-456

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

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:

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

Test that it's running:

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).

Persist your Hermes Agent files across sessions

Free 50 GB workspace for your Signal bot's output. MCP-ready endpoint, built-in search, shareable links. No credit card, no expiration.

Sign Up Free

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

Install Hermes Agent

pip install "hermes-agent[messaging]"

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

pip install "hermes-agent[all]"

Set Environment Variables

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

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:

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:

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:

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

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.

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.

Fast.io is built for this pattern. It provides persistent workspaces where agents store files and humans retrieve them through a normal web interface. The free tier includes 50 GB of storage, 5,000 AI credits per month, and 5 workspaces with no credit card required. Your agent writes files to Fast.io through the MCP server 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 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: Fast.io exposes Streamable HTTP at /mcp and legacy SSE at /sse, so Hermes can use it as a tool directly through the MCP skill
• 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 Fast.io, create a free account at 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.