Getting Hermes Agent running on a fresh Linux Mint 22 box shouldn’t feel like decoding ancient runes. Yet too many guides skip the gritty details—what happens when uv fails to provision Python, why your Docker container loses memory on restart, or which firewall rules actually matter in production. This walkthrough covers the full installation stack, from prerequisite checks to post-install hardening, with real troubleshooting paths drawn from managing similar agent deployments across VPS infrastructure.

Linux Mint 22 (“Wilma”) ships with Python 3.12 by default, but Hermes Agent requires Python 3.11 in an isolated environment. The official installer handles this via uv, a Rust-based Python package manager that’s significantly faster than pip. You’ll also need Git, and optionally Docker if you want containerized command execution. Expect the core install to take 2–5 minutes on a standard VPS with 4GB RAM.

Beyond the basic commands, this guide dives into what matters for production use: securing API credentials, tuning resource limits, configuring approval gates for dangerous operations, and setting up monitoring so you’re not flying blind when the agent starts executing tasks at 3 AM. Whether you’re deploying on a local workstation or a remote VPS, the principles remain the same—isolate, authenticate, and audit.

Understanding Hermes Agent Architecture

Hermes Agent isn’t just another CLI wrapper around an LLM API. It’s a persistent, self-improving system that maintains memory across sessions, builds custom skills from experience, and can execute commands either directly on your host or inside sandboxed Docker containers. This architecture has direct implications for how you install and secure it.

The agent consists of three core components:

• Gateway: An OpenAI-compatible API server (default port 8642) that handles external connections from dashboards, tools, or custom integrations.
• Memory & Skills Engine: Persistent storage for conversation history, learned patterns, and custom capabilities. Lives in ~/.hermes by default.
• Command Executor: Either runs natively on your system or inside Docker containers for isolation. This is where security boundaries matter most.

For Linux Mint 22 specifically, you’re working with an Ubuntu 24.04 base, which means apt package management, systemd for services, and UFW as the default firewall. The installation methods below account for these specifics.

Prerequisites and System Requirements

Before running any installer, verify your system meets the baseline requirements. Hermes Agent is lightweight compared to local LLM runners, but cutting corners here leads to cryptic failures later.

Hardware Requirements

The 2 GB minimum works for basic CLI usage with hosted models. If you’re running local models via Ollama or similar, add at least 4 GB per concurrent model instance. Gateway services and browser automation (Playwright) push requirements higher—8 GB gives comfortable headroom.

Software Dependencies

Only Git is strictly required upfront. The installer handles everything else:

• Git: Version control for cloning the repository
• Python 3.11: Provisioned automatically via uv (doesn’t touch system Python)
• Node.js v22: Installed for browser automation features
• uv: Fast Python package manager (Rust-based)
• ripgrep & ffmpeg: Optional but recommended for search and media processing

Linux Mint 22 ships with Python 3.12, which is incompatible. The installer’s uv layer provisions Python 3.11 in an isolated virtual environment, avoiding conflicts with system packages. This is critical—don’t try to downgrade your system Python.

Network Considerations

Hermes Agent requires internet connectivity for hosted model APIs (Anthropic, OpenAI, OpenRouter, etc.). If you’re behind a corporate firewall or proxy, ensure outbound HTTPS (443) is allowed to:

• api.anthropic.com
• api.openai.com
• openrouter.ai
• GitHub (for updates)

Local model deployments via OpenAI-compatible endpoints work offline once configured. For VPS deployments, consider setting up a dedicated egress firewall rule to log and monitor agent traffic.

Installation Method 1: Native Install via One-Line Script

The fastest path to a working Hermes Agent is the official installer script. It’s been tested across Ubuntu, Debian, Fedora, and Arch derivatives—Linux Mint 22 falls squarely in the supported range.

Step 1: Install Git

The installer requires Git to clone the repository. On Linux Mint 22:

sudo apt update
sudo apt install -y git

Verify the installation:

git --version

You should see output like git version 2.43.0 or newer. If you’re on a minimal VPS image without apt, use your distro’s equivalent (dnf install git for Fedora/RHEL, pacman -S git for Arch).

