Running an AI agent with real system access on your Linux server changes how you work. You get persistent automation that runs 24/7, learns from your projects, and executes shell commands when you need them. But installing Hermes Agent correctly on AlmaLinux 10 requires care. Many tutorials skip critical security steps that leave your server exposed.

This guide shows you how to install Hermes Agent on AlmaLinux 10 the right way. You will create a dedicated non-root user, set up a systemd service for persistence, configure firewall hardening, and verify the installation end-to-end. Every command includes the WHY behind it, not just the HOW. This approach comes from 10 years of sysadmin experience deploying production services on RHEL-compatible systems.

By the end, you will have a hardened Hermes Agent instance running under systemd, ready to connect to Telegram or your preferred messaging platform. Let’s get started.

Prerequisites

Before running any commands, verify you have these requirements. Skipping prerequisites causes 80% of installation failures on AlmaLinux 10.

Operating System

• AlmaLinux 10 installed (x86_64 or ARM64 architecture)
• Fresh installation recommended for first-time setup

Hardware Requirements

• Minimum 2 GB RAM available (4 GB recommended for production workloads)
• At least 20 GB free disk space for dependencies and agent memory
• Stable internet connection for GitHub and LLM provider API access

User Permissions

• Root or sudo-capable user for initial system setup
• You will create a dedicated hermes user (do not run as root)
• SSH access to the server from your terminal

Tools You Need

• curl installed (or install via DNF)
• git installed (required for cloning skills post-install)
• Python 3.11 or higher (installer handles this automatically)

API Keys

• OpenRouter API key, DeepSeek API key, or any OpenAI-compatible endpoint key
• Have this key ready before running hermes setup

Time Investment

• 15 to 20 minutes for a fresh install with all hardening steps
• Add 5 minutes if you need to install curl and git first

Step 1: Update AlmaLinux 10 and Install Dependencies

A stale package cache on AlmaLinux 10 causes dependency conflicts during Hermes installation. This step prevents broken installs and version collisions.

Update Your System

sudo dnf update -y

WHAT this does: The dnf update command refreshes your package database and installs all available updates for AlmaLinux 10. The -y flag automatically confirms the installation without prompting.

WHY this matters: AlmaLinux 10 ships with a base package set that may be several minor releases behind. The Hermes installer requires Python 3.11+ at minimum. Running on an outdated system creates version collisions with the installer’s dependency resolver.

Expected output:

AlmaLinux 10 (Kitten)
Additional packages: 47
Total download size: 234 MB
Is this ok | yes | no: yes
...
Complete!

Install curl and git

sudo dnf install -y curl git

WHAT this does: Installs curl for downloading the installer script and git for cloning post-install skills from external repositories.

WHY this matters: The installer script uses curl to fetch the setup payload from the Nous Research GitHub repository. Without git, post-install skill cloning fails completely. Both must be present before running the one-line installer.

Expected output:

Package curl-7.79.1-10.alma10.x86_64 is already installed.
Package git-2.40.1-1.alma10.x86_64 is already installed.
Dependency solved.
Is this ok | yes | no: yes
...
Complete!

Verify Python 3.11 Availability

python3 --version

WHAT this does: Checks the current Python version on your system to confirm it meets Hermes Agent’s minimum requirement of Python 3.11.

WHY this matters: If the version returned is below 3.11, the installer will upgrade Python automatically. Knowing the current version before running the installer lets you predict whether it will upgrade or skip. Surprises mid-install are never good on a production box.

Expected output (if Python 3.11+ is installed):

Python 3.11.5

If Python is below 3.11, install it explicitly:

sudo dnf install -y python3.11
sudo alternatives --set python3 /usr/bin/python3.11

WHAT these commands do: The first installs Python 3.11 via DNF. The second sets Python 3.11 as the default python3 interpreter using the alternatives system.

WHY this matters: Some scripts call python3 without specifying the version. The alternatives system ensures all scripts use the correct version consistently.

