Skip to content

Getting started

This page takes you from subscribing to chatting with your agent in Telegram. It takes about fifteen minutes. You launch the image, connect over SSH and run one provisioning script.

You need:

  • An AWS account that can subscribe to AWS Marketplace products and launch EC2 instances.
  • An EC2 key pair.
  • An API key from a supported provider: openai, anthropic, openrouter, gemini or groq, and the exact model ID that provider expects.
  • A Telegram bot token from BotFather.
  • Your numeric Telegram user ID.
  • A subnet with outbound HTTPS access, and a public IP address if you connect over SSH from the internet.

1. Subscribe and launch

  1. Open the Hermes AI Agent listing and choose View purchase options, then Subscribe.
  2. When the subscription is confirmed, choose Launch your software.
  3. Keep the recommended t3.medium instance type.
  4. Under Key pair, choose an existing key pair or create one.
  5. Under Network settings, edit the SSH rule (TCP 22) so its source is your own IP address, for example 203.0.113.10/32.
  6. Choose Launch instance.

Change the SSH rule before you launch

The recommended security group allows SSH only from 127.0.0.1/32, which means nowhere. Unless you change it to your own address, you cannot connect.

Encrypted disk

If the root volume must be encrypted, turn on EBS encryption by default in the EC2 settings for the Region before you launch.

2. Connect over SSH

When the instance shows Running, copy its Public IPv4 address and connect as ubuntu:

ssh -i <your-key.pem> ubuntu@<public-ip>

3. Provision your agent

Become root, then enter your secrets at prompts, so they never land in your shell history. This example uses OpenAI:

sudo -i
read -rsp "Model provider API key: " LLM_API_KEY; echo
read -rsp "Telegram bot token: " BOT_TOKEN; echo
read -rp "Telegram user ID: " CUSTOMER_TELEGRAM_ID
export LLM_API_KEY BOT_TOKEN CUSTOMER_TELEGRAM_ID
export LLM_PROVIDER=openai
export LLM_MODEL=gpt-5
bash /opt/hermes/bin/provision-hermes.sh
unset LLM_API_KEY BOT_TOKEN CUSTOMER_TELEGRAM_ID
exit

For Anthropic, use LLM_PROVIDER=anthropic and LLM_MODEL=claude-sonnet-5. For other providers, set the provider name and the model ID together. See Configuration for every setting.

The script writes your settings, starts the hermes-gateway service and waits up to about 45 seconds for Telegram to connect. It ends with a summary: look for is LIVE on Telegram!

4. Say hello

Open your bot in Telegram, choose Start and send a message.

Hermes may suggest /sethome in its first reply. Run it once if you want this chat to receive job results and messages from other platforms. Ordinary replies work without it.

5. Verify

hermes --version
sudo systemctl status hermes-gateway --no-pager
sudo tail -n 80 /home/ubuntu/.hermes/logs/gateway.log

The service can be active before Telegram has connected. Check that the gateway log reports a Telegram connection, and no invalid token, unknown provider or missing model. If it does, see Troubleshooting.