Step 2: Run the Installer

With Git installed, execute the one-line installer:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Breaking down the flags:

• -f: Fail silently on HTTP errors (prevents partial downloads)
• -s: Silent mode (no progress meter)
• -S: Show errors if they occur
• -L: Follow redirects

The script performs these operations automatically:

1. Detects your OS and architecture
2. Downloads and installs uv to /root/.local/bin or ~/.local/bin
3. Provisions Python 3.11 in an isolated environment
4. Clones the Hermes Agent repository with submodules
5. Installs dependencies into a virtual environment
6. Creates the hermes CLI command and adds it to your PATH

Step 3: Verify Installation

After the installer completes, verify the setup:

hermes --version

Expected output: hermes 0.14.0 or newer (version numbers increment regularly).

Run a diagnostic check:

hermes doctor

This validates Python, uv, dependencies, config files, and connectivity. If anything fails, the output points directly to the issue—missing packages, permission errors, or network problems.

Step 4: First-Time Configuration

Launch the interactive setup:

hermes setup

The wizard prompts for:

• LLM Provider: Anthropic, OpenAI, DeepSeek, OpenRouter, etc.
• API Key: Your provider’s authentication token
• Messaging Channels: Telegram, Discord, Slack, WhatsApp (optional)
• Model Selection: Claude 3.5 Sonnet, GPT-4o, etc.

For security, never hardcode API keys in config files. The setup stores them in ~/.hermes/config.json with appropriate file permissions (600), but consider using environment variables or a secrets manager for production deployments.

Alternative: PyPI Installation

As of v0.14.0, Hermes Agent is available on PyPI:

pip install -U hermes-agent

Or with uv for faster installs:

uv pip install -U hermes-agent

This method skips the Git clone and submodule setup, useful for scripted deployments or Docker builds. The trade-off is you lose the automatic dependency management the full installer provides.

Installation Method 2: Docker Deployment

Docker deployment isolates Hermes Agent from your host system, ideal for VPS setups or when you want command execution sandboxed. This approach also simplifies updates and rollback.

Step 1: Install Docker Engine

On Linux Mint 22 (Ubuntu 24.04 base):

sudo apt update
sudo apt install -y docker.io
sudo usermod -aG docker $USER

Log out and back in for group changes to take effect, or run:

newgrp docker

Verify Docker is running:

docker --version
docker info

You should see Docker Engine version 24.x or newer.

Step 2: Create Persistent Data Directory

Hermes stores all state—config, API keys, memories, skills—in ~/.hermes. This must be mounted as a Docker volume, or data vanishes on container restart.

mkdir -p ~/.hermes

Step 3: Run Setup Wizard

Execute the interactive setup inside a container:

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  --shm-size=1g \
  nousresearch/hermes-agent:latest setup

Critical flags:

• -v ~/.hermes:/opt/data: Mounts your host directory to the container’s data path
• --shm-size=1g: Allocates shared memory for Playwright (browser automation)
• --rm: Removes container after setup completes

The wizard walks through the same configuration as the native install: provider selection, API key entry, messaging channel setup.

Step 4: Start the Gateway

Once configured, run the gateway service:

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  nousresearch/hermes-agent:latest \
  gateway run

Flags explained:

• -d: Detached mode (runs in background)
• --name hermes: Assigns a container name for easy management
• --restart unless-stopped: Auto-restarts on failure or reboot
• -p 8642:8642: Exposes the gateway API port

Verify the container is running:

docker ps | grep hermes
docker logs -f hermes

Check the health endpoint:

curl http://localhost:8642/health

Expected response: {"status":"ok"} or similar JSON.

Docker Compose for Multi-Agent Setups

For organized deployments or running multiple isolated agents, use Docker Compose. Create docker-compose.yml:

version: "3.8"
services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes
    restart: unless-stopped
    command: gateway run
    volumes:
      - ~/.hermes:/opt/data
    ports:
      - "8642:8642"
    deploy:
      resources:
        limits:
          memory: 4G
          cpus: "2.0"

Start with:

