Secure Self-Hosted Hermes

Use a mainstream VPS provider and a current Ubuntu LTS image.

Recommended baseline:

Reasonable providers include Hetzner, DigitalOcean, Vultr, and Linode. A Hetzner CPX31/CPX32-class instance is a practical starting point for personal agent workflows.

Do not start with the cheapest box. Hermes is not the only workload. You may also run Docker containers, Syncthing, logs, browsers, Python tooling, and generated artifacts.

Create an SSH keypair on your laptop. Upload only the public key to the VPS provider.

Laptop/Mac
  private key: stays local
  public key: uploaded to VPS provider

Use SSH keys from the start when possible. If password SSH is used during bootstrap, disable it after confirming key-based admin access.

Create two users:

This separation matters. If someone abuses Hermes or a tool runtime, the next step should not be sudo.

The hermes user should own the Hermes install and its working directories. The admin user should handle package installation, firewall changes, system upgrades, and recovery tasks.

At minimum:

• disable root login;
• disable password login;
• keep public-key auth enabled;
• keep a tested admin SSH session open while changing settings;
• only then reload or restart SSH.

SSH hardening can lock you out. Take a VPS snapshot before and after this phase if your provider supports it.

Start with UFW:

The final goal is stricter: SSH should only be reachable over Tailscale, not from the public internet.

That means there are two phases:

1. Bootstrap phase: public SSH is temporarily allowed so you can set up the machine.
2. Private phase: after Tailscale works, public SSH is closed and administration happens over the 100.x.x.x Tailscale address.

Do not close public SSH until you have tested Tailscale SSH access from your laptop.

Tailscale gives you a private network without your own VPN server. For this setup, it keeps dashboards, admin ports, and SSH off the public internet.

After Tailscale is installed and the VPS appears in your tailnet:

• test SSH to the VPS Tailscale IP;
• confirm you can administer the server through that route;
• update UFW so public SSH is no longer open;
• keep Hermes dashboard/admin access private as well.

Use this mental model:

Hermes can run terminal/file/code execution through different backends. For a security-conscious VPS, prefer:

yamlterminal:
  backend: docker

Avoid using a direct local shell backend for normal agent work on a server. Docker is not a magic shield, but it creates a boundary between agent tool execution and the host operating system.

This isolates common tool actions such as:

• shell commands;
• Python scripts;
• Node tooling;
• file writes;
• package experiments.

You will not make compromise impossible. You can stop routine agent work from getting the same access as the server operator.

Install Hermes as the restricted hermes user.

Recommended location:

/home/hermes

Useful verification commands after installation:

bashhermes version
hermes doctor
hermes config path
hermes config env-path

Use the public Hermes installer endpoint:

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

Then run the setup wizard:

bashhermes setup

For provider authentication, use the current Hermes docs and the hermes setup, hermes model, and hermes auth flows. Do not hardcode stale model-provider assumptions.

Model choice affects quality, cost, latency, and context. It will not fix a bad server architecture.

Hermes supports both OAuth/subscription-backed providers and API-key-backed providers. Some advanced tooling, external evaluation frameworks, and optimization systems may require direct API keys even if normal Hermes usage works through OAuth.

Use lighter daily models for normal operation and stronger models for deep work. Treat the model as one layer. Your security posture comes from:

• private networking;
• OS hardening;
• containerized tool execution;
• secrets isolation;
• Telegram allowlisting;
• approval policies;
• controlled filesystem mounts.

For operational resilience, configure fallback providers in config.yaml, not .env:

yamlfallback_providers:
  - provider: openrouter
    model: <fallback-model-name>

Choose a model currently supported by your provider. Use fallbacks for outages, rate limits, or cost control, and test them before you depend on them during a long research run.

Hermes documentation separates configuration from secrets:

~/.hermes/config.yaml  → normal settings
~/.hermes/.env         → API keys, bot tokens, secrets

That split matters. The tool container should not inherit your whole environment.

Use a tighter posture:

yamlterminal:
  backend: docker
  env_passthrough: []
  docker_forward_env: []

Forward only the variables a workflow needs. If a tool needs a GitHub token, add it on purpose. Do not forward your whole shell environment into an AI-controlled runtime.

Do not mount the host root filesystem into the tool container.

Avoid mounting:

/
/home/hermes
/var/run/docker.sock

