# Implement: Connect an Existing Hermes Agent to Telegram Securely

Inspect the target environment, configure the integration, verify it, and report the result. If you have terminal tools, perform the safe, inspectable steps yourself and pause only when the user must enter a secret or complete an action in Telegram. If you cannot use tools, return the same workflow as an exact human-run procedure with commands and expected results. Inspect before changing anything, preserve unrelated configuration, and ask only for required information you cannot derive. Never ask the user to paste a bot token into this conversation.

## Outcome

Connect an existing Hermes installation on a Linux VPS to a Telegram bot through Hermes's built-in messaging gateway. Run the gateway as a systemd user service owned by the non-root `hermes` account, keep it active after SSH logout with systemd lingering, and restrict access to the intended numeric Telegram user ID.

The finished integration must let the allowlisted user send a direct message to the bot and receive a Hermes response. It must survive logout without running Hermes as root, exposing a new inbound server port, enabling access for every Telegram user, or placing the Telegram bot token in chat, command history, source control, logs, or the completion report.

## Preconditions and inputs

Inspect or confirm these prerequisites before making changes:

- A Linux VPS with systemd and SSH access.
- An existing, working Hermes CLI installation owned by the non-root `hermes` user.
- A configured model provider that already works from the Hermes CLI.
- Permission to run `sudo loginctl enable-linger hermes`.
- No intentionally active system-level Hermes gateway service.
- The Hermes profile being configured. Use the default profile unless the user identifies a named profile.

The user must supply or create:

- `<TELEGRAM_BOT_TOKEN>` through Telegram's official `@BotFather`. Treat it as a secret and have the user enter it directly into the interactive Hermes wizard.
- `<TELEGRAM_USER_ID>`, the stable numeric Telegram account ID that should be allowed to reach Hermes. This value is an identity selector, not the bot username.
- `<HERMES_HOME>` only if a non-default Hermes home or named profile is in use. The default is `~/.hermes` for the `hermes` account.

If Hermes is missing, its existing CLI cannot complete a basic model request, or the machine is not using systemd, stop and report the unmet prerequisite. Do not expand this task into installing Hermes or changing the operating system.

## Safety constraints

- Run Hermes and its gateway as `hermes`, never as root. Use elevated privileges only for the specific lingering command.
- Keep the gateway fail-closed. Configure the exact `<TELEGRAM_USER_ID>`; never set `GATEWAY_ALLOW_ALL_USERS=true` or add unknown IDs.
- Do not request, display, echo, log, validate through a URL, or store `<TELEGRAM_BOT_TOKEN>` in the conversation. Pause while the user types it directly into `hermes gateway setup`.
- Do not commit Hermes configuration, `.env` files, gateway state, tokens, or copied terminal output containing secrets.
- Keep secret files readable only by their owner. If the wizard uses `<HERMES_HOME>/.env`, enforce mode `600` without printing its contents.
- Use the article's user-service approach for this implementation. Current Hermes also offers a system-level service for headless servers, but do not install it during this workflow and never keep both user and system gateway services active simultaneously.
- Treat Telegram bot conversations as cloud-mediated rather than end-to-end encrypted. Do not send server credentials or other sensitive values to the bot during testing.

## Implementation

1. Connect to the VPS and inspect the current identity, Hermes installation, profile location, and service state. Non-zero service status is acceptable when the gateway has not been installed yet; record it rather than trying unrelated fixes.

   ```bash
   whoami
   command -v hermes
   hermes --version
   printf '%s\n' "${HERMES_HOME:-$HOME/.hermes}"
   hermes gateway status
   systemctl --user status hermes-gateway --no-pager
   systemctl status hermes-gateway --no-pager
   ```

   Continue only as the `hermes` user. If `systemctl status hermes-gateway` shows an active system service, stop and ask which service model should remain; do not create a competing user service.

2. Ask the user to open the verified `@BotFather` account in Telegram, send `/newbot`, choose the bot name and username, and retain the issued `<TELEGRAM_BOT_TOKEN>` privately. Do not ask them to return the token to you. Confirm only that the token and `<TELEGRAM_USER_ID>` are ready.

3. Start the official Hermes gateway wizard in the `hermes` user's interactive terminal:

   ```bash
   hermes gateway setup
   ```

   Select Telegram. When the wizard requests the token, pause and tell the user to enter `<TELEGRAM_BOT_TOKEN>` directly in that terminal. Configure `<TELEGRAM_USER_ID>` as the only allowed Telegram user. Decline any allow-all option. Preserve unrelated gateway platforms already configured by the user.

4. Restrict the legacy environment file if the wizard created or updated it. Do not fail merely because a newer Hermes version stores gateway configuration elsewhere.

   ```bash
   HERMES_ENV="${HERMES_HOME:-$HOME/.hermes}/.env"
   if [ -f "$HERMES_ENV" ]; then chmod 600 "$HERMES_ENV"; fi
   ```

5. Install and start the supported systemd user service, then enable lingering so it remains active after the SSH session ends:

   ```bash
   hermes gateway install
   sudo loginctl enable-linger hermes
   hermes gateway start
   ```

   Do not add `--system`. Do not create a custom systemd unit when Hermes's generated unit installs successfully.

6. Inspect status and logs without revealing configuration values:

   ```bash
   hermes gateway status
   systemctl --user is-enabled hermes-gateway
   systemctl --user is-active hermes-gateway
   journalctl --user -u hermes-gateway -n 50 --no-pager
   ```

   Address only errors related to Telegram configuration or the generated gateway service. Do not paste complete logs into chat if they contain credentials; redact sensitive values first.

## Verification

Confirm every pass criterion:

1. `whoami` reports `hermes` for non-privileged gateway commands.
2. `systemctl --user is-enabled hermes-gateway` reports `enabled`, and `systemctl --user is-active hermes-gateway` reports `active`.
3. `loginctl show-user hermes -p Linger` reports `Linger=yes`.
4. The logs show Telegram connecting without authentication, polling, or repeated restart errors and do not print the bot token.
5. The user opens the new bot in Telegram, sends `/start` or a normal message from the allowlisted account, and receives a Hermes response.
6. The user sends `/whoami` and confirms the expected identity and access scope.
7. Configuration does not contain `GATEWAY_ALLOW_ALL_USERS=true`, and no system-level Hermes gateway is active alongside the user service.

If any check fails, report the failed command, sanitized error, and safest next diagnostic. Do not claim the integration is complete until the allowed Telegram message succeeds.

## Completion report

Return a concise report containing:

- Changes made: profile configured, user service installed, lingering state, and secret-file permissions changed without secret values.
- Verification performed: each command or Telegram action and its pass/fail result.
- User actions still required: only actions that could not be completed with available tools, such as entering the token or sending the first Telegram message.
- Unresolved risks or blockers: sanitized errors, conflicting services, missing prerequisites, or none.
- Security confirmation: state that allow-all remains disabled and no credential was included in the response.

### Sources

- Source article: [Controlling Hermes via Telegram: Remote Setup & Security](https://vgagaleski.com/blogs/controlling-hermes-through-telegram/)
- Official reference: [Hermes Agent Messaging Gateway](https://github.com/NousResearch/hermes-agent/blob/main/website/docs/user-guide/messaging/index.md)
- Official reference: [Telegram Bots: An introduction for developers](https://core.telegram.org/bots)