Hermes Agent with Tailscale: reach your agent privately instead of opening ports

What Hermes itself does with Tailscale

Hermes Agent 0.22.5 has no Tailscale integration of its own: there is no hermes subcommand for it, no setting that joins a tailnet, and no code that talks to Tailscale. Tailscale runs on the machine (or beside the container) and Hermes simply listens on an address that Tailscale makes reachable. What the Hermes documentation and code do contain is guidance and a few related behaviours:

• The dashboard documentation says that for a dashboard without a login you should bind to loopback and “reach it over an SSH tunnel or Tailscale”, and it names Tailscale Serve as an example of putting an HTTPS front door on a loopback dashboard.
• The security notes say not to expose the gateway or API to the public internet without a VPN, Tailscale or firewall in front.
• Hermes Desktop lists a remote gateway as reachable over “LAN, Tailscale, or the internet”.
• Hermes’ own web tools refuse addresses in 100.64.0.0/10, the range Tailscale hands out, as part of their protection against requests to internal networks. We come back to this at the end of the Docker section.
• The NixOS module can wait for a Tailscale name or interface before the dashboard starts, so a boot does not race the Tailscale daemon.

New to running Hermes yourself? Start with how to install Hermes Agent, then come back here.

The dashboard over a tailnet: three routes

By default hermes dashboard binds to 127.0.0.1 on port 9119, so only that machine can open it, and there is no login. The dashboard reads and writes your .env, so treat it as a control panel for the whole agent. There are three sensible ways to use it from another device. The Hermes Agent dashboard guide covers the pages themselves.

Route 1: leave it on loopback and tunnel in. Nothing new is exposed. With Tailscale running on both devices, open an SSH tunnel to the machine’s Tailscale name and browse to http://localhost:9119:

ssh -L 9119:localhost:9119 user@your-machine

Route 2: bind to the machine’s Tailscale address. Run the dashboard with --host set to the Tailscale IP, for example hermes dashboard --host 100.x.y.z. Only devices on your tailnet can reach that address. Hermes still switches its login gate on, because any bind other than 127.0.0.1, ::1 or localhost counts as non-loopback; its code states that private and Tailscale ranges are treated as public on purpose, since a hostile device on a shared network is part of the threat model. Without a configured sign-in provider the dashboard refuses to start. The simplest provider is the bundled username and password, set in ~/.hermes/.env:

HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=choose-a-long-password
HERMES_DASHBOARD_BASIC_AUTH_SECRET=<output of: openssl rand -base64 32>

The Hermes documentation says this provider is meant for a trusted network or a VPN and is not suitable for the public internet, which is exactly the tailnet case. The --insecure flag no longer turns authentication off; it does nothing. Hermes also checks the Host header against the address it bound to, so browse to that same address (the Tailscale IP) rather than another name for it.

Route 3: keep it on loopback and put Tailscale Serve in front. Serve adds tailnet-only HTTPS on a https://<machine>.<tailnet>.ts.net address and forwards to the local dashboard. Hermes needs to be told that address, because the request arrives with that hostname. Set it as dashboard.public_url in config.yaml, or as the environment variable HERMES_DASHBOARD_PUBLIC_URL. Per the Hermes documentation, this makes the address an exact accepted Host and still turns the login gate on even though the backend is on loopback, so you set a sign-in provider here too. Then:

# Terminal 1: leave this running
hermes dashboard --host 127.0.0.1 --port 9119 --no-open

# Terminal 2, on the same machine
tailscale serve --bg localhost:9119

Without --bg, Tailscale runs Serve in the foreground and you have to start it again after a reboot or a Tailscale restart. tailscale serve status lists what is being served and tailscale serve reset clears it. Serve needs HTTPS certificates enabled for the tailnet; the CLI offers to enable them.

Hermes Desktop can also attach to a dashboard running elsewhere. Give it the remote address you bound to and sign in with the password above; see the Hermes Agent Desktop guide. Its SSH connection type is a different route: Desktop opens the tunnel and starts the dashboard for you using your SSH key.

Tailscale Serve versus Funnel: one is private, one is public

The two commands look alike and do opposite things. Tailscale Serve routes traffic from other devices on your tailnet to a local service. It is not reachable from the public internet.

Tailscale Funnel routes traffic from the broader internet to a local service. Anyone with the Funnel URL can reach it without being on your tailnet, and it can listen only on ports 443, 8443 and 10000. It needs MagicDNS, HTTPS certificates and a funnel attribute in your tailnet policy file, so it will not switch on by accident, but one deliberate command is enough.

