How to install Hermes Agent on Ubuntu VPS: Step-by-Step Guide

Installing Hermes Agent on an Ubuntu VPS gives your AI agent a server that stays online after your laptop or terminal session shuts down. 

To install Hermes Agent on Ubuntu VPS, you will: 

• Connect to your VPS with SSH. 

• Update Ubuntu and install the required Linux packages. 

• Create a dedicated Hermes user. 

• Run the official Nous Research installer. 

• Complete the Hermes setup wizard. 

• Verify the installation with hermes doctor. 

• Run the Hermes gateway with systemd if you want the agent to stay online. 

For example, you might want Hermes Agent to monitor a task, respond through Telegram or Discord, keep memory across sessions or stay available for browser automation while your laptop is shut. Running Hermes Agent on an Ubuntu VPS gives the same agent a persistent server environment instead of tying it to a local machine. 

This guide walks you through the complete setup, from server preparation to installation, configuration, gateway testing, firewall hardening and troubleshooting. By the end, you will have a working Hermes Agent installation on Ubuntu VPS that is ready for real workloads. 

Quick answer: How to install Hermes Agent on Ubuntu VPS 

To install Hermes Agent on an Ubuntu VPS, run the official Nous Research installer, configure your LLM provider with hermes setup, and check for configuration issues with hermes doctor. Then run hermes to start your first conversation. 

1. Run the official installer 

Connect to your Ubuntu VPS over SSH. Check the prerequisites in the official Hermes installation documentation, then run: 

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

2. Configure and check your setup 

After installation, reload your Bash shell and run: 

source ~/.bashrc 
hermes setup 
hermes doctor 

Use hermes setup to choose your model provider, configure authentication and select your tools and preferences. If you completed setup during installation, you can skip rerunning it. Use hermes doctor to identify missing configuration or installation issues. 

3. Start Hermes Agent 

Launch the agent and send a test prompt to confirm your model responds: 

hermes 

Optional messaging access: Run hermes gateway setup to configure a supported channel, such as Telegram, Discord or Slack. Then run hermes gateway to start the messaging gateway. 

Prefer one-click deployment? Bluehost Hermes Agent VPS Hosting offers one-click setup on a self-managed VPS. You can configure model providers, tools and gateway settings after deployment. The manual steps below cover server preparation, customization and troubleshooting. 

Also read: What is Hermes Agent? A Self-Hosted AI Agent Guide for Developers 

What you need before installing Hermes Agent on Ubuntu VPS 

Before you install Hermes Agent on Ubuntu VPS, make sure you have: 

• An Ubuntu 22.04 LTS or Ubuntu 24.04 LTS VPS 

• SSH access to the server 

• A user with sudo privileges 

• A stable internet connection from the server 

• curl installed or available through apt 

• An LLM provider plan, API keys or Nous Portal setup path 

• A domain name or static IP if you plan to expose webhooks, a web dashboard or external access 

• Basic comfort with Linux commands, terminal access and command-line setup 

For most API-backed agent workloads, you can start with modest server resources. If you plan to run local models on the same VPS, you will need more CPU, RAM, storage and more headroom. 

Your VPS should match the type of agent workload you plan to run. 

For a basic Hermes Agent setup using remote model APIs, start with: 

• 2 vCPU cores 

• 4 GB RAM 

• 40 GB storage 

• Ubuntu 22.04 LTS or 24.04 LTS 

• Root or sudo access 

• A dedicated IP address 

For heavier workflows, concurrent tasks, browser automation or local model experiments, consider: 

• 4 or more vCPU cores 

• 8 GB RAM or higher 

• NVMe storage 

• More disk space for logs, memory, project files, config files and model assets 

• A VPS plan that lets you upgrade or scale resources without rebuilding the server 

If you only want to install Hermes Agent on Ubuntu VPS and connect it to cloud-hosted LLM provider APIs, the baseline setup is enough to begin. If you want the VPS to handle local inference, choose more RAM before you deploy. 

How to install Hermes Agent on Ubuntu 

To install Hermes Agent on an Ubuntu VPS, prepare the server, create a dedicated user, run the official installer and configure your model provider. Then test the agent before setting up its messaging gateway as a background service. 

These steps assume a fresh Ubuntu VPS, a Bash shell and an administrator account with sudo access. 

