Deploying Hermes Agent on a Linux VPS Afdrukken

Hermes Agent is an open-source AI agent by Nous Research. It can run commands, work with files, browse the web, remember preferences, schedule tasks, and respond through messaging platforms such as Telegram.

This guide installs Hermes on an ArkHost KVM VPS running Debian 13. Hermes runs continuously under a dedicated Linux user and connects to Telegram without exposing a public web port.

What you need

• An ArkHost Linux VPS with Debian 13. One CPU, 3 GB RAM, and 40 GB storage is enough for a normal remote-model setup. Choose more memory if you plan to run databases, browser automation, or other local services on the same VPS.
• SSH access as root or another administrative user.
• Access to a supported AI model provider. Hermes supports Nous Portal, OpenAI Codex, OpenRouter, Anthropic, Google, local OpenAI-compatible endpoints, and other providers.
• A Telegram account if you want to use Hermes from your phone.

Prepare the server

Connect over SSH and update Debian:

apt update && apt upgrade -y
apt install -y ca-certificates curl git ufw fail2ban

Create a dedicated user for Hermes:

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

Do not give this account unrestricted sudo access. If Hermes later needs one administrative command, grant only that command through a narrow sudo rule.

Configure the firewall. Replace YOUR_TRUSTED_IP with the public IP used for SSH:

ufw default deny incoming
ufw default allow outgoing
ufw allow from YOUR_TRUSTED_IP to any port 22 proto tcp
ufw enable

If your SSH address changes regularly, use ufw allow 22/tcp instead. Confirm that a second SSH session works before closing the first one.

Enable fail2ban:

systemctl enable --now fail2ban

Allow the Hermes user service to keep running after logout:

loginctl enable-linger hermes

Install Hermes Agent

Switch to the dedicated account:

su - hermes

Run the official installer:

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

The installer downloads Hermes, installs its Python environment, and adds the hermes command to your shell. You do not need to install Python packages or uv separately.

Verify the installation:

command -v hermes
hermes --version
hermes doctor

Choose a model provider

Start the setup wizard:

hermes setup

Choose the setup path and provider that match your account. Common options include:

• Nous Portal: OAuth login with access to hosted models and managed tools.
• OpenAI Codex: device-code login using a compatible ChatGPT or Codex account.
• OpenRouter: one API key with access to models from several providers.
• Custom endpoint: an OpenAI-compatible model server you operate yourself.

If you use an API key, create a dedicated key for Hermes and set a spending limit at the provider. Do not reuse a key shared with unrelated applications.

Model names change frequently. Select a current model that supports tool calling and has enough context for agent work instead of copying a model ID from an old guide.

Test a normal chat before adding Telegram:

hermes chat -q "Reply with: Hermes is working"

If this fails, fix the provider configuration first. Run hermes model to change provider or model, then use hermes doctor to check the installation.

Create a Telegram bot

Open Telegram and message @BotFather:

1. Send /newbot.
2. Choose a display name and a username ending in bot.
3. Copy the bot token. Store it as a credential and never paste it into a normal chat.
4. Send /setjoingroups, select the bot, and choose Disable if this is a private assistant.

Telegram privacy mode controls which messages a bot can read inside groups. It does not restrict a bot to direct messages. Disabling group joins and configuring the Hermes user allowlist provide that restriction.

Get your numeric Telegram user ID from @userinfobot or another trusted ID lookup bot.

Connect Telegram to Hermes

Run the gateway setup wizard as the hermes user:

hermes gateway setup

Select Telegram, enter the bot token, and add your numeric user ID to the allowlist. The wizard stores credentials in ~/.hermes/.env and normal settings in ~/.hermes/config.yaml.

The allowlist matters. Without an allowlist or another configured authorization method, an unknown Telegram user could reach an agent that has access to files and tools on the VPS.

Install the gateway service

Install and start the gateway as a systemd user service:

hermes gateway install --start-now --start-on-login
hermes gateway status

The status should show a running gateway. Open Telegram, find the bot, and send:

hello

Test a harmless tool call:

What is the current disk usage on this server?

If the bot does not answer, inspect the gateway and recent logs:

hermes gateway status
journalctl --user -u hermes-gateway -n 100 --no-pager