docker compose up -d

For multiple agents (e.g., work vs personal), duplicate the service block with different names, ports, and data directories:

services:
  hermes-work:
    image: nousresearch/hermes-agent:latest
    container_name: hermes-work
    volumes:
      - ~/.hermes-work:/opt/data
    ports:
      - "8642:8642"
  
  hermes-personal:
    image: nousresearch/hermes-agent:latest
    container_name: hermes-personal
    volumes:
      - ~/.hermes-personal:/opt/data
    ports:
      - "8643:8643"

Each agent maintains isolated skills, memory, and messaging channels.

Updating Docker Deployments

The update process requires careful sequencing to avoid data loss:

# Pull the new image
docker pull nousresearch/hermes-agent:latest

# Stop and remove the old container
docker stop hermes && docker rm hermes

# Start a new container with the same volume mount
docker run -d --name hermes --restart unless-stopped \
  -v ~/.hermes:/opt/data -p 8642:8642 \
  nousresearch/hermes-agent:latest gateway run

With Docker Compose:

docker compose pull
docker compose up -d

The volume mount (~/.hermes:/opt/data) preserves your data across container replacements. Without it, pulling a new image wipes accumulated skills and memories.

Installation Method 3: WSL2 on Windows

For Windows users, WSL2 (Windows Subsystem for Linux) provides a full Linux environment. Hermes Agent doesn’t run natively on Windows—WSL2 is the required path.

Enable WSL2

In PowerShell (Admin):

wsl --install

This enables the WSL feature, installs the default Ubuntu distro, and sets WSL2 as the default version. Reboot when prompted.

Install Inside WSL

Once WSL2 is running, open the Ubuntu terminal (from Start Menu) and follow the same Linux installation steps:

# Update package lists
sudo apt update

# Install Git
sudo apt install -y git

# Run the installer
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

For Docker support inside WSL2, install Docker Desktop with the WSL2 backend enabled. This allows Hermes to use Docker for sandboxed command execution while running the agent itself on the WSL2 filesystem.

Post-Installation Configuration

A working install is just the starting point. Production deployments require thoughtful configuration for security, performance, and maintainability.

API Key Management

Never hardcode credentials in skills, cron jobs, or prompt templates. The setup wizard stores keys in ~/.hermes/config.json, but for production:

• Use environment variables:

  export ANTHROPIC_API_KEY="your-key-here"
  export OPENAI_API_KEY="your-key-here"

• Integrate with a secrets manager (HashiCorp Vault, AWS Secrets Manager)
• Rotate credentials quarterly and document the procedure

Each team member should have their own API keys for audit trails and individual revocation. Shared keys are a security anti-pattern.

Security Hardening

Hermes Agent includes four built-in safety features:

1. Pairing Code System: Only approved users can interact with your agent via messaging platforms. Strangers who find your Telegram bot are ignored unless explicitly added.
2. Container Isolation: When running in Docker, command execution happens inside containers, not on your host. This is enabled by default with Docker deployments.
3. Dangerous Command Approvals: Risky operations (mass file deletions, system changes) trigger approval prompts. Always review these before confirming.
4. Skill Scanner: Community skills are automatically scanned for malicious code before installation. Still, review skill sources carefully.

Firewall Configuration

On Linux Mint 22, UFW is the default firewall. Configure it to allow only necessary traffic:

# Enable UFW if not already active
sudo ufw enable

# Allow SSH (adjust port if using non-standard)
sudo ufw allow 22/tcp

# Allow Hermes gateway port (if using external access)
sudo ufw allow 8642/tcp

# Deny all other incoming by default
sudo ufw default deny incoming

# Check status
sudo ufw status verbose

For VPS deployments, consider restricting port 8642 to specific IP ranges:

sudo ufw allow from 192.168.1.0/24 to any port 8642 proto tcp

This limits gateway access to your local network or trusted jump hosts.

SSH Hardening (VPS Deployments)

If you’re running Hermes on a remote VPS:

• Disable root login:

  sudo sed -i 's/PermitRootLogin yes/PermitRootLogin no/' /etc/ssh/sshd_config