Step 2: Create a Dedicated Non-Root User for Hermes Agent

Running Hermes Agent as root is the single biggest security mistake beginners make. This step is non-negotiable for production deployments.

Create the hermes User

sudo useradd -m -s /bin/bash hermes
sudo passwd hermes

WHAT these commands do:

• useradd -m -s /bin/bash hermes creates a new user named hermes with a home directory (-m) and bash as the shell (-s /bin/bash)
• passwd hermes prompts you to set a password for the new user

WHY this matters: Hermes Agent has direct, real-time access to your server’s filesystem, shell, and network. Running it as root means a single mistaken agent command, a bad prompt injection, or a compromised API key could wipe the entire server. A dedicated user limits the blast radius to /home/hermes/ and nothing else.

Expected output:

Changing password for user hermes.
New password: 
(retype New password: )
Password changed.

Grant sudo Access (Optional but Recommended)

sudo usermod -aG wheel hermes

WHAT this does: Adds the hermes user to the wheel group, which on AlmaLinux 10 grants sudo privileges.

WHY this matters: The agent may need to run specific commands that require elevated privileges (like installing system packages as part of a skill). Giving it sudo access within the wheel group allows this while still keeping it separate from the root user. The agent still cannot escalate to root without explicit sudo authorization.

Switch to the hermes User

su - hermes

WHAT this does: Switches your current shell session to the hermes user. All subsequent commands run under this user’s permissions.

WHY this matters: You must run the installer as the hermes user, not root. The installer writes files to ~/.hermes/, which maps to /home/hermes/.hermes/. Running as root would write to /root/.hermes/, breaking the systemd service path later.

Verify you are the hermes user:

whoami

Expected output:

hermes

Step 3: Run the Official Hermes Agent Installer

This is the core installation step. The command is short, but the reasoning behind each flag matters deeply.

Execute the One-Line Installer

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

WHAT this command does:

• curl downloads the installer script from the Nous Research server
• The -fsSL flags mean:
  • -f: Fail silently on server errors (no output on 404)
  • -s: Silent mode (no progress bar)
  • -S: Show errors that -s would normally hide
  • -L: Follow HTTP redirects
• The | bash part pipes the downloaded script directly to the bash interpreter for execution

WHY this exact command matters: Using a bare curl | bash without the -fsSL flags can silently install a broken version if the URL ever redirects. The flags ensure you get the correct script and see errors if something fails. This is the official installation method from Nous Research documentation.

Expected output:

[INFO] Installing Hermes Agent...
[INFO] Downloading dependencies...
[INFO] Python 3.11 detected, skipping upgrade
[INFO] Installing to /home/hermes/.hermes
[INFO] Setup complete. Run 'source ~/.bashrc' to load the binary.

Reload Your Shell Environment

source ~/.bashrc

WHAT this does: Reloads your bash configuration file, which now includes the path to the hermes binary added by the installer.

WHY this matters: The installer adds the Hermes binary path to ~/.bashrc. Without reloading, your shell session does not know where the binary lives. Every hermes command returns “command not found” until you reload.

Verify the Installation

hermes --version
hermes doctor

WHAT these commands do:

• hermes --version displays the installed Hermes Agent version number
• hermes doctor runs a live diagnostic that checks API key configuration, Python dependencies, and install directory structure

WHY hermes doctor specifically matters: Unlike --version, hermes doctor catches broken installs that report as successful. It verifies your API key configuration is reachable, dependencies are intact, and the install directory is structured correctly. This step prevents thinking you have a working install when you actually have a broken one.

Expected output from hermes doctor:

[OK] Hermes Agent version: 0.10.0
[OK] Python 3.11.5 found at /usr/bin/python3.11
[OK] API key configured: DEEPSEEK
[OK] Dependencies intact
[OK] Install directory: /home/hermes/.hermes

Step 4: Configure Hermes Agent with Initial Setup