Step 1: Connect to your Ubuntu VPS and update packages 

Connect to your server through SSH. Replace username and your-server-ip with your administrator username and server IP address: 

ssh username@your-server-ip 

Update the package lists and installed packages: 

sudo apt update && sudo apt upgrade -y 

If Ubuntu indicates that a reboot is required, restart the server: 

sudo reboot 

Wait for the server to restart, then reconnect: 

ssh username@your-server-ip 

Step 2: Install the required system packages 

The official Hermes installer manages the main runtime setup. Your server still needs basic command-line tools and system libraries. 

Run these commands as your administrator: 

sudo apt install -y curl git ca-certificates tar coreutils libatomic1 build-essential ufw 

This installs download tools, Git, archive utilities, certificate support, build tools and the firewall utility used below. libatomic1 supplies a library that the managed Node.js runtime may require on minimal Ubuntu installations. 

If you enable browser automation, you may also need additional Chromium system libraries. Install those as your administrator when prompted by the installation output or official documentation. 

Step 3: Configure the firewall and confirm SSH access 

Allow your SSH connection before enabling the firewall. 

The following example assumes SSH uses port 22. If your server uses another SSH port, replace 22 with that port before running the commands: 

sudo ufw default deny incoming 
sudo ufw default allow outgoing 
sudo ufw allow 22/tcp 
sudo ufw enable 
sudo ufw status verbose 

Keep your current SSH session open. Open another terminal and confirm that you can still connect to the server. 

Only open additional ports when a configured service requires inbound access. If you later add a dashboard or webhook endpoint, configure authentication and HTTPS before allowing public access. For private access, use an IP-restricted rule without leaving a broader public rule enabled. 

Step 4: Create a dedicated Hermes Agent user 

Create a separate account to own the Hermes installation, configuration and runtime files: 

sudo adduser --disabled-password --gecos "" hermes 

Keep this account without sudo privileges. Use your administrator account for package installation, firewall changes and system service management. 

Switch to the new account: 

sudo -iu hermes 

Run Steps 5–8 as the hermes user. This account does not have password-based SSH login configured. If you reconnect later, log in with your administrator account and switch users again with sudo -iu hermes. 

Step 5: Install Hermes Agent 

Run the official Nous Research Linux installer: 

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

You can review the prerequisites and installation options in the official Hermes installation documentation. 

If the installer offers to configure your model provider, you can complete that setup now. Leave background service installation and startup for Step 9. 

After installation, reload your Bash configuration: 

source ~/.bashrc 

Check that the command is available: 

command -v hermes 

For this user, the launcher will normally be: 

/home/hermes/.local/bin/hermes 

If the command is not found, add the launcher directory to your current shell’s search path and check again: 

export PATH="$HOME/.local/bin:$PATH" 
command -v hermes 

If it remains unavailable, review the installer output for errors before continuing. 

Step 6: Configure your model provider and tools 

If you did not complete configuration during installation, start the setup wizard: 

hermes setup 

Choose a supported model provider, complete authentication and configure the tools and runtime settings you need. 

You can update individual settings later: 

hermes model 
hermes tools 

If you prefer Nous Portal, use this alternative setup command: 

hermes setup --portal 

Choose the setup path that matches your provider. You do not need to run every configuration option. 

Hermes stores user-managed API keys and bot tokens in ~/.hermes/.env. If setup created that file, restrict its permissions: 

chmod 600 ~/.hermes/.env 

Keep credential files out of repositories and publicly accessible directories. 

Step 7: Verify the installation and test a conversation 

Check the installed version and run diagnostics: 

hermes --version 
hermes doctor 

Review the results and resolve errors affecting your selected provider or enabled tools. 

Start the interactive CLI: 

hermes 

Send a short test prompt and confirm that the model responds without authentication or connection errors. Exit the CLI before continuing. 

A successful response confirms that the installation and provider connection work together. If you only need interactive terminal access, you can stop here. Continue to configure messaging and continuous gateway operation. 

Step 8: Configure and test the messaging gateway 

To connect messaging platforms such as Telegram, Discord or Slack, run: 

hermes gateway setup 

Follow the prompts for your chosen platform. Configure allowed users or approved pairing before using the bot. Leave automatic background service installation and startup disabled for now. 

Test the gateway in the foreground: 

hermes gateway run 

