How to Secure a Hermes Agent Server

Steps

1. 1

   Inventory the runtime before changing access

   Run hermes --version, hermes config path, hermes dashboard --status and hermes gateway status on the owning host. Record the installation, service user, active profile and intended network path without copying secrets. A local browser address does not identify a remote server. Use the VPS deployment guide to establish which machine owns the runtime before editing firewall rules.

2. 2

   Keep SSH recovery available

   Use a non-root service account and SSH keys. Before disabling password login or changing a firewall, prove key-based access in a second terminal and retain the original session plus provider recovery-console access. Allow the SSH port actually configured on this host, not a guessed port 22. Validate the SSH configuration before reloading it. Do not run a blanket firewall recipe that can lock you out.

3. 3

   Keep the dashboard private by default

   Start hermes dashboard --host 127.0.0.1 --port 9119 --no-open on the server. From your laptop, use ssh -N -L 9119:127.0.0.1:9119 user@your-server, replacing the host and account, then open http://127.0.0.1:9119. Restrict SSH access itself. Loopback dashboards do not require a login by default, so never forward that origin through a public tunnel and assume the tunnel activates Hermes authentication. The dashboard setup guide covers launch and reachability.

4. 4

   Choose authentication for the actual exposure

   For a trusted LAN or VPN, the built-in username/password provider can be appropriate; it is a shared credential, not per-user accounts or MFA. For a public HTTPS hostname, use Nous OAuth or your own conformant OIDC provider. A non-loopback bind engages the auth gate and fails closed if no provider is configured. The deprecated --insecure flag does not bypass it. Authentication protects access to a powerful administration surface; it is not a limited guest-chat role.

5. 5

   Match the OAuth callback to the public hostname

   For Nous OAuth, register on the owning host with hermes dashboard register --redirect-uri https://dashboard.example.com/auth/callback, replacing the example domain. Configure HERMES_DASHBOARD_PUBLIC_URL=https://dashboard.example.com for that same deployment and serve it through HTTPS. Load the settings into the intended service and restart it in a maintenance window. Keep the origin reachable only by the intended private/proxy path; do not open port 9119 to the world just to repair a redirect. Follow the official Dashboard authentication documentation for provider configuration.

6. 6

   Verify the gate, not just a green status response

   From a signed-out browser, check that management pages require login. Inspect curl -fsS https://dashboard.example.com/api/status for auth_required: true and the expected auth provider. This endpoint is deliberately public and its HTTP 200 is not proof of authorization. Attempt a read-only management endpoint such as /api/config without credentials: it must not disclose configuration. Sign in normally, verify the owning profile, then test one harmless Chat response. Log out and repeat the denied-access check. Record only the status and result, not cookies, authorization headers or returned private configuration.

7. 7

   Authorize messaging users separately

   Dashboard login does not authorize Telegram or Discord senders. Use hermes gateway setup and the supported per-platform allowlists; for Telegram, TELEGRAM_ALLOWED_USERS is a comma-separated list of numeric user IDs in the owning profile environment. Review existing pairing approvals as well as allowlists and remove unintended access through supported pairing commands. A whole-group authorization may permit every member, which differs from a sender allowlist. Follow the Telegram setup guide and Discord setup guide, then prove one permitted request and one denied or pairing-only request without running privileged actions.

8. 8

   Configure approvals and understand their limits

   In config.yaml, set approvals.mode: manual when you require a human decision on commands classified as dangerous, and retain approvals.cron_mode: deny and approvals.single_query_mode: deny for unattended work that must not auto-approve them. These are nested YAML keys, not a complete replacement file. Review command_allowlist, YOLO settings and the tools available to the agent. Manual mode does not prompt for every command or every possible external write. Tirith scanning is a separate setting, security.tirith_enabled; it is not the approval policy. Consult the official security reference before changing defaults.

9. 9

   Bound file, tool and network access

   A profile separates agent configuration and state, but is not an operating-system sandbox. Use a dedicated account or isolated environment for a distinct trust boundary, mount only necessary files, and avoid exposing the host Docker socket or unrelated credentials. The terminal backend guide explains execution placement. File-tool write guards do not stop a terminal process running as the same OS user from accessing those files. Command approvals and prompt-injection scanning reduce mistakes; neither proves that an adversarial process is contained.

10. 10

    Protect secrets and recoverable state

    Keep credentials out of source control, screenshots, public logs and support exports. On POSIX, restrict the owning profile .env with chmod 600 ~/.hermes/.env, adjusting the path for a named profile; also check parent-directory ownership and backup access. If a token appears in a log or shared transcript, revoke or rotate that token and review provider activity. A redaction setting cannot un-leak it. Use the Hermes backup and restore guide and test recovery privately without starting a second live messaging poller.

11. 11

    Update deliberately and repeat the acceptance checks

    Run hermes doctor for diagnostics and advisories, back up, then update using the method appropriate to this installation. A source checkout, container image and declarative Nix deployment do not have identical update procedures. After restart, repeat private reachability, denied management access, intended-profile login and a harmless permitted workflow. Treat newly exposed ports, missing auth or unexpected users as a failed release rather than calling the server secure because the process started.

12. 12

    Decide who owns ongoing security

    Write down who owns host patches, dashboard identity configuration, provider credentials, backups, gateway access and incident response. Self-hosted Web UI is an administration surface, including supported TUI Chat, not managed operations. Compare FlyHermes pricing and hosting responsibility if your requirement is managed browser/mobile access and uptime. Confirm current plan scope; managed hosting does not erase your responsibility for connected-account permissions or approval of consequential actions.

Pro Tips

• 💡Keep a small acceptance record: host/profile, version, exposure path, auth provider, signed-out result, permitted-user result, denied-user result, recovery owner and timestamp. Do not include secrets.
• 💡Do not use a public reverse proxy as a substitute for Hermes authentication. Test both the proxy entry point and whether the origin can be reached around it.
• 💡Telegram polling uses outbound connections. Expose an inbound endpoint only for an intentionally configured webhook or other service; protect it with the documented verification mechanism.
• 💡These instructions are a hardening baseline, not a penetration test or a guarantee against compromise. Review the full official security documentation for your threat model.

Troubleshooting

FAQ