Especially avoid the Docker socket. Mounting /var/run/docker.sock usually means the container can control Docker on the host. That can become host-level control.

Prefer a small, intentional artifact mount:

yamlterminal:
  backend: docker
  docker_mount_cwd_to_workspace: false
  docker_forward_env: []
  env_passthrough: []
  docker_volumes:
    - "/home/hermes/output:/output"

Then tell Hermes to write generated files to /output. Any dedicated folder can work. Mount that folder, not the whole home directory. The exact host path is not important. The rule is simple: mount only a dedicated artifacts directory into /output, not the entire home directory.

If Docker writes files as root, your sync tools and editor will complain.

Use Hermes Docker settings so generated files are owned by the host user where possible:

yamlterminal:
  docker_run_as_host_user: true

Use docker_run_as_host_user: true when writing to a synced /output folder, so generated files are owned by the hermes user instead of root. This improves file sync and permissions, but it is not a standalone security control. It should still be paired with narrow mounts and no secret passthrough. Root-owned markdown files do not improve security. They create maintenance work.

Create a bot through BotFather and keep the token secret. If it leaks, revoke it.

Hermes Telegram setup can be handled interactively:

bashhermes gateway setup

For manual .env configuration:

envTELEGRAM_BOT_TOKEN=<your-bot-token>
TELEGRAM_ALLOWED_USERS=<your-numeric-telegram-id>

Do not use an allow-all configuration for a private AI agent. Telegram is the front door. Lock it.

If the bot is added to groups, also pay attention to:

• group allowlists;
• privacy mode;
• whether the bot sees all messages or only mentions;
• whether group context is being observed without auto-replying.

The desired gateway posture is default-deny: only explicitly allowed users or paired users should be able to interact with the agent.

The default private deployment should begin with one user ID: yours. For groups, use group allowlists separately and do not assume a private-user allowlist protects group chats automatically.

Allowlisting controls who can reach the bot. It does not mean every allowed user should get every command.

For shared bots, separate:

admin users
regular allowed users
allowed slash commands

Use limited command exposure for non-admin users. Do not assume "allowlisted" means "safe to give full tool access."

For shared bots, configure allow_admin_from and user_allowed_commands so regular users only get specific slash commands. For groups, use the group equivalents: group_allow_admin_from and group_user_allowed_commands.

A Telegram assistant needs to survive logout and SSH disconnects.

Use Hermes gateway service commands:

bashhermes gateway install
hermes gateway start
hermes gateway status

If you are using a user-level service on Linux, make sure the service can survive logout when required. On systemd systems that may involve enabling linger for the service user.

Then check the service and logs:

bashhermes gateway status
journalctl --user -u hermes-gateway -n 120 --no-pager
sudo systemctl status syncthing-hermes
sudo ufw status verbose

If the gateway is not installed as a systemd user service, check the Hermes log file instead:

bashtail -n 100 ~/.hermes/logs/gateway.log

Do not expose every Hermes tool to every interface by default. A Telegram bot, Discord bot, desktop app, and terminal session do not need the same tool surface.

Run hermes tools to configure individual tool availability per platform. Hermes persists those choices to config.yaml, so this is finer-grained than only enabling or disabling broad toolsets.

Start with a small surface:

• chat and research tools;
• file write access only to /output;
• browser and web tools only when a workflow needs them;
• no unnecessary messaging or admin integrations;
• no production cloud tools;
• no main email or GitHub write access at first.

Treat each new tool as another attack surface. Docker isolation helps, but it does not make a powerful tool safe on every platform.

Treat MCP servers and external tool integrations like privileged plugins. Do not add MCP servers casually. Review what tools they expose, what credentials they need, and whether they can access local files, network services, or secrets.

Delay sensitive integrations on day one:

• main Gmail or personal email;
• production GitHub write access;
• cloud admin keys;
• Home Assistant device control;
• webhook or API server exposure;
• shared Discord or Slack bots.

Start with Telegram allowlisted to one user, one web search backend, and /output file writing. Add stronger integrations only after the basic setup behaves safely.

A good artifact system gives generated files one obvious destination.

Use:

This prevents the common failure mode where the agent creates a file, but the gateway cannot send it or your laptop cannot find it.

For Docker-backed Telegram sessions, Hermes docs warn that attachments are sent by the gateway process, not from inside the container. So the final file path must be readable by the gateway host.