Send a message from an authorized account on your configured platform. Confirm that Hermes receives it and responds. 

Press Ctrl+C to stop the foreground gateway after testing. Resolve any errors before moving to systemd. 

Use hermes gateway run for this test. The hermes gateway start command is intended to start an already installed background service. 

Step 9: Run the Hermes gateway with systemd 

A systemd service lets the gateway operate independently of your SSH session and start automatically after a reboot. 

First, exit the hermes shell to return to your administrator account: 

exit 

Create a system service file: 

sudo nano /etc/systemd/system/hermes-agent.service 

Add the following configuration. If Step 5 returned a different launcher path, update ExecStart accordingly: 

[Unit] 
Description=Hermes Agent Gateway 
Wants=network-online.target 
After=network-online.target 
 
[Service] 
Type=simple 
User=hermes 
WorkingDirectory=/home/hermes 
Environment=HOME=/home/hermes 
Environment=HERMES_HOME=/home/hermes/.hermes 
Environment=PATH=/home/hermes/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin 
ExecStart=/home/hermes/.local/bin/hermes gateway run 
KillMode=mixed 
Restart=on-failure 
RestartSec=5 
 
[Install] 
WantedBy=multi-user.target 

The ExecStart command runs the gateway in the foreground so systemd can supervise it. Restart=on-failure restarts a failed process, while RestartSec=5 adds a five-second delay between attempts. 

Save the file, reload systemd and enable the service: 

sudo systemctl daemon-reload 
sudo systemctl enable --now hermes-agent 

Check its status: 

sudo systemctl status hermes-agent --no-pager 

Look for active (running). If the service fails, inspect the logs: 

sudo journalctl -u hermes-agent -n 100 --no-pager 

To follow logs in real time: 

sudo journalctl -u hermes-agent -f 

Press Ctrl+C to stop viewing logs. The service continues running. 

After updating Hermes or changing settings that require a restart, restart this custom service: 

sudo systemctl restart hermes-agent 

Use these systemctl commands to manage the custom service. Keep only one gateway service running for this installation. 

Hermes retains saved memory across restarts when its data directory remains intact. Continuous gateway operation keeps messaging and scheduled workflows available; memory retention does not depend on uninterrupted uptime. 

Quick setup overview: Install Hermes Agent on Ubuntu VPS 

Step	Action	Main commands	Why it matters
1	Connect to your Ubuntu VPS and update packages	ssh username@your-server-ipsudo apt update && sudo apt upgrade -ysudo reboot	Gives Hermes Agent a clean, updated Ubuntu environment and helps avoid package conflicts.
2	Install curl and basic system packages	sudo apt install curl git ca-certificates -ycurl –version	Installs the basic tools needed to run the official Hermes Agent installer.
3	Create a dedicated Hermes Agent user	sudo adduser –disabled-password –gecos “” hermessudo usermod -aG sudo hermessudo -iu hermes	Keeps Hermes files, configuration, API keys and runtime activity separate from the root account.
4	Install Hermes Agent on Ubuntu VPS	curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bashsource ~/.bashrccommand -v hermes	Installs Hermes Agent and confirms that the hermes command is available.
5	Verify the Hermes Agent installation	hermes –versionhermes doctorhermes	Checks that Hermes Agent installed correctly and can start from the command line.
6	Configure Hermes Agent	hermes setuphermes modelhermes toolshermes setup –portal	Connects Hermes to your model provider, API keys, tools, skills and runtime preferences.
7	Test Hermes Agent from the command line	hermeshermes gatewayhermes gateway setuphermes gateway start	Confirms that Hermes and the gateway work before you run them as a background service.
8	Run Hermes Agent with systemd	command -v hermessudo nano /etc/systemd/system/hermes-agent.servicesudo systemctl daemon-reloadsudo systemctl enable hermes-agentsudo systemctl start hermes-agent	Keeps the Hermes gateway running continuously after SSH disconnects, crashes or server reboots.
9	Secure your Hermes Agent VPS before going live	sudo ufw allow OpenSSHsudo ufw enablesudo ufw statussudo ufw allow 443/tcp	Reduces exposure by limiting public access, protecting SSH and opening only the ports your setup needs.

Troubleshooting when you install Hermes Agent on Ubuntu VPS 

Installation issues are common on fresh servers. Use this table to identify the most likely cause and fix. 

