Troubleshooting¶

Fixes for the problems you are most likely to hit with the Hermes image.

SSH times out¶

The recommended security group allows SSH only from 127.0.0.1/32. Edit the rule so its source is your own IP address.
The instance needs a public IP address and a route to the internet.
After several failed logins, fail2ban bans your address for 1 hour. Wait, or unban it from another session:
```
sudo fail2ban-client set sshd unbanip <your-ip>
```

Connect as ubuntu, with the key pair you chose at launch. Password login is turned off.

The service is running but Hermes could not connect. The summary shows the last error; the full log is in /home/ubuntu/.hermes/logs/gateway.log.

Error in the log	Fix
`InvalidToken` or `rejected by the server`	The Telegram bot token is wrong. Copy it again from BotFather.
`Unknown provider`	`LLM_PROVIDER` is not one of `openai`, `anthropic`, `openrouter`, `gemini` or `groq`.
`provider auth failed`	The API key is wrong, revoked, or for another provider.
`does not exist`	The model ID is wrong for that provider. Use the provider's exact ID, with no prefix.
`no adapter` or `not installed`	The channel you configured is not installed in this image.

Fix the value and run the provisioning script again.

With DM_POLICY=allowlist, only CUSTOMER_TELEGRAM_ID and ADDITIONAL_USERS can talk to the bot. Check you used your numeric user ID, not your username.
Choose Start in the bot chat before you send a message.
Check your model provider account has credit and quota.

Use gpt-5, the tested default. Some older OpenAI models, such as gpt-4o, do not fully support the API Hermes uses.

Email info@softwaresushi.com with your instance ID, the image version and the redacted error. Do not include keys or tokens.