Use the shared /output mount for that reason.

You can add Obsidian as the knowledge layer.

Create a vault directory on the VPS:

Inside the container, Hermes sees it as:

Now Hermes can write notes, reports, ledgers, markdown drafts, research artifacts, and operating documents into one predictable place.

A simple structure:

Use the inbox for generated artifacts. Curate later in local Obsidian.

Hermes only needs a Markdown vault path. In this setup, Syncthing is the sync layer that moves that folder between the VPS and your Mac for local Obsidian use. It is your deployment pattern, not a Hermes requirement. Hermes also has official Obsidian-oriented patterns, including vault-path configuration and server-friendly options such as headless Obsidian/Obsidian Sync, but Syncthing is simpler and private for this setup.

Syncthing syncs files privately without pushing AI artifacts through Google Drive, Dropbox, or email.

The pattern:

Benefits:

• real files;
• local Obsidian access;
• automatic sync;
• no SaaS document middleman;
• easy backup and review.

Check ownership and permissions after the first sync. If files are root-owned, fix the Docker user mapping before you generate hundreds of notes.

For research workflows, add one current web search provider. Tavily is a practical first choice for agent-oriented search. Exa is useful for semantic search workflows, but add one web backend first and test it before adding more.

A web backend gives Hermes current sources. The model’s training data is not enough for research workflows, and AI-agent outputs should cite live pages.

Web pages, PDFs, skills, READMEs, and arbitrary documents are untrusted input. They can contain prompt injection, malicious instructions, or misleading claims.

Keep the policy simple:

Use web search for evidence.
Do not let web content override deployment rules.

The safest default is a dashboard bound to 127.0.0.1 on the VPS, reached from your laptop through an SSH tunnel. Move to a Tailscale-bound dashboard only if you specifically want a permanently available remote backend. If you do that, bind only to the VPS Tailscale IP and allow the port only on the Tailscale interface.

Hermes Desktop remote backend uses the dashboard backend, usually port 9119, not the OpenAI-compatible API server on 8642. If using the desktop app remotely, point it at the dashboard URL and sign in with the dashboard auth provider advertised by that backend.

For anything reachable beyond your own trusted network, use the OAuth / Nous Portal dashboard auth path from the current Hermes docs. For localhost, SSH tunnel, or Tailscale-only trusted-network use, username/password dashboard auth is the simpler path.

Set dashboard login credentials in ~/.hermes/.env:

envHERMES_DASHBOARD_BASIC_AUTH_USERNAME=<dashboard-user>
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=<strong-dashboard-password>
HERMES_DASHBOARD_BASIC_AUTH_SECRET=<random-signing-secret>

Generate a stable signing secret on the VPS so dashboard sessions survive restarts:

bashopenssl rand -base64 32

Then run the dashboard through a tunnel-first setup on localhost:

bashhermes dashboard --tui --no-open --host 127.0.0.1 --port 9119

For a Tailscale-bound trusted-network dashboard, bind to the VPS Tailscale IP:

bashhermes dashboard --tui --no-open --host <tailscale-ip> --port 9119

A safe access pattern is an SSH tunnel to 127.0.0.1:9119 or http://<tailscale-ip>:9119 behind Tailscale. Never expose the dashboard directly to the open internet. Public access should use the OAuth / Nous Portal path, network restrictions, TLS, monitoring, and a clear reason.

Avoid public 0.0.0.0 exposure unless you have intentionally added authentication, network restrictions, TLS, monitoring, and a clear reason.

For a personal AI-agent VPS, public dashboards add risk without much benefit.

Take provider snapshots after each major phase:

1. OS installed;
2. SSH hardened;
3. Docker installed;
4. Hermes installed;
5. Telegram gateway working;
6. Obsidian/Syncthing working.

Snapshots do not replace backups. They give you fast rollback when you break SSH, Docker, or the gateway service.

The agent may read:

• web pages;
• PDFs;
• emails;
• Telegram messages;
• GitHub READMEs;
• issue comments;
• attached files;
• pasted logs.

Those inputs are data sources, not system administrators.

Keep this rule in the deployment notes:

For higher-risk actions, require approval before:

• shell commands;
• package installs;
• config changes;
• network exposure changes;
• file writes outside /output;
• credential creation;
• cloud administration.