Problem	Likely cause	Fix
hermes: command not found	Your shell path has not reloaded	Run source ~/.bashrc, reopen SSH or check command -v hermes
Installer fails	Missing basic packages or network issue	Install curl, git and ca-certificates, then retry
Permission denied	Hermes was installed under a different user	Switch to the correct user or reinstall as the dedicated hermes user
hermes doctor reports missing dependencies	The installer did not complete cleanly	Re-run the installer and review the output
Gateway service fails under systemd	ExecStart path is wrong	Run command -v hermes as the hermes user and update the service file
Service starts then exits	Gateway is not configured	Run hermes gateway setup manually first
API authentication fails	Provider setup is incomplete or credentials are wrong	Run hermes setup, hermes model or your provider setup flow again
SSH disconnect stops the agent	You are running Hermes manually instead of through systemd	Use systemd for the gateway or run interactive sessions manually only
Server runs out of memory	Workload exceeds available RAM	Upgrade the VPS or use remote model inference

When systemd logs are unclear, test manually as the hermes user: 

sudo -iu hermes 
hermes doctor 
hermes gateway start 

Manual runs usually show clearer errors than service status output. 

Also read: Hermes Agent VPS Security Guide: How to Secure a Self-Hosted AI Agent 

How to update Hermes Agent 

To update Hermes Agent after installation, switch to the hermes user: 

sudo -iu hermes 

Then run: 

hermes update 

After updating, run: 

hermes doctor 

If you use the systemd gateway service, restart it: 

exit 
sudo systemctl restart hermes-agent 
sudo systemctl status hermes-agent 

Check the logs after every update: 

sudo journalctl -u hermes-agent -n 100 

This confirms that the updated version starts cleanly and that your gateway configuration still works. 

Also read: Hermes Agent Docker: Production Setup Guide That Works 

What to look for in a Hermes Agent VPS 

The best VPS for Hermes Agent depends on how you plan to use it. For basic API-backed workflows, a smaller VPS can work well. For local models, parallel tasks, browser automation or heavier automation, choose more CPU, RAM and storage. 

Look for these features: 

• Full root or sudo access 

• Ubuntu 22.04 LTS or Ubuntu 24.04 LTS support 

• NVMe storage 

• Dedicated resources 

• Scalable CPU and RAM 

• Static IP or dedicated IP support 

• Reliable uptime 

• Easy SSH access 

• Firewall control 

• Support for long-running background services 

• One-click provisioning or simple dashboard access where available 

When Bluehost Hermes Agent VPS Hosting makes sense 

Bluehost Hermes Agent VPS Hosting makes sense if you want to run Hermes Agent on a self-managed VPS without starting from a blank server. Instead of preparing every layer manually, you get a one-click deployment path for Hermes Agent, then continue configuring the model provider, API keys, gateway workflows, memory, skills and server settings yourself. 

This is useful if your goal is not just to install Hermes Agent once, but to keep the same agent running beyond a laptop session. A VPS gives Hermes Agent a persistent runtime for scheduled tasks, messaging channels, browser automation and long-running workflows. Bluehost adds a faster setup path while still giving technical users control over the environment. 

It is still worth understanding the manual steps in this guide. They help you troubleshoot the installation, secure the server, verify the Hermes gateway and know what is happening behind the one-click setup. 

Give Hermes Agent a server it can grow into 

Installing Hermes Agent on Ubuntu VPS is more than a setup task. It is the step that turns a local AI agent into a persistent system that can keep working after your laptop shuts, your terminal closes or your session ends. 

The manual path gives you full visibility into how the server is prepared, how Hermes Agent is installed, how the setup wizard connects your model provider and how the Hermes gateway stays online through systemd. Those details matter because an agent is only as reliable as the environment it runs in. A clean install, a dedicated user, secure API key handling, firewall rules and restart behavior all shape how stable the agent becomes in real workloads. 

If you want more control, follow the manual Ubuntu VPS setup. If you want a faster starting point, Bluehost Hermes Agent VPS Hosting gives you a one-click deployment path while still leaving room to configure the agent, gateway, memory, skills and provider settings yourself. Either way, the real decision is not just where to install Hermes Agent. It is whether you want your agent to remain a temporary tool on a machine you open occasionally or a persistent worker with a server of its own. 

Frequently asked questions