Deploying Hermes to VPS with Dual Telegram Bots: A Battle-Tested Guide to Stable Production Setup

Introduction: The Real Challenge Isn’t Installation — It’s Keeping Everything Running

This guide answers one core question: How do you deploy Hermes reliably on a VPS and run two Telegram Bots simultaneously without them stepping on each other?

Many people assume that seeing hermes --version produce output means the job is done. It doesn’t. The real difficulty was never getting Hermes installed. It lies in making it run stably over time, wiring Telegram into the system properly, letting systemd manage the process lifecycle, and ensuring two Bots coexist without conflicts. This article distills hard-won lessons from a complete production deployment into a clear, repeatable path you can follow.

Server deployment concept
Image source: Unsplash

Part 1: Foundation — From Installation to Service Activation

Why VPS Is Non-Negotiable for Production Use

Core question: What are the limitations of running Hermes locally, and how does a VPS solve them?

Running Hermes from the command line on your local machine works fine for quick experiments. But the moment your goals shift to any of the following, a VPS becomes mandatory:

  • Hermes needs to stay online 24/7.
  • Your Telegram Bot must respond to calls at any time.
  • You plan to expand to multiple Bots down the road.
  • Services must recover automatically after a server reboot.

Local machines fail on all counts: shutting down your computer stops Hermes, losing your network connection stops Hermes, and there is no mechanism for automatic recovery. Deploying to a VPS is fundamentally not about solving an installation problem — it is about solving an environment stability problem.

Installing Hermes: Avoiding the Most Common Misdiagnosis

Core question: How do you install Hermes correctly and avoid mistaking “installed” for “running as a service”?

The official installation script handles the job. Run it, then verify with:

hermes --version

If you see version output, the CLI tool itself is installed successfully.

Critical distinction: A working hermes --version proves only that the binary exists and executes. It does not mean your Telegram Bot is online. This is the single most common misdiagnosis. People see the version string, assume everything is working, and then spend hours debugging why the Bot never responds.

Two Environment Pitfalls Before You Proceed

Core question: What environment issues should you fix before attempting to configure Hermes?

Pitfall 1: Do Not Use a Web-Based SSH Terminal

Most VPS control panels offer a browser-based SSH terminal. Do not use it for real deployment. It introduces problems that degrade your ability to troubleshoot:

  • Connections drop frequently, breaking your session context.
  • Long command pastes may fail silently.
  • Output and input become interleaved and hard to read.
  • Typos go unnoticed.

Solution: Use a dedicated local SSH client such as FinalShell or Termius. A stable terminal session is the foundation everything else depends on.

Pitfall 2: Broken System Package Sources (APT Mirror 404 Errors)

During setup, you may encounter errors like:

E: Failed to fetch ... 404 Not Found
E: Unable to fetch some archives

This is not a Hermes problem. The system’s package repository — used to install dependencies — is unreachable or outdated.

Solution: Replace the mirror with the official Ubuntu repository:

sudo sed -i 's|http://old-mirror-url|http://archive.ubuntu.com/ubuntu|g' /etc/apt/sources.list
sudo apt update && sudo apt upgrade -y
sudo apt install -y ripgrep ffmpeg

Key logic: If apt update itself fails, many downstream Hermes issues are merely symptoms. Fix the system dependency chain first, then address Hermes.

Part 2: From “It Works” to “It’s Stable” — Service Management and Verification

The Critical Leap: Installing the Hermes Gateway as a Systemd Service

Core question: How do you make Hermes run persistently in the background with automatic restart and boot recovery?

Hermes deployment operates at three distinct levels:

  1. CLI is functional — you can run hermes commands.
  2. Gateway can execute — the gateway process starts.
  3. Service is managed — systemd controls the gateway’s lifecycle.

True production stability lives at level three. You must install the gateway as a systemd service.

Two errors commonly appear during this step:

  1. System gateway install requires root. Re-run with sudo. — You need root privileges.
  2. sudo: hermes: command not found — The sudo environment cannot locate the hermes binary.

The second error occurs because Hermes installs to the current user’s local directory (e.g., /home/ubuntu/.local/bin/hermes), which is not in sudo‘s default PATH.

Correct procedure:

# Use the absolute path to run the installation
sudo /home/ubuntu/.local/bin/hermes gateway install --system

