> For the complete documentation index, see [llms.txt](https://docs.ititanhosting.ro/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ititanhosting.ro/docs/english/vps/linux/how-to-install-hermes-agent-on-ubuntu.md).

# How to install Hermes Agent on Ubuntu

Hermes Agent is an open-source AI assistant that runs directly on your server. It can write code, manage files, run commands, browse the web, and more. In this guide, I will walk you through installing it on a fresh Ubuntu VPS.

### What you need

* a Linux VPS running Ubuntu 20.04 or newer
* SSH access with sudo privileges
* about 15 minutes

### Step 1: Connect to your VPS

If you haven't already, connect via SSH:

```bash
ssh root@your-server-ip
```

Replace `your-server-ip` with the actual IP of your VPS.

### Step 2: Update your system

Always start with a clean slate:

```bash
sudo apt update && sudo apt upgrade -y
```

### Step 3: Install Python and pip

Hermes needs Python 3.10 or newer. Ubuntu 22.04+ comes with it by default, but let us make sure everything is in place:

```bash
python3 --version

# If you need Python 3.11 specifically
sudo apt install python3.11 python3.11-venv python3-pip -y
```

### Step 4: Install uv (fast Python package manager)

Hermes uses `uv` under the hood. Install it with a single command:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

After the install completes, reload your shell:

```bash
source ~/.bashrc
```

Check that it worked:

```bash
uv --version
```

### Step 5: Install Hermes Agent

Now for the main event. Create a directory for Hermes and install it:

```bash
mkdir -p ~/hermes && cd ~/hermes

# Download and run the installer
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | sh
```

The installer will set up a virtual environment and download all dependencies. This might take a minute or two depending on your server.

### Step 6: Configure your API key

Hermes needs access to an LLM provider. The easiest way is to set up an OpenRouter API key:

```bash
export OPENROUTER_API_KEY="your-api-key-here"
```

To make this permanent, add it to your shell config:

```bash
echo 'export OPENROUTER_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc
```

You can get a free API key from [openrouter.ai/keys](https://openrouter.ai/keys).

### Step 7: Test that it works

Run a quick test to verify everything is set up correctly:

```bash
# Check the Hermes version
hermes --version

# Start an interactive session
hermes
```

If everything went well, you should see Hermes starting up and ready for your commands.

### Running Hermes as a service (optional)

If you want Hermes to keep running in the background, set it up as a systemd service:

```bash
sudo nano /etc/systemd/system/hermes.service
```

Paste this:

```ini
[Unit]
Description=Hermes Agent
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/root/hermes
ExecStart=/root/hermes/.venv/bin/hermes
Restart=always
Environment=OPENROUTER_API_KEY=your-api-key-here

[Install]
WantedBy=multi-user.target
```

Then enable and start it:

```bash
sudo systemctl daemon-reload
sudo systemctl enable hermes
sudo systemctl start hermes
sudo systemctl status hermes
```

### Common issues

#### "Command not found: hermes"

The installer adds Hermes to your PATH, but you might need to reload your shell:

```bash
source ~/.bashrc
# Or log out and back in
```

#### "uv: command not found"

Make sure `~/.local/bin` is in your PATH:

```bash
export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
```

### Where to go from here

* Read the [official Hermes documentation](https://hermes-agent.nousresearch.com/docs)
* Check out the [GitHub repo](https://github.com/nousresearch/hermes-agent)
* Join the community on Discord or GitHub Discussions