Do not point Funnel at Hermes. The Hermes documentation says the username and password provider is not for exposing a dashboard directly to the public internet, and says the API server hands outside callers the agent’s tools, including terminal commands. Upstream also records that exposed dashboards and API servers were scanned and abused in 2026. If you need Hermes reachable from people outside your tailnet, use a different front door and sign-in method designed for the public internet, not Funnel plus a shared password.

A tailnet is also not a licence to skip the sign-in. Every device on it, including a laptop that someone else shares, can reach the address, which is why Hermes keeps its login gate on for non-loopback binds.

The API server over Tailscale

The gateway’s OpenAI-compatible API server listens on 127.0.0.1:8642 by default. Two settings matter: API_SERVER_HOST (the bind address) and API_SERVER_KEY, the bearer token required for protected API requests. The basic health endpoint does not need it. The key is required even on loopback: Hermes refuses to start the API server with no key, or with a placeholder or a key shorter than 16 characters, and suggests openssl rand -hex 32 to make one.

To let another tailnet device call it, bind to the Tailscale address:

API_SERVER_HOST=100.x.y.z
API_SERVER_KEY=<a long random value>

Clients on your tailnet then use http://100.x.y.z:8642/v1 as the base URL, or the machine’s MagicDNS name once it resolves to that address. You can instead leave the host on loopback and have Tailscale Serve forward to localhost:8642, which gives you HTTPS.

Take the warning in the Hermes documentation seriously: the API server gives full access to the agent’s toolset, including terminal commands. When it is reachable beyond loopback and the terminal backend is the default local one, Hermes logs a warning that agent work from that endpoint runs as the host user, and suggests a sandboxed backend and a firewall to trusted networks. A tailnet is a trusted network only as far as you trust every device and person on it; the access rules below narrow that. Browsers do not get cross-origin access by default; set API_SERVER_CORS_ORIGINS to an explicit list only if a web page must call it directly.

SSH to the box, and the Docker install

SSH. Once the machine is on your tailnet you can SSH to its Tailscale address or MagicDNS name from any other tailnet device, without opening port 22 to the internet. Tailscale also offers its own SSH service: tailscale set --ssh on the host lets Tailscale handle authentication using your tailnet identity instead of SSH keys, on Linux and on the open-source macOS variant of Tailscale. It needs SSH rules in your tailnet policy file; Tailscale’s default policy gives users access to their own devices, with a re-authentication check by default.

Hermes can also run its commands on another machine over SSH, using terminal.backend: ssh with TERMINAL_SSH_HOST and TERMINAL_SSH_USER. That host can be a tailnet name, which keeps a work machine or a homelab box off the public internet. Hermes connects with StrictHostKeyChecking=accept-new and no password prompt, so set up the SSH key first.

Docker. The official Hermes image keeps its persistent state under /opt/data and runs the gateway, plus the dashboard when you set HERMES_DASHBOARD=1. Two details matter for Tailscale. First, inside the container the dashboard binds 0.0.0.0 by default, so the login gate is on and a sign-in provider is required; the documented way to avoid that is HERMES_DASHBOARD_HOST=127.0.0.1 for sidecar or reverse-proxy setups. Second, a published Docker port is reachable on every host address by default. Docker’s documentation shows the fix: bind the published port to a specific address, such as -p 127.0.0.1:9119:9119. The full run options are in the Hermes Agent Docker guide.

The simplest private setup keeps Tailscale on the Docker host:

1. Install Tailscale on the host and sign in, so the host is a tailnet device.
2. Keep the dashboard listening on 0.0.0.0:9119 inside the container and publish it to loopback only with -p 127.0.0.1:9119:9119, so nothing is open on the host’s public address. If you also need the API, set API_SERVER_HOST=0.0.0.0 and a strong API_SERVER_KEY in the container, then add -p 127.0.0.1:8642:8642.
3. Set a sign-in provider and HERMES_DASHBOARD_PUBLIC_URL as in route 3, then run tailscale serve --bg localhost:9119 on the host. If sign-in misbehaves behind the proxy, the Docker guide in the Hermes source explains the dashboard.trusted_proxies setting.