Installation and configuration are two distinct phases. Most tutorials blur them together and leave readers with an installed but non-functional agent.

Launch the Interactive Setup Wizard

hermes setup

WHAT this does: Runs the interactive setup wizard that configures your LLM provider, links your API key, and sets the default model.

WHY this matters: hermes setup is not optional. Without this step, the agent binary exists on the server but cannot reason, respond, or execute any tools. The wizard guides you through provider selection and key entry interactively.

Choose Your LLM Provider

During setup, select one of these providers:

• OpenRouter (recommended for model flexibility)
• DeepSeek (recommended for cost efficiency on VPS deployments)
• Nous Portal (official Nous Research provider)
• Any OpenAI-compatible endpoint

WHY provider choice matters: Model costs accumulate fast on a persistent server agent. Cheap, fast models are correct for simple shell tasks. Reserve expensive models like Claude Sonnet or Opus for complex reasoning workflows that actually need them. Configuring the wrong model by default on a 24/7 server can generate unexpected API bills within hours.

Set Your Model Explicitly (Optional)

If you prefer to set the model manually instead of through the wizard:

hermes config set model.provider deepseek
hermes config set model.default deepseek-v4-pro
echo 'DEEPSEEK_API_KEY=your_key_here' >> ~/.hermes/.env

WHAT these commands do:

• hermes config set model.provider deepseek sets DeepSeek as your LLM provider
• hermes config set model.default deepseek-v4-pro sets the default model to use
• echo 'DEEPSEEK_API_KEY=...' >> ~/.hermes/.env writes your API key to the environment file

WHY manual configuration matters: Sometimes the interactive wizard fails on AlmaLinux 10 due to terminal encoding issues. Setting the provider and key manually via commands bypasses the wizard and ensures your configuration is correct. The .env file is where Hermes reads all environment variables at runtime.

Step 5: Configure Firewall and Security Hardening

A live AI agent with shell access on a port-exposed server is an attack surface. This section is non-optional for any public-facing deployment.

Tighten File Permissions on the Hermes Config Directory

chmod 700 ~/.hermes/
chmod 600 ~/.hermes/.env

WHAT these commands do:

• chmod 700 ~/.hermes/ sets the directory permissions to read, write, and execute for the owner only
• chmod 600 ~/.hermes/.env sets the environment file to read and write for the owner only

WHY this matters: The .env file contains live API keys. If another user on the same system can read it, those keys are compromised immediately. 700 on the directory and 600 on the file restrict access to only the hermes user. No other user can list the directory or read the file.

Set Dangerous Command Approval Mode

hermes config set approval_mode ask

WHAT this does: Configures Hermes Agent to pause and require manual confirmation before executing any command flagged as destructive (file deletions, network changes, service restarts).

WHY this matters: With approval_mode: ask, the agent becomes a human-in-the-loop system. A single prompt injection attack or misunderstood instruction cannot wipe your /etc directory or restart your database. This is the safety net that separates a responsible deployment from a liability.

Set the Working Directory (CWD)

hermes config set terminal.cwd /home/hermes/projects

WHAT this does: Sets the agent’s default working directory to /home/hermes/projects instead of the root directory or /etc.

WHY this matters: Without an explicit CWD, the agent may operate from sensitive directories like / or /etc. Setting CWD to a dedicated project folder is the simplest way to contain what the agent can touch. Even if the agent tries to write outside this directory, systemd’s ProtectSystem=strict will block it later.

Create the Projects Directory

mkdir -p /home/hermes/projects
chmod 700 /home/hermes/projects

WHAT these commands do: Creates the projects directory and sets permissions to owner-only access.

WHY this matters: The CWD must exist before the agent starts. If the directory does not exist, Hermes will fail to initialize and the systemd service will report an error. Creating it upfront prevents startup failures.

Step 6: Set Up Hermes Agent as a Persistent systemd Service

Without systemd, the agent dies the moment your SSH session closes. This step makes the installation production-grade.

