Installing Hermes Agent on BinaryLane

Deploy Hermes Agent, Nous Research's open-source self-improving AI agent, on Ubuntu in under 15 minutes. Hermes connects to Telegram, Discord, Slack, WhatsApp, Signal, and email with persistent memory, reusable skills, and cron automation.

Note: This article was written and tested by actually deploying Hermes Agent on a BinaryLane VPS end-to-end - installer, configuration, and the gateway service were all verified live. All commands and steps have been reviewed against the current Hermes Agent CLI and documentation as of August 2026.

⚠️ Unsupported Software: Hermes Agent is third-party software developed by Nous Research, not developed or maintained by BinaryLane. While we provide this guide to help you get started, BinaryLane Support cannot assist with Hermes configuration, troubleshooting, or usage. For Hermes-specific help, please refer to the Hermes Agent Documentation or GitHub repository.

TABLE OF CONTENTS

• What is Hermes Agent?
• Security Considerations
• Prerequisites
• Deployment Methods
  • Method 1: BinaryLane CLI (Recommended)
  • Method 2: BinaryLane API
  • Method 3: Manual Installation
• Configuration
  • AI Provider Setup
  • Connecting Messaging Platforms
• Managing Your Installation
• Security & Sandboxing
• Troubleshooting
• Additional Resources

What is Hermes Agent?

Hermes Agent is an open-source, self-improving AI agent from Nous Research that runs on your own server. It provides:

• Persistent memory - remembers your preferences, projects, and environment across sessions
• Self-improving skills - autonomously creates and refines reusable skills after complex tasks
• Multi-platform support - Telegram, Discord, Slack, WhatsApp, Signal, email, and CLI through a single gateway process
• Provider flexibility - switch between Anthropic, OpenAI, Google, OpenRouter, Nous Portal (300+ models), or a custom endpoint without code changes
• Cron & automation - schedule recurring agent tasks

Licensed under MIT. Official repository: github.com/nousresearch/hermes-agent.

Hermes Desktop: Nous Research also ships a native desktop app for macOS, Windows, and Linux, for anyone who'd rather run Hermes locally instead of self-hosting it on a VPS. Download it from hermes-agent.nousresearch.com - or, if the CLI is already installed, just run hermes desktop.

Security Considerations

⚠️ Important: By default Hermes runs its terminal/file tools directly on the host (terminal.backend: local in config.yaml) - it has full system access, the same as OpenClaw or any other host-mode agent. Treat this server as a high-value target.

Recommended security measures for a public-facing Hermes host:

• Sandbox the agent: Set terminal.backend to docker or ssh in ~/.hermes/config.yaml to run tool calls inside an isolated container/remote host instead of directly on the VPS. Optionally enable the egress credential-injection proxy (hermes egress setup && hermes egress start) so a sandboxed agent never sees your real API keys.
• SSH: Use key-based authentication only (Ed25519 or RSA 4096-bit), disable root login
• External Firewall: If you're connecting from a static IP address, use the External Firewall to whitelist only your IP address for SSH (port 22)
• Secrets: API keys live in ~/.hermes/.env - store a backup in a password vault, never in version control
• Network: Consider deploying inside a VPC, or use a VPN/WireGuard for additional access control
• Updates: Keep the system patched and consider unattended-upgrades + fail2ban

Harden the server: Don't stop at the steps above - see Securing Your Servers for general BinaryLane hardening guidance. You could also consider deploying on a CIS Hardened Image instead of stock Ubuntu for a pre-hardened baseline.

Prerequisites

⭐ = Recommended

Deployment Methods

Method 1: BinaryLane CLI (Recommended)

The fastest way to deploy Hermes - using the BinaryLane CLI with cloud-init to automatically install Hermes on first boot.

Step 1: Install the BinaryLane CLI

pip install binarylane-cli

Step 2: Configure Authentication

Create an API token from the BinaryLane Dashboard → Developer API → Create Token, then:

bl configure

Verify with bl account get

Step 3: Get Your SSH Key ID

bl ssh-key list

If you don't have one registered:

bl ssh-key create --name "My Key" --public-key "ssh-rsa AAAA..."

Step 4: Create the Cloud-Init Script

Save this as hermes-init.yaml:

#cloud-config
package_update: true
package_upgrade: true

runcmd:
  # Disable interactive prompts
  - export DEBIAN_FRONTEND=noninteractive

  # Refresh package lists first - without this, the Hermes
  # installer's ripgrep/ffmpeg step silently fails on a fresh image
  - apt-get update

  # Install Hermes Agent (installer handles Python, Node, uv, etc.)
  - curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

This installs Hermes and all its dependencies automatically on first boot (typically 5–8 minutes, depending on package mirrors - most of that time is downloading the bundled Playwright Chromium browser for web tools).

Step 5: Deploy the Server

bl server create \
  --name hermes \
  --region syd \
  --image ubuntu-24.04 \
  --size std-1vcpu \
  --ssh-keys YOUR_SSH_KEY_ID \
  --user-data "$(cat hermes-init.yaml)"

Step 6: Get Your Server IP

bl server list

Wait for status to show active. Cloud-init will run automatically on first boot.

Step 7: Configure and Start the Gateway

SSH in and configure your AI provider (avoid pasting a real API key into cloud-init - do this step interactively instead):

ssh root@YOUR_SERVER_IP
hermes setup

Or configure non-interactively:

hermes config set model anthropic/claude-sonnet-5
hermes config set ANTHROPIC_API_KEY your-api-key-here

Then install and start the gateway as a persistent service:

hermes gateway setup    # interactive: connect Telegram/Discord/Slack/etc.
hermes gateway install  # creates + enables a systemd --user service

Verified: hermes gateway install automatically runs loginctl enable-linger for you, so the gateway keeps running after you log out of SSH - no extra steps needed.

Tip: If cloud-init is still running, check progress with: tail -f /var/log/cloud-init-output.log

Available Regions

Available Sizes
⭐ = Recommended

*Pricing as of August 2026, subject to change

If you find the performance insufficient for your use case (e.g. running the Docker sandbox backend, or several concurrent sessions), you can upgrade your server via the Change Plan page in the BinaryLane Dashboard at any time, subject to resource availability.

Method 2: BinaryLane API

Deploy directly via the REST API with the same cloud-init script for automatic installation.

Get Your SSH Key ID

curl -s --request GET \
  'https://api.binarylane.com.au/v2/account/keys' \
  --header 'Authorization: Bearer YOUR_API_TOKEN'

Create Server with Cloud-Init

curl --request POST \
  'https://api.binarylane.com.au/v2/servers' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "hermes",
    "region": "syd",
    "image": "ubuntu-24.04",
    "size": "std-1vcpu",
    "ssh_keys": [YOUR_SSH_KEY_ID],
    "user_data": "#cloud-config\npackage_update: true\npackage_upgrade: true\n\nruncmd:\n  - export DEBIAN_FRONTEND=noninteractive\n  - apt-get update\n  - curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash"
  }'

Once the server is active, SSH in and run hermes setup (or hermes config set ...) followed by hermes gateway setup && hermes gateway install to complete setup.

Get Server IP

curl -s --request GET \
  'https://api.binarylane.com.au/v2/servers' \
  --header 'Authorization: Bearer YOUR_API_TOKEN'

Full API Reference: api.binarylane.com.au/reference

Method 3: Manual Installation

For users who prefer step-by-step control or are installing on an existing server.

1. Create a VPS via the BinaryLane Dashboard with Ubuntu 24.04 LTS.

   
   

2. SSH into your server:

   ssh root@YOUR_SERVER_IP

   
   

3. Update system packages:

   apt update && apt upgrade -y

   Don't skip this step - on a fresh image the Hermes installer's automatic ripgrep/ffmpeg install silently fails without a prior apt update (it falls back to a slower grep-based search and disables TTS voice messages).

   
   

4. Install Hermes Agent:

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

   The installer handles Python 3.11, Node.js 22, uv, ripgrep, ffmpeg, and Playwright's bundled Chromium automatically. On a std-1vcpu server this takes 5–8 minutes and uses about 6GB of disk.

   
   

5. Run the setup wizard:

   hermes setup

   
   

6. Connect messaging platforms and install the gateway service:

   hermes gateway setup
   hermes gateway install

   
   

Configuration

AI Provider Setup

Hermes ships with anthropic/claude-opus-4.6 configured against an OpenRouter base URL by default - you'll need to set your own model and credentials. Supported providers include:

⚠️ Minimum context requirement: Hermes requires a model with at least 64,000 tokens of context. Smaller-context models are rejected at startup - they can't hold enough working memory for multi-step tool calling.

To set your model and key non-interactively (verified working):

hermes config set model anthropic/claude-sonnet-5
hermes config set ANTHROPIC_API_KEY your-api-key-here

Non-secret settings go to ~/.hermes/config.yaml; secrets go to ~/.hermes/.env automatically.

Connecting Messaging Platforms

hermes gateway setup

This interactive wizard walks you through connecting Telegram, Discord, Slack, WhatsApp, Signal, email, Home Assistant, or Teams - one gateway process serves all connected platforms.

Fail-closed by default: until you configure a platform allowlist (e.g. TELEGRAM_ALLOWED_USERS=your_id) or set GATEWAY_ALLOW_ALL_USERS=true, the gateway denies messages from unrecognized senders on every connected platform.

Managing Your Installation

Note: The gateway runs as a systemd --user service. hermes gateway install automatically enables systemd lingering, so it keeps running after your SSH session ends - no manual loginctl step required.

Check Status:

hermes gateway status
hermes doctor

Service Commands:

# Check service status
systemctl --user status hermes-gateway

# View live logs
journalctl --user -u hermes-gateway -f

# Restart the gateway (also refreshes an outdated unit file)
hermes gateway restart

# Stop / start
hermes gateway stop
hermes gateway start

Update Hermes:

hermes update

This pulls the latest code, re-installs dependencies, migrates your config, and restarts the gateway automatically. Preview what would change first with hermes update --check.

Test the Agent:

hermes

Starts an interactive chat session in the terminal. Use hermes --continue (or -c) to resume your last session.

Security & Sandboxing

Unlike some self-hosted AI gateways, a fresh Hermes install does not open any network port - the gateway only makes outbound connections to messaging platform APIs. There's no local dashboard or API port to lock behind a reverse proxy.

The main exposure to manage instead is the agent's own system access. By default, tool calls (shell, file operations) run directly on the host. To sandbox them:

# In ~/.hermes/config.yaml
terminal:
  backend: "docker"   # or "ssh" to run tools on a separate remote host

For further isolation, the egress credential-injection proxy keeps your real API keys off the sandbox entirely - the sandbox only sees opaque proxy tokens:

hermes egress setup
hermes egress start

Troubleshooting

Additional Resources

• Hermes Agent Documentation
• Hermes Agent GitHub Repository
• BinaryLane CLI Documentation
• BinaryLane API Reference

If you require assistance with BinaryLane services, feel free to submit a support ticket at our helpdesk here: Submit a ticket | BinaryLane