Deploying Hermes Agent on a Linux VPS Печать

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

This guide installs Hermes on an ArkHost Linux VPS running Debian 13, under a dedicated Linux account. The AI model runs at your chosen provider. Telegram uses outbound polling, so you do not need to expose a dashboard or open a public web port.

Choose a current VPS plan

For this setup, we recommend VPS XS: 2 vCPU, 4 GiB RAM and 50 GiB NVMe. This is a starting recommendation for one assistant using a remote model, not a guaranteed capacity limit.

• VPS Nano: 1 vCPU, 2 GiB RAM and 25 GiB NVMe. Consider it only for light use without local browser automation or other heavy services. Monitor memory and disk use.
• VPS XS: our suggested starting point for the Telegram assistant described here.
• VPS SM: 4 vCPU, 8 GiB RAM and 100 GiB NVMe. Consider more headroom if you add browser automation, parallel tasks or containers.

Check the current Linux VPS plans and prices before ordering. These plans are hosted in Stockholm, Sweden. Model subscriptions and API usage are separate from the VPS price. Hosting a large model locally has different hardware requirements and is outside this guide.

Before you start

• Use a fresh Debian VPS with administrative SSH access.
• Open the VPS browser console from your ArkHost Client Area and confirm you can log in. Keep your SSH session open while testing changes.
• Have an account with a supported model provider and a Telegram account.

Prepare Debian

Run these commands as root on the VPS. They update packages and install the basic dependencies:

apt update
apt upgrade
apt install ca-certificates curl git xz-utils

Create an unprivileged account and enable its user services to run after logout and at boot:

adduser --disabled-password --gecos "" hermes
loginctl enable-linger hermes

Do not give this account unrestricted sudo access. Keep system administration separate from the agent.

Before enabling a firewall, allow your actual SSH port and test a new connection. Do not install a second firewall manager over an existing one. See the UFW guide for Debian and Ubuntu.

Install Hermes

Switch to the dedicated account. Run the rest of the Hermes commands as this user, not as root:

su - hermes

Use the official installer. This basic Telegram setup skips local browser and desktop-control dependencies; you can add them later if needed:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --skip-browser --skip-computer-use
source ~/.bashrc
command -v hermes
hermes --version

The installer creates the Python environment and launcher. If you later enable local browser automation, follow the official installation guide for the system libraries an administrator must install. Do not grant the agent unrestricted sudo just to install a browser.

Connect a model provider

hermes setup

Choose a supported provider for your account, such as Nous Portal, OpenAI Codex or an API-key provider. Follow its login flow. Availability and billing depend on that provider; the VPS does not include model access.

Choose a current model with tool support. Avoid copying an old model ID from a tutorial. If using an API key, create a separate key and set a spending limit where the provider supports one.

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

Resolve authentication or quota errors before setting up Telegram. Use hermes model to change provider or model.

Create a private Telegram bot

1. Message @BotFather in Telegram and send /newbot.
2. Choose a name and a username ending in bot.
3. Keep the bot token private. Enter it only in the setup wizard, not in a conversation with an assistant.
4. For a personal bot, use BotFather's /setjoingroups command to disable group joins.
5. Get your numeric Telegram user ID from @userinfobot. A username is not a numeric user ID.

In the VPS terminal, still as the hermes user:

hermes gateway setup

Select Telegram, enter the bot token and allow only your numeric user ID. Hermes denies users who are neither allowlisted nor approved through pairing by default. Do not enable allow-all access for an agent with tools. Telegram group privacy mode is separate from Hermes authorization.

Run the gateway as a service

A shell opened through su may not inherit the user-service environment. Set it explicitly for this account:

export XDG_RUNTIME_DIR="/run/user/$(id -u)"
export DBUS_SESSION_BUS_ADDRESS="unix:path=$XDG_RUNTIME_DIR/bus"
systemctl --user is-system-running

If this reports a bus connection error, stop here and check that lingering was enabled for hermes from the root session. A reachable manager reporting degraded instead needs its failed units inspected.

Install and start the gateway:

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

Open the bot in Telegram, press Start and send a message. Then try a read-only task such as asking for disk usage. If it does not reply, inspect the service:

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

Only one gateway should poll this bot token. Running the same bot on two machines can cause polling conflicts.

Limit access

Hermes stores credentials in ~/.hermes/.env and its credential stores, and ordinary settings in ~/.hermes/config.yaml. Use the supported configuration commands:

hermes config set approvals.mode smart
hermes tools
hermes skills config

Keep only the tools you need enabled. Command approvals help review risky actions, but they are not a sandbox. The agent can access files and commands available to its Linux account. Keep unrelated customer data, root credentials and production keys out of that account.

Back up and update

Create a full Hermes backup before major changes:

umask 077
hermes backup --keep 0

The backup contains credentials and conversation data. Transfer it to encrypted off-server storage and restrict access. Back up project files and other data outside the Hermes directory separately. A VPS backup does not replace an independent copy.

Check and install updates from your SSH terminal:

hermes update --check
hermes update
hermes config check
hermes doctor
hermes gateway status

Allow for a gateway restart during updates. Send a new Telegram message afterwards to verify the bot is responding.

Troubleshooting

• Command not found: reload the shell with source ~/.bashrc and check command -v hermes.
• CLI works but Telegram does not: check gateway status, the bot token, your numeric allowlist entry and the logs.
• Stops after logout or reboot: check loginctl show-user hermes -p Linger and the gateway service status.
• Authentication or quota error: use hermes model and check the model provider account.
• Memory or disk pressure: inspect the actual processes, session sizes and stored files. Remove unnecessary services and contact support if you need a larger VPS. Package upgrades are not self-service.

Start with this single-server setup. Add browser automation, scheduled jobs and other integrations only after the basic assistant works.

Official documentation

• Installation
• Telegram setup
• Gateway services
• Security