Create the systemd User Service Directory

mkdir -p ~/.config/systemd/user/

WHAT this does: Creates the directory where systemd looks for user-level service unit files.

WHY this matters: AlmaLinux 10 uses systemd user services for non-root processes. The ~/.config/systemd/user/ path is the standard location for user service files. Without this directory, the service file cannot be saved.

Create the Hermes Gateway Service File

nano ~/.config/systemd/user/hermes-gateway.service

WHAT this does: Opens the nano text editor to create a new systemd unit file named hermes-gateway.service.

Paste the following content into the file:

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

[Service]
ExecStart=/home/hermes/.hermes/bin/hermes gateway start
Restart=on-failure
RestartSec=5
ProtectSystem=strict
ProtectHome=read-only
ReadWritePaths=/home/hermes/.hermes
User=hermes

[Install]
WantedBy=default.target

WHAT each section does:

• [Unit] defines the service name and dependencies (After=network.target ensures networking is ready before starting)
• [Service] defines the startup command, restart behavior, and security hardening:
  • ExecStart is the exact path to the Hermes binary
  • Restart=on-failure restarts the service if it crashes
  • RestartSec=5 waits 5 seconds before restarting
  • ProtectSystem=strict makes the filesystem read-only except for allowed paths
  • ProtectHome=read-only protects the home directory
  • ReadWritePaths=/home/hermes/.hermes allows writes only to the Hermes directory
  • User=hermes runs the service under the hermes user, not root
• [Install] enables the service to start automatically at login

WHY systemd security directives matter: ProtectSystem=strict and ProtectHome=read-only make the entire filesystem read-only for the service, except for explicitly allowed ReadWritePaths. Even if a prompt injection attack tricks the agent into writing files, it physically cannot write outside /home/hermes/.hermes/. This is the defense-in-depth layer that most guides omit entirely.

Enable Linger so the Service Survives SSH Logout

First, exit the hermes user and return to root:

exit

Then run:

loginctl enable-linger hermes

WHAT this does: Enables systemd “linger” for the hermes user, which keeps the user’s systemd slice alive even when no sessions are active.

WHY this matters: On AlmaLinux 10, systemd user services stop when the user’s last session ends. enable-linger tells systemd to keep the user’s slice alive at all times, making the service persist even after you close your terminal and SSH disconnect.

Start and Enable the Service

Switch back to the hermes user:

su - hermes

Then run:

systemctl --user daemon-reload
systemctl --user enable --now hermes-gateway
systemctl --user status hermes-gateway

WHAT these commands do:

• systemctl --user daemon-reload reloads systemd’s unit file cache to detect the new service file
• systemctl --user enable --now hermes-gateway enables the service for automatic startup and starts it immediately
• systemctl --user status hermes-gateway shows the current service state

WHY check status immediately matters: A green active (running) status confirms systemd successfully launched the process. A failed status at this point means the ExecStart path is wrong, which is far easier to debug immediately than 12 hours later when you wonder why the agent stopped stopped responding.

Expected output:

● hermes-gateway.service - Hermes Agent Gateway
     Loaded: loaded (/home/hermes/.config/systemd/user/hermes-gateway.service; enabled)
     Active: active (running) since Fri 2026-06-12 13:45:22 WIB
   Main PID: 12847 (hermes)
      Tasks: 12 (limit: 4953)
     Memory: 145.2M

Verify the Process Runs Under the hermes User

ps aux | grep hermes

WHAT this does: Lists all running processes and filters for lines containing “hermes”.

WHY this matters: Confirms the process is running under the hermes user, not root. If root appears as the process owner in the output, the systemd unit file was not configured correctly. Fix it before proceeding.

Expected output:

hermes    12847  2.3  0.8 145234 98765 ?        Sl     13:45   0:12 /home/hermes/.hermes/bin/hermes gateway start

Note that hermes appears in the first column, not root.

Troubleshooting Common Installation Errors on AlmaLinux 10

