# How to install Hermes AI Agent on a Linux VPS

**URL:** <https://forum.boxtoplay.com/t/how-to-install-hermes-ai-agent-on-a-linux-vps/31781>\
**Category:** VPS\
**Tags:** english, vps\
**Created:** [Juin 10, 2026, 3:51 UTC](https://forum.boxtoplay.com/t/how-to-install-hermes-ai-agent-on-a-linux-vps/31781 "2026-06-10T15:51:46Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![BoxToPlay-helper](https://forum.boxtoplay.com/user_avatar/forum.boxtoplay.com/boxtoplay-helper/32/5468_2.png) [@BoxToPlay-helper](https://forum.boxtoplay.com/u/BoxToPlay-helper)\
**Post date:** [Juin 10, 2026, 3:51 UTC](https://forum.boxtoplay.com/t/how-to-install-hermes-ai-agent-on-a-linux-vps/31781/1 "2026-06-10T15:51:46Z")

</div>

![How to install Hermes AI Agent on a Linux VPS](https://forum.boxtoplay.com/uploads/default/original/2X/7/790e46f5c17447aa8b4a2f640f861839551e30c5.jpeg)

### Complete guide: install Hermes AI Agent on a Linux VPS

This guide walks you step by step through installing and configuring the **Hermes AI Agent** on a **Linux VPS server**. The goal is to get a fully autonomous agent that runs 24/7 on your VPS, executes commands, automates tasks, and responds through the terminal, Telegram, Discord, and other channels.

[Hermes Agent](https://github.com/NousResearch/hermes-agent) is an open-source self-improving AI agent created by Nous Research. It can plan actions, run code, call tools (web, shell, etc.), and build up memory over time. Once it lives on a VPS, it becomes a background assistant for your projects. If you are interested in similar autonomous assistants, you can also check out our guide to [install OpenClaw on a Linux VPS](https://www.boxtoplay.com/en/news/install-openclaw-on-a-linux-vps-practical-guide-and-first-steps-31756).

* * *

### 1. Requirements on your Linux VPS

Before you start, make sure you have:

- A **Linux VPS server** (Ubuntu 22.04 or 24.04 recommended, Debian 12 or similar also works)
- **SSH access** with a user that has sudo rights
- At least **1 to 2 GB of RAM** if you use cloud model APIs
- An **API key** for your model provider (OpenAI, Anthropic, OpenRouter, etc.), or a local model server such as Ollama if you prefer local models

Update the system and install basic tools.

Ubuntu / Debian:

```bash
sudo apt update && sudo apt upgrade -y
sudo apt install -y curl git

```

AlmaLinux / Rocky Linux:

```bash
sudo dnf update -y
sudo dnf install -y curl git

```

* * *

### 2. Install Hermes Agent with the official script

Hermes provides an all-in-one installer for Linux that handles Python, Node.js, and dependencies.

On your VPS, run:

```bash
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

```

Reload your shell so the **hermes** command is available:

```bash
source ~/.bashrc

```

Check the installation:

```bash
hermes --version

```

Example output:

```plaintext
Hermes Agent v0.16.0 (2026.6.5)
Project: /usr/local/lib/hermes-agent
Python: 3.11.15
OpenAI SDK: 2.24.0
Up to date

```

If the command is not found, make sure `~/.local/bin` is on your PATH or reconnect your SSH session.

* * *

### 3. Initial Hermes setup with the interactive wizard

Hermes ships with a full setup wizard.

Start it with:

```bash
hermes setup

```

The wizard will guide you through the setup (or you can use the “Quick Setup via Nous Portal” option):

- Pick a **model provider** (OpenAI, Anthropic, OpenRouter, Ollama, and others)
- Enter your **API key** if you use a cloud provider
- Choose the **default model** (featuring fuzzy-search on the model picker)
- Confirm where to store memory, skills, and logs (by default `~/.hermes`)

You can change this later with:

```bash
hermes model

```

* * *

### 4. Enable the Docker backend for safe execution

Hermes can run shell commands and code. On a VPS it is strongly recommended to execute these inside a **Docker sandbox** instead of directly on the host.

Install Docker depending on your distribution. For more details or other configurations, read our full guide to [install Docker on Linux](https://www.boxtoplay.com/en/news/install-docker-on-linux-a-practical-getting-started-guide-31747).

Ubuntu / Debian:

```bash
sudo apt-get remove -y docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo systemctl enable --now docker
sudo usermod -aG docker $USER

```

AlmaLinux / Rocky Linux:

```bash
sudo dnf install -y dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
sudo systemctl enable --now docker
sudo usermod -aG docker $USER

```

Reconnect to your session (or use `newgrp docker`) so your user can run Docker without sudo.

Tell Hermes to use Docker as its terminal backend:

```bash
hermes config set terminal.backend docker

```

Example output:

```plaintext
✓ Set terminal.backend = docker in ~/.hermes/config.yaml

```

You can switch back to local later with:

```bash
hermes config set terminal.backend local

```

* * *

### 5. Administrate and interact with your agent (Desktop, Dashboard, or Terminal)

To manage, configure, and chat with your Hermes agent on your VPS, the recommended method is to use the **Hermes Desktop** app. It serves as your primary graphical control center. Browser-based alternatives or direct command-line tools remain available to fit any workflow.

#### Option A (Recommended): The native Hermes Desktop App

The native **Hermes Desktop** application installs on your personal computer (Windows, macOS, Linux) and connects remotely to the Hermes daemon running on your VPS. It provides a polished native interface with chat streaming, session history, file drag-and-drop, and a model picker.

 ![Hermes Desktop Application Interface](https://forum.boxtoplay.com/uploads/default/original/2X/9/9e1c4ecd33aeb3fbfb93810ea66f048397b8954e.jpeg)

##### How to connect Hermes Desktop to your VPS:

1. On the VPS, define a persistent session token in `~/.hermes/.env`:  
`HERMES_DASHBOARD_SESSION_TOKEN=your_secure_token`
2. Start the daemon on the VPS, enabling WebSockets (via the `--tui` flag) to allow the Desktop app to connect:

```bash
hermes --tui dashboard --host 0.0.0.0 --port 9119 --no-open --insecure

```

3. In the Desktop App installed on your local computer, go to the **Gateway** tab on the left sidebar, select **Remote gateway** , enter `http://<YOUR_VPS_IP>:9119` in the **Remote URL** field, and click **Save and reconnect**.

 ![Configuring the Remote Gateway in the Hermes Desktop App](https://forum.boxtoplay.com/uploads/default/original/2X/f/fe1bdac62054984f4c0c5a5880d9170b54bf5bc0.png)

##### Choosing the Execution Backend:

From this graphical interface, you can configure where Hermes runs its terminal tasks by navigating to **Settings \> Terminal \> Execution Backend**. In addition to **Docker** (the recommended choice, which runs terminal commands isolated in a container on the VPS, as configured in Step 4), you can choose **Local** (to run directly on the VPS host system without isolation), **Ssh** (to delegate execution to another remote machine), **Modal** / **Daytona** (cloud serverless), or **Singularity** (HPC computing).

 ![Execution Backend settings in Hermes Agent](https://forum.boxtoplay.com/uploads/default/original/2X/b/b769b047c612b2feda97cfc8da4a745f70875d2f.png)

#### Option B: The Web Dashboard

If you prefer not to install the desktop app, Hermes includes a browser-based dashboard. It integrates your MCP catalog, messaging channels, credentials, webhooks, memory, and secure authentication.

To start the web dashboard on the VPS:

```bash
hermes dashboard --host 0.0.0.0

```

By default, it listens on port `9119`. You can access it in your browser at `http://<YOUR_VPS_IP>:9119` (make sure to open port `9119` in your firewall if you wish to use this interface).

 ![Hermes Web UI Chat Dashboard](https://forum.boxtoplay.com/uploads/default/original/2X/1/1ab35f2b18cb7567fb93ffa673a7a2196040b154.jpeg)

#### Option C: Classical Command Line (TUI & CLI)

For developers and system administrators who prefer working directly inside the SSH terminal:

- **Interactive Text Interface (TUI)**: Run the `hermes` command to enter a real-time chat interface. For instance, enter `what can you do as a hermes agent on this server?`. Hermes will plan its answer, call tools, and store the history under `~/.hermes`. Exit the TUI with `Ctrl+D` or `/quit` (you can also revert N turns in your history using the `/undo` command).
- **One-Shot Mode (Quick Command)**: To send a single command and print only the final text output directly to stdout:

```bash
hermes -z "Create a python script that fetches the weather in Paris"

```

* * *

### 6. Configure messaging gateways (Telegram, Discord, etc.)

One of the biggest advantages of running Hermes on a VPS is being able to interact with it **from your phone or chat rooms**.

You have two ways to configure these gateways:

#### Via the Graphical Interface (Dashboard / Desktop App):

Navigate to the **Messaging** tab in the left sidebar of the graphical interface. You will find all supported channels there (Telegram, Discord, Slack, WhatsApp, Signal, Twilio SMS, etc.).  
For example, for **Telegram** :

1. Follow the on-screen instructions to get a Bot Token from `@BotFather` on Telegram.
2. Enter your Bot Token and optionally your authorized user IDs in the **Allowed Telegram user IDs** field (highly recommended to prevent unauthorized access to your agent).
3. Toggle the switch at the bottom to **Enabled** and click **Save changes**.

 ![Configuring the Telegram messaging gateway in Hermes Agent GUI](https://forum.boxtoplay.com/uploads/default/original/2X/f/f52958caaba5d8fe899c302c1ad44c55eed88d10.png)

#### Via the Terminal (SSH):

If you prefer using the terminal, run the interactive configuration wizard:

```bash
hermes gateway setup

```

The wizard will guide you step by step to link your Telegram, Discord, or other accounts.

You can then run the gateway in the foreground to test the configuration:

```bash
hermes gateway

```

* * *

### 7. Run Hermes as a persistent 24/7 service

If you only run `hermes gateway` in an SSH session, the process will stop as soon as you disconnect.

To keep the agent **always on** , Hermes has built-in commands to install it automatically as a background service (systemd on Linux or launchd on macOS).

To install it as a user service (recommended):

```bash
hermes gateway install

```

Example terminal output:

```plaintext
Start the gateway now after installing the service? [Y/n]: y
Start the gateway automatically on login/boot with systemd? [Y/n]: y
Installing user systemd service to: ~/.config/systemd/user/hermes-gateway.service

✓ User service installed and enabled!

Next steps:
  hermes gateway start # Start the service
  hermes gateway status # Check status
  journalctl --user -u hermes-gateway -f # View logs

✓ Systemd linger is enabled (service survives logout)
✓ User service started

```

If you prefer to install it as a system-wide service so it starts automatically at boot:

```bash
sudo hermes gateway install --system

```

Once installed, you can easily manage the service lifecycle using the built-in Hermes commands:

| Action | Command |
| --- | --- |
| **Start the agent** | `hermes gateway start` |
| **Stop the agent** | `hermes gateway stop` |
| **Check the status** | `hermes gateway status` |

To check the status and ensure everything is running correctly:

```bash
hermes gateway status

```

Example output:

```plaintext
● hermes-gateway.service - Hermes Agent Gateway - Messaging Platform Integration
     Loaded: loaded (/home/username/.config/systemd/user/hermes-gateway.service; enabled; preset: enabled)
     Active: active (running) since Fri 2026-06-05 15:13:31 UTC; 2s ago
   Main PID: 3449 (hermes)
      Tasks: 4 (limit: 21479)
     Memory: 82.9M (peak: 97.5M)
        CPU: 2.119s
     CGroup: /user.slice/user-1000.slice/user@1000.service/app.slice/hermes-gateway.service
             └─3449 /usr/local/lib/hermes-agent/venv/bin/python -m hermes_cli.main gateway run --replace

Jun 05 15:13:31 demo-vps systemd[1228]: Started hermes-gateway.service - Hermes Agent Gateway.
Jun 05 15:13:33 demo-vps python[3449]: WARNING gateway.run: No messaging platforms configured.
✓ User gateway service is running
✓ Systemd linger is enabled (service survives logout)

```

* * *

### 8. Automate tasks with hermes cron

Hermes can schedule jobs using natural language, which is extremely useful on a VPS for monitoring and reporting.

Examples:

```bash
hermes cron "every weekday at 8 AM, summarize overnight server logs and send to Telegram"
hermes cron "every hour, check if https://example.com returns 200 and alert me if not"
hermes cron "every Friday at 5 PM, list all commits across my Git repos this week"

```

You do not need crontab syntax. Hermes parses these sentences, sets up the schedule, and runs the jobs unattended.

* * *

### 9. Secure your VPS and Hermes agent

Even if Hermes simplifies automation, it still runs as a service on a **VPS server**. A few security best practices:

- **Firewall** : only open the necessary ports (SSH by default). Note that if you use **Telegram or Discord** bots, they communicate via _Long Polling_ (outbound HTTP connections), so you do **not need to open any inbound ports** on your VPS firewall. You only need to open ports if you configure webhooks (like Slack), which typically listen on port 443 or a custom port. Use `ufw` or `firewalld`.
- **Non-root user** : run Hermes under a normal user account, added to the `docker` group if required.
- **SSH keys only** : disable password authentication in `sshd_config` and use SSH keys.
- **Command approvals** : keep approvals enabled for sensitive operations in Hermes instead of auto approving everything.
- **Backups** : regularly back up the `~/.hermes` directory (memory, config, logs) to an external location.

With this setup, your Hermes AI agent is permanently available on your VPS, ready to handle technical tasks, monitoring, or conversations across your favorite channels.

* * *

### Conclusion

By installing Hermes on a **VPS server** , you turn your machine into a fully autonomous AI assistant, perfect for task automation, service monitoring, and centralizing your workflows. At BoxToPlay we focus on reliable and high-performance VPS hosting that fits this kind of always-on agent. If you want to try this setup yourself, you can [start your free VPS trial](https://www.boxtoplay.com/en/vps-hosting/vps-server).