Apply safe server defaults

Hermes stores secrets in ~/.hermes/.env and normal settings in ~/.hermes/config.yaml. Use hermes config set instead of editing YAML by hand.

Keep dangerous-command approvals in the default smart mode:

hermes config set approvals.mode smart

Enable the hard stop for repeated tool failures. This prevents an unattended gateway task from repeating the same failed action until it reaches the full iteration limit:

hermes config set tool_loop_guardrails.hard_stop_enabled true

Hermes includes secret redaction, command approval checks, and Tirith command scanning. Tirith is resolved from the system path or the Hermes home directory and can be installed automatically. Check the full security state with:

hermes doctor

Do not switch approval mode off on a persistent server. Do not paste passwords, private keys, bot tokens, or API keys into conversations. Redaction reduces accidental exposure but does not replace proper credential handling.

Restart the gateway after configuration changes that do not reload automatically:

hermes gateway restart

Choose which skills and tools to load

Hermes supports skills for development, infrastructure, research, documents, media, and other work. Enable only the skills relevant to your use:

hermes skills config

Disabled skills remain installed and can be enabled later. Toolsets can be reviewed separately with:

hermes tools

Add integrations one at a time. Verify the base chat and Telegram gateway before configuring cron jobs, MCP servers, browser automation, or extra messaging platforms.

Back up Hermes

The ~/.hermes/ directory contains configuration, OAuth credentials, sessions, skills, scheduled jobs, and memory data. Back it up before major updates or configuration work:

tar --exclude='.hermes/cache' --exclude='.hermes/logs' \
  -czf "$HOME/hermes-backup-$(date +%F).tar.gz" \
  -C "$HOME" .hermes
chmod 600 "$HOME"/hermes-backup-*.tar.gz

The archive contains credentials. Store it in encrypted off-server storage and apply the same access controls used for other secrets.

Keep Hermes updated

Check for an update:

hermes update --check

Install the update:

hermes update
hermes config check
hermes doctor
hermes gateway status

Hermes creates a pre-update state snapshot by default. A separate off-server backup is still recommended because a local snapshot does not protect against VPS or disk loss.

Common problems

• hermes: command not found: run source ~/.bashrc, then check command -v hermes.
• The CLI works but Telegram does not: run hermes gateway status and check the gateway logs. Verify the bot token and numeric allowlist entry.
• The bot stops after logout or reboot: verify that lingering is enabled with loginctl show-user hermes -p Linger, then reinstall or restart the gateway service.
• The model returns authentication or quota errors: run hermes model and check the provider account, API key, subscription, or spending limit.
• A configuration change breaks startup: run hermes config check and hermes doctor. Restore the last backup if the configuration was edited manually.
• A long conversation becomes slow or consumes too much context: start a fresh session with /new. Persistent memory and saved skills are separate from the active conversation.
• Memory usage keeps growing: inspect the running process and session size before increasing the VPS. Restarting the gateway clears process memory but does not fix a repeatedly oversized workflow.

Useful next steps

• Create an AGENTS.md file inside each project with its build, test, style, and safety rules.
• Clone repositories into directories owned by the hermes user. Ask Hermes to create a branch and show the diff for review before any commit or push.
• Add scheduled jobs for certificate expiry, backups, disk usage, or service health after interactive checks work reliably.
• Configure another messaging platform through hermes gateway setup if Telegram is not suitable.
• Review terminal permissions before giving Hermes access to another server. Prefer a dedicated account with narrowly scoped commands over root SSH access.

Optional split-service setup

The basic installation uses the model provider for inference and keeps Hermes itself on one VPS. This is the simplest setup and fits the entry VPS tier.

Heavier helper services can run on a second VPS when needed. Examples include web search, webpage extraction, browser rendering, OCR, speech processing, and a database-backed memory service. Keep these services on a private network or WireGuard tunnel and do not publish their database or queue ports to the internet.

Separating helper services keeps scraping and database workloads away from the Telegram gateway. It also lets you resize the helper VPS without moving the Hermes runtime.

Further reading

• Hermes Agent quickstart
• Installation guide
• Configuration reference
• Security reference
• FAQ and troubleshooting