You can instead run Tailscale as its own container with the official tailscale/tailscale image. Tailscale documents the settings that matter: TS_AUTHKEY to join the tailnet, TS_STATE_DIR on a volume so it keeps its identity across restarts, TS_HOSTNAME for the name, and TS_SERVE_CONFIG to set up Serve from a file. Userspace networking is the default; kernel networking needs the /dev/net/tun device and the NET_ADMIN capability. Auth keys are created on the Keys page of the Tailscale admin console and expire after 1 to 90 days, 90 by default; a reusable key is dangerous if stolen, so keep it out of images and repositories.

One side effect to know about: Hermes’ web and vision URL checks block 100.64.0.0/10 addresses by default, so the agent may not be able to fetch a page from another tailnet device by its Tailscale IP. The Hermes setting security.allow_private_urls: true lifts that block for all private ranges at once. The documentation calls it a deliberate trust boundary; enable it only if you accept the agent being steered at your internal network by a malicious page.

MagicDNS names, HTTPS and access rules

MagicDNS gives every device a name, so you do not type IP addresses. The full name is the machine name plus your tailnet’s DNS name, in the form machine-name.tailnet-name.ts.net, and the short machine name alone works from devices on the tailnet. Tailnets created on or after 20 October 2022 have it enabled by default. Use the name you bound Hermes to, and remember the Host header check: if you start the dashboard with --host set to the Tailscale IP, browse by IP; if you use Serve, the ts.net name goes into public_url.

HTTPS certificates are switched on in the admin console’s DNS page, and Serve needs them. Tailscale warns that turning them on records your machine names in the public Certificate Transparency ledger, so do not enable HTTPS if a machine name contains anything sensitive. Name the machine something plain.

Access rules. A new tailnet starts with a policy that lets all devices talk to each other. For an agent that can run commands, narrow it: remove or narrow any existing allow-all rule, because adding a restrictive rule does not override a broader one. Rules live in the tailnet policy file. A rule names a source, a destination and a port, and the destination can be a tag, which is a label you assign to a device. Tags must be declared in the policy file under tagOwners. A minimal policy that lets your own users reach a tagged Hermes machine on the dashboard port:

{
  "tagOwners": {
    "tag:hermes": ["autogroup:admin"]
  },
  "acls": [
    {
      "action": "accept",
      "src": ["autogroup:member"],
      "dst": ["tag:hermes:9119"]
    }
  ]
}

Add one destination per port you want to allow, such as tag:hermes:8642 for the API. With Tailscale Serve, clients connect on HTTPS port 443, so allow tag:hermes:443 instead. The example uses the access-rule form shown in Tailscale’s documentation; Tailscale also offers a newer grants format, so check the current policy syntax page before copying either into a live policy.

Tailscale on ReadyHermes

If you would rather not run a machine, ReadyHermes runs your Hermes Agent for you. Its Tailscale feature is narrower than the self-hosted options above, and it is worth being exact about it: it is an SSH tool that gives you a terminal on your assistant’s own machine, over your own tailnet. It does not let the assistant reach your devices, and it does not publish a dashboard or an API on your tailnet. ReadyHermes does not offer Tailscale Serve or Funnel. (Bot tools also has a separate API endpoint panel that gives you a key and a URL for calling your assistant from your own apps; that is not part of the Tailscale feature.)

It is for people comfortable with a command line who want hands-on access, and you need a Tailscale account. To set it up:

1. Install Tailscale on your own computer and sign in.
2. In the Tailscale admin console, open the Keys page and choose “Generate auth key”. Leave Reusable and Ephemeral off (if your tailnet requires device approval, turn on Pre-approved) and copy the key, which starts with tskey-auth-.
3. In the ReadyHermes workspace, open Bot tools, then SSH. Paste the key and press Connect. The first time can take a couple of minutes.
4. The panel then shows the machine name, the Tailscale address and a ready-made command of the form ssh root@machine-name.tailnet-name.ts.net. Run it from any device signed in to the same tailnet.

The panel says the key is used once to join your network and is never stored. Nothing is opened to the public internet: the assistant joins your tailnet, and the connection is Tailscale SSH, so your own tailnet access rules decide who can connect. The platform brings the connection back after the assistant restarts. Disconnect removes the assistant from your tailnet, and you can connect again later with a new key; if the panel cannot confirm the disconnect, remove the machine in your Tailscale admin console to be sure.

Careful with the login. For a Hermes assistant the SSH user is root. Use the session to look at files and logs, not to run the hermes command: change settings from the workspace panels instead. The panel is available while you are on a paid plan or inside the free trial, which lasts one hour.

For how hosted and self-run setups compare, read self-hosting versus managed hosting.