Safety Boundaries: Permissions and What Not to Touch

The Risk Is Real

In June 2026, internet scanners found Hermes deployments where the web dashboard was bound to a public IP without authentication. The scanners reached the dashboard, sent instructions to the agent, and the agent -- because it had unrestricted shell access and no constraints on what it could do -- planted SSH key backdoors on the host. The vulnerability was not in Hermes itself; it was in the deployment: no auth gate, public-facing dashboard, agent running with too many privileges.

The fix was straightforward after the fact: mandatory basic auth on non-loopback binds, VPN or SSH tunnel for remote access, and non-root agent accounts with minimal permissions. But the incident is a useful illustration of a general principle: an agent that can do everything is a liability, not just an asset.

This lesson covers how to apply that principle in a homelab context -- not to make the agent useless, but to make it useful in a bounded way.

The Safe Toolset

Hermes ships a safe toolset that provides read-only capabilities: web search, web extraction, and vision analysis -- but no file writes and no terminal execution. For monitoring-only sessions (a Hermes instance that checks infrastructure but never modifies anything), start it with:

hermes chat --toolsets safe,web

For a monitoring agent running as a cron job or responding to Telegram messages about lab health, the safe toolset is often sufficient. It can run read-only queries via API (using web_extract to hit your Proxmox or TrueNAS API endpoints) without having direct shell access to your machines.

If you need terminal access for reading (not writing), add only the terminal toolset and restrict what the agent user can do via SSH (see below). Do not add the file write toolset to a monitoring-only agent.

Private Network Access and SSRF Protection

Hermes includes SSRF (Server-Side Request Forgery) protection that is enabled by default. It blocks requests to private network ranges including all RFC 1918 addresses -- 192.168.x.x, 10.x.x.x, and 172.16.x.x through 172.31.x.x. This is exactly where your homelab lives.

This matters for web-based tool calls such as web_extract. If you ask the agent to fetch https://192.168.1.10:8006/api2/json/nodes using the web tool, SSRF protection will block it. Terminal-tool curl commands are not subject to SSRF protection and will work regardless.

To allow the agent's web tools to reach your private network (required if you want to use web_extract with homelab APIs), add this to ~/.hermes/config.yaml:

security:
  allow_private_urls: true

This opt-in is deliberate -- it should only be set on a Hermes instance running on a trusted private network, which is exactly what a homelab agent is. Do not set it on any Hermes instance with a public-facing gateway.

Principle of Least Privilege: SSH

The Hermes service account on each machine should have only what it needs for the tasks you have defined. For a monitoring-only agent:

• Create a dedicated hermes user (not root, no sudo)
• Restrict the SSH authorized key with a command= option to limit what commands can run via that key
• Or configure AllowUsers hermes in /etc/ssh/sshd_config to prevent the account from being used interactively

On Proxmox, assign the PVEAuditor role to the hermes@pam user at the datacenter level. This grants read access to cluster resources, VMs, LXCs, and storage -- exactly what the monitoring queries in Lessons 4-6 need -- without the ability to create, modify, or destroy anything.

On TrueNAS, create an API key with read-only scope rather than using the root API key. Check the TrueNAS API key permissions screen when creating it.

Principle of Least Privilege: What the Agent Should Never Do

Define what your homelab agent is not allowed to do and make sure the boundaries are in place at the system level, not just in the prompt. Prompts can be overridden; system permissions cannot. Things a monitoring agent should never be able to do:

• Delete or format anything. The hermes user should not have write access to ZFS datasets, VM disk paths, or backup targets.
• Modify firewall rules. On pfSense/OPNsense, restrict the API token scope to read-only endpoints.
• Start or stop VMs. PVEAuditor on Proxmox prevents this. If you later want the agent to be able to restart VMs, create a separate profile with a more privileged account and use it consciously -- not as the default.
• Modify its own configuration or credentials. The hermes user should not have write access to ~/.hermes/ on your Hermes host if it is running with the SSH backend pointed elsewhere. Keep the config owned by a different user.

Securing the Dashboard

If you run the Hermes web dashboard (default port 9119; remapped to 30433 by the TrueNAS app), set all three auth variables in ~/.hermes/.env:

HERMES_DASHBOARD_BASIC_AUTH_USERNAME=yourusername
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=a-strong-password
HERMES_DASHBOARD_BASIC_AUTH_SECRET=32-plus-random-bytes-for-token-signing

The SECRET variable signs the session tokens -- without it, auth state is not durable across dashboard restarts. All three are needed for a properly secured dashboard.

Do not expose the dashboard port directly to the internet. Put it behind a VPN (Tailscale or WireGuard) or an SSH tunnel. The documentation describes basic auth as "intended for trusted-network / homelab use only."

The Gateway and Messaging Permissions

The Hermes messaging gateway accepts instructions from anyone who can reach the bot. Without an allowlist, the gateway denies all users by default. Set a platform-specific allowlist in ~/.hermes/.env:

# For Telegram: use your numeric Telegram user ID
TELEGRAM_ALLOWED_USERS=123456789

# For Discord:
DISCORD_ALLOWED_USERS=111222333444555666

# Or a cross-platform allowlist (applies to all platforms):
GATEWAY_ALLOWED_USERS=123456789

Get your numeric Telegram user ID from @userinfobot on Telegram. For a homelab agent where only you should issue commands, a single numeric ID in TELEGRAM_ALLOWED_USERS is the right configuration.

For more nuanced control -- such as letting a family member check status but not issue commands -- see the allow_admin_from / user_allowed_commands gateway config options in the Hermes gateway documentation.

A Practical Safety Checklist

Before putting a homelab agent into production, verify:

• Dashboard has all three auth variables set and is not accessible on a public IP
• Agent SSH key is associated with a non-root, no-sudo account on each host
• Proxmox role is PVEAuditor (read-only) unless you have explicitly decided otherwise
• API tokens (Proxmox, TrueNAS, OPNsense) are read-only scoped
• The hermes account cannot write to backup targets, VM disk paths, or system configs
• TELEGRAM_ALLOWED_USERS is set in .env with your numeric user ID
• security.allow_private_urls: true is set only if your Hermes instance is on a private network and you are using web tools to reach homelab APIs
• A Proxmox snapshot exists so you can roll back the Hermes VM if something goes wrong