Hermes Agent SMS Integration: Twilio Text Message Gateway Setup Guide

This guide covers how to connect Hermes Agent to SMS using Twilio, turning any trusted phone number into a gateway for short requests, alerts, and fallback workflows. It is written for Hermes users who want to send commands or receive notifications via SMS without opening a terminal, and who need a secure, step-by-step rollout pattern.

What You Need

Before you begin, you must have the following:

• A Twilio account with an active phone number capable of sending and receiving SMS messages. If you do not have one, sign up at twilio.com and purchase a number with SMS capability. The official documentation assumes you already have this configured.
• Hermes Agent installed and running on a server or local machine. The gateway requires a running Hermes process to handle incoming SMS messages and route them to the correct profile and skills.
• The Hermes CLI available in your terminal. You will run hermes gateway setup and other commands to enable the SMS platform adapter.
• An active Hermes profile with credentials stored securely. The official documentation stresses that tokens or credentials must be stored in the active Hermes profile environment, never in source control or a shared note.
• A test phone number that is allowlisted before any production use. This can be your own mobile number.

If you prefer to skip self-hosting, the official documentation mentions a managed cloud option: "Deploy in 60 seconds" with API costs included and no gateway maintenance. That path is separate from this guide, which focuses on the self-hosted setup.

What SMS Is Good For (And What It Is Not)

SMS is a human-facing gateway, not a full automation system. According to the official documentation, SMS is best for short, urgent, low-context workflows where the message starts the request, but Hermes can still use files, terminal tools, MCP servers, web search, cron history, GitHub, Linear, Notion, and project-specific skills to do the real work.

Good Use Cases

• Operational alerts and status reports that should reach people without opening a terminal. For example, a cron job can send a daily summary of server health to your phone.
• Approval workflows where Hermes drafts the action but a human confirms it in chat. The documentation lists approvals as a common workflow: "let Hermes draft the action and ask for confirmation before sending, deploying, or editing anything sensitive."
• Incident triage: summarize the alert, inspect logs or dashboards, and post next actions back to chat.
• Project updates: ask Hermes what changed in GitHub, Linear, or Notion and receive a concise report.
• Knowledge capture: turn a chat thread into a task, document, issue, or reusable skill.
• Fallback commands when other channels (Slack, Discord, Telegram) are unavailable.

Limitations to Keep in Mind

The official documentation warns that SMS has weaker identity and formatting compared to chat apps. You should use stricter limits than you would with a platform like Slack or Discord. Specifically:

• Messages can be too long or poorly formatted. The documentation advises: "use concise prompts and route long reports to email, docs, or a file when the platform has tight message limits."
• Identity is weaker. SMS does not provide the same level of authentication as OAuth-based chat platforms. This is why allowlisting is critical.
• No rich formatting. You cannot send code blocks, images, or file attachments via SMS. Keep prompts and responses plain text.

Setup Path: Step-by-Step

The official documentation provides a six-step setup path. Each step is explained below with additional context.

Step 1: Create or Configure the SMS Bot/App/Account

You need a Twilio phone number that can send and receive SMS. If you already have one, ensure it is configured to handle incoming messages via a webhook URL. The Hermes gateway will expose an endpoint that Twilio will call when an SMS arrives.

In the Twilio console, go to Phone Numbers > Manage > Active Numbers, select your number, and under "Messaging", set the webhook URL to point to your Hermes gateway endpoint. The exact URL will depend on your gateway configuration and network setup. The official documentation does not specify the exact URL path, but typically it will be something like https://your-server:port/sms or a path defined by the gateway adapter.

Step 2: Store the Token or Credentials in the Active Hermes Profile

Do not hardcode credentials in configuration files or scripts. The official documentation states: "Store the token or credentials in the active Hermes profile, not in source control or a shared note."

To do this, use the Hermes profile environment. For example, you might set environment variables in your shell profile or use Hermes's built-in secret management. The exact command depends on your Hermes setup, but the principle is that the profile running the gateway must have access to the Twilio account SID, auth token, and phone number.

Step 3: Run hermes gateway setup and Enable the Platform Adapter

In your terminal, run:

hermes gateway setup

This command will guide you through enabling platform adapters. When prompted, enable the SMS/Twilio adapter. The official documentation says to "enable only the platform you are testing" during initial setup. This prevents accidental cross-platform interference.

Step 4: Restrict Allowed Users, Rooms, Groups, or Contacts Before the First Test

Before you send any message, configure the allowlist. The official documentation repeatedly emphasizes this: "Allowlisted users, rooms, groups, or contacts before broader rollout."

In the Hermes gateway configuration, specify which phone numbers are allowed to interact with the bot. Start with one private number (your own). The documentation says: "Allowlist one private user or test room before adding team-wide rooms."

Step 5: Restart the Gateway and Send One Harmless Private Test Message

After configuring the allowlist, restart the gateway to pick up the changes. Then send a harmless test message from your allowlisted phone number. The official documentation recommends: "Send a harmless prompt such as 'reply with the active profile and enabled platform name.'"

This smoke test confirms that:

• The gateway is running.
• The platform adapter is enabled.
• Your phone number is allowlisted.
• Hermes can receive and respond to SMS.

Step 6: Only After the Smoke Test, Connect Project Skills, Cron Reports, MCP Tools, or Team Rooms

Once the smoke test passes, you can gradually expand the bot's capabilities. The official documentation says: "Only after the smoke test, connect project skills, cron reports, MCP tools, or team rooms."

Add one feature at a time. For example, first enable a simple status check skill, then add a cron report, then add team-wide access. This incremental approach makes it easier to isolate issues.