# Enable the service for automatic start on boot
sudo systemctl enable hermes-gateway

# Start the service now
sudo systemctl start hermes-gateway

# Verify the service status
sudo systemctl status hermes-gateway

Success criterion: The output of systemctl status must contain Active: active (running). Without that line, the service is not truly online.

Diagnosing a Silent Bot: The Right Order of Checks

Core question: When a Telegram Bot stops responding, what is the systematic way to diagnose the problem?

Do not jump straight to blaming the Token. Follow this priority order:

  1. The user has not clicked “Start”: In Telegram, the Bot will not respond until the user sends /start or presses the Start button in the private chat. This is a Telegram platform requirement, not a Hermes issue.

  2. Allowed User ID mismatch: If Hermes is configured with an Allowed User ID restriction, messages from any other user ID will be silently ignored.

  3. Gateway service is not running: This is the most frequent technical cause. Check with:

    sudo systemctl status hermes-gateway
journalctl -u hermes-gateway -f   # View live logs

  4. Token format error: Telegram Bot Tokens follow a standard format like 123456789:AAxxxxxxxxxxxxxxxxxxxxxxxx. Malformed tokens cause authentication failures.

Lesson learned: The order of diagnosis matters enormously. Checking the service first, then logs, then configuration values saves significant time. Reversing this order leads to hours wasted on irrelevant rabbit holes.

Part 3: The Advanced Challenge — Running Two Bots Side by Side

Why Simple Directory Isolation Fails for Dual Bots

Core question: Why can’t you just create two Hermes directories under the same user to run two Bots?

A tempting shortcut is to create two separate configuration directories under a single system user (e.g., ~/.hermes and ~/hermes-trader), each with its own config. This immediately fails with the error:

Gateway already running

The message is unambiguous: the conflict occurs at the process level, not the file level. Both Bots attempt to claim the same system resources (ports, process locks, socket files). Isolating directories does nothing to isolate running instances.

The Stable Solution: User-Level Isolation

Core question: What is the most reliable architecture for running two Bots simultaneously?

The answer, validated through real deployment, is user-level isolation — creating a dedicated system user for each Bot, with independent Hermes installations and configurations.

Architecture example:

Aspect Bot 1 (Main Assistant) Bot 2 (Trading Assistant)
System user ubuntu trader
Service name hermes-gateway hermes-trader-gateway
Purpose Tech deployment, content assistance Market analysis, trading signals
Hermes install /home/ubuntu/.local/bin/hermes /home/trader/.local/bin/hermes
Config directory /home/ubuntu/.hermes /home/trader/.hermes

Steps to set up the second Bot:

# 1. Create a new system user
sudo adduser trader
sudo usermod -aG sudo trader   # Optional: grant sudo access

# 2. Switch to the new user
sudo -iu trader

# 3. Install Hermes independently in this user's environment
curl -fsSL <official-install-script-url> | bash
source ~/.bashrc
which hermes          # Verify installation path
hermes --version

# 4. Configure the second Bot with its own Token, User ID, etc.
hermes setup

Creating a Separate Systemd Service for the Second Bot

Core question: How do you make the second Bot start automatically and run persistently in the background?

The second Bot requires its own systemd service unit file. Never reuse the first Bot’s service definition.

Step 1 — Create the service file:

sudo nano /etc/systemd/system/hermes-trader-gateway.service

Step 2 — Define the service (note that User, WorkingDirectory, and ExecStart all point to the trader user):

[Unit]
Description=Hermes Trader Gateway
After=network.target

[Service]
Type=simple
User=trader
WorkingDirectory=/home/trader
ExecStart=/home/trader/.local/bin/hermes gateway run --replace
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Step 3 — Load and start the service:

sudo systemctl daemon-reload
sudo systemctl enable hermes-trader-gateway
sudo systemctl start hermes-trader-gateway
sudo systemctl status hermes-trader-gateway

Success criterion: Again, confirm Active: active (running) in the status output. Both Bots are now independently managed by systemd and will survive reboots.

Part 4: Summary, Checklists, and Troubleshooting

The Six-Step Deployment Sequence

For a first-time deployment, follow this exact order to avoid rework:

Step Action Command / Detail
1 Connect via stable SSH Use a local SSH client (FinalShell, Termius), not a web terminal
2 Install Hermes Run the official install script; verify with hermes --version
3 Fix system dependencies sudo apt update; if 404 errors appear, update /etc/apt/sources.list; install ripgrep and ffmpeg
4 Configure Hermes Run hermes setup for the first Bot
5 Install Gateway as a systemd service Use the absolute path: sudo /home/ubuntu/.local/bin/hermes gateway install --system; then enable, start, and status
6 Final validation Close SSH — does the Bot still reply? Reboot VPS — does the service auto-recover?

Deployment Validation Checklist

Category Check Pass Criteria
Single Bot hermes --version Returns version number
which hermes Returns a valid path
sudo apt update No 404 errors
systemctl status hermes-gateway Shows active (running)
Telegram interaction Start button has been pressed
Configuration Allowed User ID and Token format are correct
Persistence test Bot responds after SSH disconnect and after VPS reboot
Dual Bot (additional) User isolation Second Bot uses a dedicated system user
Independent installation Hermes is installed separately under the second user
Independent config Second Bot has its own Telegram Token, User ID, and channel permissions
Independent service Second Bot has its own systemd service file
Parallel operation Both services show active (running) and both Bots respond simultaneously

Five Most Common Dual-Bot Problems

Problem Root Cause Solution
Gateway already running Two gateways running under the same system user Implement user-level isolation
hermes: command not found under second user Hermes was only installed for the first user Switch to the second user and reinstall Hermes
Second Bot service fails to start Incorrect User, WorkingDirectory, or ExecStart in the service file Verify all three fields point to the second user’s paths
Both Bots online but responses are jumbled Bots share configuration (same Token or User ID) Run hermes setup separately under each user
Only one Bot survives a reboot Second service not enabled, or daemon-reload was skipped Run systemctl daemon-reload, then enable and start the second service

Reflections: From Commands to Architecture

The deepest takeaway from this deployment is that the hard part of Hermes is rarely any single command — it is the overall system design. Most errors that look like “command failures” trace back to environment conflicts, misaligned configurations, or missing service definitions.

A compact way to frame it:

  • Single Bot is about installation.
  • Dual Bots are about isolation.
  • Production readiness is about systemd.

Understanding and applying user-level isolation and systemd service management is the bridge from experimentation to a dependable production setup.

Frequently Asked Questions (FAQ)

Q1: Running hermes gateway install --system says I need sudo, but using sudo says the command is not found. What do I do?

Hermes installs into the user’s local directory, which is not in sudo‘s default search path. Use the absolute path to the binary:

sudo /home/your-username/.local/bin/hermes gateway install --system

Q2: Dual Bot deployment throws “Gateway already running.” How do I fix it?

Both Bots are competing for resources under the same system user. Create a separate system user for the second Bot, install Hermes independently in that user’s environment, and configure a dedicated systemd service.

Q3: The second user cannot find the hermes command. Why?

Hermes is installed per-user, not globally. After switching to the second user, you must run the installation script again to set up a separate copy of Hermes.

Q4: Both Bots appear online but their responses are mixed up or go to the wrong chat. What went wrong?

The two Bots likely share overlapping configuration. Ensure each user runs hermes setup independently, with distinct Telegram Tokens, Allowed User IDs, and channel permissions.

Q5: After a VPS reboot, only one Bot starts automatically. How do I fix this?

Check whether the second service is enabled: sudo systemctl is-enabled hermes-service-name. If not, run sudo systemctl enable hermes-service-name. Also confirm you ran sudo systemctl daemon-reload after creating or modifying the service file.

Q6: How can I view real-time logs for debugging?

Use journalctl with the -f flag to follow live output:

journalctl -u hermes-gateway -f

Replace hermes-gateway with the appropriate service name for the second Bot.

Q7: Why is the web-based SSH terminal discouraged for deployment?

Web terminals suffer from unstable connections, failed command pastes, interleaved input/output, and hard-to-spot typos. A local SSH client provides a persistent, reliable session — a prerequisite for efficient deployment and troubleshooting.

Q8: What is the minimum set of system dependencies Hermes needs on a fresh VPS?

Based on the deployment described, you need ripgrep and ffmpeg installed via apt. Ensure sudo apt update runs cleanly before installing them; if it fails with 404 errors, fix the package source first.