• Use key-based authentication only:

  sudo sed -i 's/PasswordAuthentication yes/PasswordAuthentication no/' /etc/ssh/sshd_config

• Change the default SSH port (optional but effective against automated scans):

  sudo sed -i 's/#Port 22/Port 2222/' /etc/ssh/sshd_config

• Restart SSH:

  sudo systemctl restart sshd

These changes reduce your attack surface significantly. Document the new SSH port and test connectivity before closing your session.

Resource Limits and Performance Tuning

Hermes Agent is efficient, but unconstrained deployments can cause issues under load. Set resource limits based on your use case.

Memory Limits

For Docker deployments, the docker-compose.yml example above includes:

deploy:
  resources:
    limits:
      memory: 4G
      cpus: "2.0"

Adjust based on your workload:

• 2G: Basic CLI usage, single user
• 4G: Gateway + messaging + light automation
• 8G: Heavy browser automation, multiple concurrent users

Native installations don’t have built-in cgroup limits. Use systemd to constrain the service if running as a daemon:

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

[Service]
Type=simple
User=youruser
ExecStart=/home/youruser/.local/bin/hermes gateway run
MemoryLimit=4G
CPUQuota=200%
Restart=always

[Install]
WantedBy=multi-user.target

Save as /etc/systemd/system/hermes.service and enable:

sudo systemctl daemon-reload
sudo systemctl enable hermes
sudo systemctl start hermes

Disk I/O Optimization

Hermes stores memory and skills in SQLite databases under ~/.hermes. For high-throughput deployments:

• Use SSDs (obvious but worth stating)
• Consider moving ~/.hermes to a dedicated partition with noatime mount option to reduce metadata writes
• Implement log rotation to prevent unbounded growth:

  sudo apt install -y logrotate

Create /etc/logrotate.d/hermes:

~/.hermes/*.log {
    daily
    rotate 7
    compress
    missingok
    notifempty
}

Network Optimization

If you’re experiencing latency in agent responses:

• Check your LLM provider’s API status page for regional issues
• Consider using a different provider (OpenRouter aggregates 200+ models)
• For self-hosted models, ensure Ollama or similar is running on the same host to avoid network hops

Gateway connections are HTTP/1.1 by default. For high-concurrency setups, consider putting Nginx in front as a reverse proxy with connection pooling:

upstream hermes_backend {
    server 127.0.0.1:8642;
    keepalive 32;
}

server {
    listen 80;
    
    location / {
        proxy_pass http://hermes_backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_set_header Host $host;
    }
}

This configuration allows Nginx to reuse connections to the Hermes backend, reducing latency under load.

Approval Gates for Dangerous Operations

Production deployments should implement tiered approval gates to prevent accidental or malicious actions:

Configure these in your Hermes settings or via the messaging platform. The agent prompts for approval before executing Tier 2+ operations, giving you a chance to review and abort if needed.

Audit Logging

Enable structured logging for all significant actions:

hermes config set logging.level debug
hermes config set logging.format json

This outputs JSON-formatted logs to ~/.hermes/logs/. For compliance or security monitoring:

• Store logs in append-only storage (S3 with Object Lock, WORM drives)
• Retain for 30–90 days minimum
• Set up automated anomaly detection (unusual command patterns, off-hours activity)

Schedule weekly log reviews or integrate with your existing SIEM. Logs should capture: what was done, by whom, when, with what inputs, and the result.

Troubleshooting Common Issues

Even straightforward installs can fail in unexpected ways. Here are the most common issues and their fixes, drawn from real deployment experience.

Git Installation Failures

Symptom: Installer reports Could not install Git automatically

Cause: Your distro’s package manager isn’t configured or network issues prevent downloads.

Fix: Install Git manually:

# Ubuntu/Debian/Mint
sudo apt update && sudo apt install -y git

# Fedora/RHEL
sudo dnf install -y git

# Arch
sudo pacman -S git

Then re-run the installer.

Python Version Conflicts

Symptom: Python 3.11 not found errors during installation

Cause: The installer expects to provision Python 3.11 via uv, but your system has a different version or uv fails to download.

Fix: Ensure uv installed correctly:

which uv
uv --version

If missing, reinstall:

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

Then re-run the Hermes installer. The uv tool handles Python 3.11 provisioning in an isolated environment, so it won’t conflict with your system Python 3.12.

Permission Errors

Symptom: Permission denied when running hermes commands

Cause: The installer added the hermes binary to ~/.local/bin, but that directory isn’t in your PATH, or file permissions are too restrictive.

Fix: Check your PATH:

echo $PATH

If ~/.local/bin is missing, add it to your shell config (~/.bashrc or ~/.zshrc):

export PATH="$HOME/.local/bin:$PATH"

Then reload:

source ~/.bashrc

Verify the binary is executable:

ls -la ~/.local/bin/hermes
chmod +x ~/.local/bin/hermes  # if needed

Docker Volume Mount Issues

Symptom: Agent loses memory/skills after container restart

Cause: The -v ~/.hermes:/opt/data volume mount is missing or misconfigured.

Fix: Always include the volume mount when running the container. Without it, data lives inside the container and is lost on docker rm. Verify the mount:

docker inspect hermes | grep Mounts

You should see ~/.hermes mapped to /opt/data. If not, recreate the container with the correct volume flag.

Playwright/Shared Memory Errors

Symptom: Browser automation fails with shared memory errors

Cause: Playwright (used for web interactions) requires adequate shared memory allocation.

Fix: Add --shm-size=1g to your Docker run command:

docker run -d --name hermes --shm-size=1g \
  -v ~/.hermes:/opt/data -p 8642:8642 \
  nousresearch/hermes-agent:latest gateway run

For Docker Compose, add to your service:

services:
  hermes:
    shm_size: '1gb'

API Key Authentication Failures

Symptom: Agent can’t connect to LLM provider, returns 401 errors

Cause: API key is incorrect, expired, or not properly configured.

Fix: Re-run the setup wizard:

hermes setup

Or manually edit ~/.hermes/config.json (ensure file permissions are 600):

{
  "provider": "anthropic",
  "api_key": "your-actual-key-here"
}

Verify the key works independently:

curl -H "Authorization: Bearer your-key-here" \
  https://api.anthropic.com/v1/models

If this fails, the issue is with your API key, not Hermes. Contact your provider.

Network Connectivity Issues

Symptom: Installer or agent can’t reach external APIs

Cause: Firewall, proxy, or DNS issues blocking outbound HTTPS.

Fix: Test connectivity:

curl -I https://api.anthropic.com
curl -I https://github.com

If these fail, check your firewall:

sudo ufw status
sudo ufw allow out 443/tcp

For corporate proxies, set environment variables:

export HTTPS_PROXY="http://proxy.example.com:8080"
export HTTP_PROXY="http://proxy.example.com:8080"

Add these to your shell config for persistence.

High Memory Usage

Symptom: Agent consumes excessive RAM, especially with browser automation

Cause: Playwright browsers and model contexts aren’t bounded.

Fix: Implement resource limits as shown in the Docker Compose example above. For native installs, use systemd cgroup limits or run the agent inside a container even if you prefer native CLI usage. Monitor memory with:

docker stats hermes
# or for native
ps aux | grep hermes

If memory consistently exceeds your limits, consider:

• Reducing concurrent browser sessions
• Using smaller model context windows
• Implementing session timeouts for idle connections

Performance Optimization Strategies

Beyond basic installation, several strategies improve Hermes Agent performance in production environments.

Model Selection and Caching

Choose models based on your use case:

• Fast, cheap: Claude 3 Haiku, GPT-4o-mini for routine tasks
• Balanced: Claude 3.5 Sonnet, GPT-4o for general automation
• Heavy reasoning: Claude 3 Opus, GPT-4 Turbo for complex tasks

Hermes supports 200+ models via OpenRouter, letting you switch providers without changing your setup. Test different models and track token usage to optimize costs.

For repeated queries, implement caching at the application layer. Hermes doesn’t cache API responses by default—consider adding a Redis layer or using provider-specific caching features where available.

Concurrency Tuning

Default concurrency settings work for single users but bottleneck under load. Adjust based on your workload:

hermes config set gateway.max_connections 50
hermes config set gateway.timeout 120

For Docker deployments, scale horizontally by running multiple containers behind a load balancer:

services:
  hermes-1:
    image: nousresearch/hermes-agent:latest
    volumes:
      - ~/.hermes-1:/opt/data
    ports:
      - "8642:8642"
  
  hermes-2:
    image: nousresearch/hermes-agent:latest
    volumes:
      - ~/.hermes-2:/opt/data
    ports:
      - "8643:8643"

Use Nginx or HAProxy to distribute traffic across instances. Each instance maintains isolated state, so this works well for multi-tenant setups.

Monitoring and Alerting

Set up monitoring to catch issues before users report them:

• Health checks: curl http://localhost:8642/health every minute
• Log aggregation: Ship logs to ELK, Loki, or similar
• Metrics: Export Prometheus metrics if available, or parse logs for error rates
• Alerts: Configure PagerDuty, Slack, or email notifications for:
  • API errors exceeding threshold
  • Memory usage above 80%
  • Unusual command patterns (bulk deletions, off-hours activity)

For simple setups, a cron job that checks health and sends alerts is sufficient:

#!/bin/bash
if ! curl -s http://localhost:8642/health | grep -q '"status":"ok"'; then
    echo "Hermes health check failed" | mail -s "ALERT: Hermes Down" admin@example.com
fi

Add to crontab:

* * * * * /path/to/health-check.sh

Best Practices for Production Deployments

Production Hermes Agent deployments differ from local testing in critical ways. Follow these practices to avoid common pitfalls.

Isolation and Sandboxing

• Always use Docker for command execution unless you explicitly need host access. Container isolation prevents accidental system damage.
• Run Hermes as a non-root user with minimal permissions. Never run as root on production systems.
• Use dedicated accounts for integrations (email, CRM, databases). Don’t use your personal Gmail or primary database credentials.

Credential Management

• Never store secrets in version control. Add ~/.hermes/ to your .gitignore.
• Use environment variables or secrets managers for API keys, not config files.
• Rotate credentials quarterly and document the procedure. Automate where possible.
• Implement least-privilege access for every connector. Read-only Gmail scope, SELECT-only database roles, scoped API keys with explicit boundaries.

Backup and Recovery

• Back up ~/.hermes regularly. This directory contains all your agent’s memory, skills, and config.
• Test restoration procedures quarterly. A backup you can’t restore isn’t a backup.
• Version your config files (excluding secrets) for audit trails and rollback capability.

Example backup script:

#!/bin/bash
BACKUP_DIR="/backups/hermes"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
tar -czf "$BACKUP_DIR/hermes_$TIMESTAMP.tar.gz" ~/.hermes
find "$BACKUP_DIR" -name "hermes_*.tar.gz" -mtime +30 -delete

Schedule via cron:

0 2 * * * /path/to/backup-hermes.sh

This runs daily at 2 AM and retains 30 days of backups.

Security Monitoring

• Review audit logs weekly for anomalous patterns
• Set up alerts for dangerous operations (Tier 3 approvals, bulk changes)
• Scan community skills before installation using the built-in skill scanner
• Implement network segmentation for VPS deployments—run Hermes in a DMZ or isolated subnet

Update Management

• Test updates in staging before deploying to production
• Read release notes for breaking changes or security patches
• Maintain rollback capability by keeping the previous Docker image version
• Schedule updates during low-traffic periods to minimize disruption

For Docker:

# Keep the previous image tagged
docker tag nousresearch/hermes-agent:latest nousresearch/hermes-agent:previous

# Pull new version
docker pull nousresearch/hermes-agent:latest

# Deploy and monitor
docker compose up -d

# Rollback if needed
docker tag nousresearch/hermes-agent:latest nousresearch/hermes-agent:failed
docker tag nousresearch/hermes-agent:previous nousresearch/hermes-agent:latest
docker compose up -d

This approach gives you a quick rollback path if issues arise.