No tutorial is complete without addressing what breaks. Each error below represents a documented failure mode from real community deployments.

Error 1: hermes: command not found After Install

Root Cause: Shell not reloaded after the installer ran.

Solution:

source ~/.bashrc

WHY this fixes it: The installer adds the Hermes binary path to ~/.bashrc. Without reloading, your shell does not know where the binary lives.

Error 2: hermes doctor Reports API Key Failure

Root Cause: API key not written to ~/.hermes/.env file.

Solution:

echo 'DEEPSEEK_API_KEY=your_actual_key_here' >> ~/.hermes/.env
hermes setup

WHY this fixes it: Hermes reads all environment variables from ~/.hermes/.env at runtime. If the key is missing, the agent cannot connect to the LLM provider.

Error 3: systemd Service Fails to Start

Root Cause: Wrong path in the ExecStart directive of the service file.

Solution:

which hermes

Then update the service file:

nano ~/.config/systemd/user/hermes-gateway.service

Replace the ExecStart line with the correct path from which hermes:

ExecStart=/home/hermes/.hermes/bin/hermes gateway start

Reload and restart:

systemctl --user daemon-reload
systemctl --user restart hermes-gateway

WHY this fixes it: The ExecStart path must match the actual binary location exactly. which hermes shows the correct path.

Error 4: Agent Runs as Root Instead of hermes User

Root Cause: Service started without the User=hermes directive in the [Service] block.

Solution: Open the service file and add the User=hermes line:

nano ~/.config/systemd/user/hermes-gateway.service

Add this line inside the [Service] block:

User=hermes

Reload and restart:

systemctl --user daemon-reload
systemctl --user restart hermes-gateway

WHY this fixes it: The User=hermes directive explicitly tells systemd to run the service under the hermes user account, not root.

Error 5: curl: (6) Could not resolve host

Root Cause: No internet connection on the server or DNS configuration issue.

Solution:

cat /etc/resolv.conf

Check if nameserver entries exist. If empty, add a resolver:

echo 'nameserver 8.8.8.8' >> /etc/resolv.conf

Test connectivity:

curl -I https://hermes-agent.nousresearch.com

WHY this fixes it: The server needs a valid DNS resolver to reach external hosts. Adding nameserver 8.8.8.8 (Google’s public DNS) provides connectivity.

Next Steps After Hermes Agent Is Installed

Your Hermes Agent is now running as a hardened systemd service. Here is what to do next to maximize its value.

Connect Telegram Gateway for Mobile Access

hermes gateway setup

WHAT this does: Guides you through creating a Telegram bot and pairing it with your Hermes Agent instance.

WHY this matters: You can interact with the agent from your phone instead of being tied to the terminal. This is the most common production use case for Hermes Agent.

Create an AGENTS.md File for Project Context

mkdir -p /home/hermes/projects
touch /home/hermes/projects/AGENTS.md

Edit the file and add your project goals, coding standards, and any off-limit commands.

WHY this matters: The AGENTS.md file gives the agent persistent context about your project. It learns your preferences over time and avoids repeating mistakes. This is how Hermes Agent “grows with you”.

Rotate API Keys Every 30 Days

hermes config set api.key your_new_key

Then review permissions:

chmod 600 ~/.hermes/.env

WHY this matters: API keys are sensitive credentials. Rotating them periodically limits the damage if a key is compromised. The chmod 600 ensures the file remains owner-only readable after the update.

Restore Previous Session When Reconnecting

hermes -c

WHY this matters: The -c flag restores your previous conversation session when reconnecting after a gap. This maintains context across multiple sessions instead of starting fresh each time.

[su_box title=”VPS Manage Service Offer” style=”bubbles” box_color=”#000000″ radius=”10″]If you don’t have time to do all of this stuff, or if this is not your area of expertise, we offer a service to do “VPS Manage Service Offer”, starting from $10 (Paypal payment). Please contact us to get the best deal![/su_box]