Hermes Agent ports: what listens where, and how to change it

The ports at a glance

These are the services most people ask about. “Bound to” is the address Hermes listens on when you change nothing.

The webhook, Telegram, WhatsApp Cloud and other chat-platform receivers only listen once you enable that platform; a plain hermes chat in the terminal opens none of them. The remaining receivers (SMS, Lark, LINE, Teams and others) are in the third section below. Hermes also never opens a port for ACP: hermes acp talks to your editor over standard input and output.

The dashboard on port 9119

hermes dashboard starts the browser interface and hermes serve starts the same server without the web pages, which is what the Hermes Desktop app and remote backends use. Both take the same options and both default to port 9119 on 127.0.0.1:

hermes dashboard --port 9120
hermes dashboard --port 0
hermes dashboard --status
hermes dashboard --stop

--port 0 asks the operating system for any free port. --status lists running dashboard processes and --stop stops them. A single backend normally serves the whole machine, including every profile, so you do not need one port per profile. If one is already running and cannot serve the host and port you typed, the command refuses and names the process that owns it;--isolated gives a profile its own server instead. The full tour of the pages is in the Hermes Agent dashboard guide.

On any address other than loopback the dashboard needs a login. Hermes refuses to start without one: the old --insecure flag is now a no-op and no longer switches authentication off. The simplest login for a private network is a username and password in ~/.hermes/.env:

HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=choose-a-strong-password
HERMES_DASHBOARD_BASIC_AUTH_SECRET=<32 random bytes>

The upstream documentation says plainly that this login is for a trusted network or a VPN, not for direct exposure to the internet. OAuth through Nous Portal (HERMES_DASHBOARD_OAUTH_CLIENT_ID) and a self-hosted OpenID Connect provider are the options for anything wider.

The API server and the webhook receivers

API server, port 8642. The gateway can expose your agent as an OpenAI-compatible endpoint, so tools such as Open WebUI can use it as a backend. It is switched on by a usable API_SERVER_KEY, and Hermes will not start it without one, even on loopback. An explicit enabled: false in config.yaml keeps it off whatever the environment says, and the same holds for the webhook receiver below. The key must be at least 16 characters and not a placeholder; openssl rand -hex 32 makes a good one. The health check is a plain GET /health, and the chat endpoint is /v1/chat/completions.

API_SERVER_KEY=<output of openssl rand -hex 32>
API_SERVER_PORT=8642
API_SERVER_HOST=127.0.0.1
API_SERVER_CORS_ORIGINS=http://localhost:3000

The same settings can live in config.yaml under gateway.api_server with enabled: true and the keys port, host, key and cors_origins. When a usable API_SERVER_KEY (16 characters or more, not a placeholder) is set in the environment, the environment settings override the YAML ones; otherwise the YAML values apply. Browser access is off until you list origins in cors_origins or API_SERVER_CORS_ORIGINS.

Several profiles do not each need their own port in 0.22.5. By default one host gateway serves them all, and the extra profiles are reached on the same listener under /p/<profile>/v1. A per-profile port setting such as SMS_WEBHOOK_PORT in a secondary profile’s .env is ignored in that setup, because nothing binds for it.

Webhook receivers. Some platforms push messages to Hermes instead of Hermes polling them, and each such platform opens its own port once enabled. The generic webhook platform is the one you configure yourself. Turn it on with WEBHOOK_ENABLED=true (or in config.yaml); it listens on 8644 unless you set WEBHOOK_PORT, each route needs a signing secret, set per route or once in WEBHOOK_SECRET, and routes are served under /webhooks/<name>. The others, by default port and address:

• SMS (Twilio): 8080 on 127.0.0.1, set with SMS_WEBHOOK_PORT and SMS_WEBHOOK_HOST.
• Lark (Feishu) webhook mode: 8765 on 127.0.0.1, set with FEISHU_WEBHOOK_PORT. The default websocket mode opens no listening port.
• BlueBubbles: 8645 on 127.0.0.1, set with BLUEBUBBLES_WEBHOOK_PORT.
• WeCom callback: 8645 on all interfaces, set with WECOM_CALLBACK_PORT and WECOM_CALLBACK_HOST.
• LINE: 8646 on all interfaces, set with LINE_PORT and LINE_HOST.
• Microsoft Graph: 8646 on all interfaces, set with MSGRAPH_WEBHOOK_PORT.
• Microsoft Teams: 3978 on all interfaces, set with TEAMS_PORT and TEAMS_HOST.
• Agent-to-agent (A2A): 9900, set with A2A_PORT. With no token configured it binds 127.0.0.1 only.

Telegram in its default polling mode, Discord and WhatsApp through the QR bridge all connect outward and need no port open to the internet. For the chat apps themselves, see Hermes Agent on Telegram and on WhatsApp. Two default pairs share a number: BlueBubbles, WeCom and the local proxy all start at 8645, and LINE and Microsoft Graph at 8646. Enable two of them on one machine and one will fail to bind until you move it.

Which ports must stay private, and how to reach them

Treat the dashboard (9119) and the API server (8642) as keys to the machine. The dashboard reads and writes your .env, which holds API keys, and the API server hands requests to an agent that can run terminal commands. Neither belongs on the open internet. Hermes itself is built around that: the dashboard will not start on a public address without a login, the API server will not start without a strong key, and the API server logs a warning when it is reachable from the network while the terminal backend is the local, unsandboxed one.

The WhatsApp QR bridge on 3000 listens on 127.0.0.1 only and rejects requests whose Host header is not local; there is nothing to open for it. The webhook receivers are different: they exist to be reached by a vendor’s servers, so they need an address the vendor can call, but every one of them checks a signature or secret. The generic webhook refuses to start a route with no secret, and refuses the special test secret on any public address. Telegram webhook mode will not start without TELEGRAM_WEBHOOK_SECRET. The usual way to give a receiver a public address is a tunnel or a reverse proxy that forwards only that one path, so the rest of the machine stays unreachable.

For your own access to the private ports, pick one of these:

• SSH tunnel. Keep the bind on 127.0.0.1 and forward the port from your own computer:ssh -L 9119:localhost:9119 user@your-server, then open http://127.0.0.1:9119 locally. This is the method the Hermes Docker Compose file itself recommends.
• A private network such as Tailscale. Bind to the machine’s private address with --host and a login configured, and only devices on that network can connect. The Hermes Desktop documentation suggests this for a remote backend.
• A reverse proxy with authentication. If you must publish a dashboard, put it behind HTTPS, set dashboard.public_url and list only your proxy’s exact address under dashboard.trusted_proxies. Hermes rejects wildcard entries there.

Do not use --host 0.0.0.0 as a shortcut on a server with a public address, and be wary of API_SERVER_HOST=0.0.0.0 for the same reason. A firewall rule or a cloud security group that allows only your own IP is a sensible second layer on top.

Ports in Docker

In the official image you publish a port with -p the usual way. No published port is needed for outbound connections such as Telegram polling, Discord, or the WhatsApp QR bridge. Webhook-based chat integrations need an inbound route through a published port, tunnel, or proxy. Publish 8642 when an external client needs the API server, and 9119 when you enable the dashboard with HERMES_DASHBOARD=1. Inside the container the dashboard binds 0.0.0.0, because otherwise a published port could not reach it, and so it always requires a login there (the username and password variables above). To publish to your own machine only, give the host side an address:

docker run -d --name hermes --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 127.0.0.1:9119:9119 \
  -e HERMES_DASHBOARD=1 \
  -e HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin \
  -e HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=choose-a-strong-password \
  nousresearch/hermes-agent gateway run

The dashboard port and bind address inside the container come from HERMES_DASHBOARD_PORT and HERMES_DASHBOARD_HOST. To expose the API server beyond the container’s own loopback you set API_SERVER_HOST=0.0.0.0 together with API_SERVER_KEY and publish 8642. The repository’s Compose file takes a different route: both services use host networking and the dashboard is started with --host 127.0.0.1. With host networking the -p flag is ignored and every port is simply the host’s port, so the bind address is the only thing keeping a port private. The Hermes Agent Docker guide covers the rest of the container setup.

Fixing the address already in use error

The error means another process already holds that port on that address. First find it:

lsof -i :9119
ss -ltnp 'sport = :9119'

Replace 9119 with the port in the message. Then fix the one that matches:

• The dashboard says the port is in use. The message points at another hermes serve or hermes dashboard backend, or the gateway. Run hermes dashboard --status, stop the old one with hermes dashboard --stop and start the dashboard again, or keep it and run a separate server with hermes dashboard --isolated --port 9120. A Desktop app has its own backend, which may be the process you are looking at.
• The API server will not bind 8642. Hermes retries a few times to cover a restart where the old process is still letting go. If the port is still taken it gives up for good instead of looping, and the log names the config key to change. Set a different API_SERVER_PORT in your profile’s .env, then restart the gateway with hermes gateway restart. The usual cause is a second gateway on the same machine, so check for one before changing anything.
• The WhatsApp bridge on 3000 is taken. Another local program, often a development server, is using it, or an old bridge was left behind. Hermes only stops a leftover process on that port if it can confirm it is a Node bridge. Otherwise set platforms.whatsapp.extra.bridge_port to a free port.
• A chat-platform receiver fails to bind. Compare the default pairs listed earlier, 8645 and 8646, and give one of the two its own port with its own variable.
• ChatGPT sign-in says port 1455 is busy. That port is used briefly by the browser sign-in flow for the Codex login, and only one program can hold it. Hermes falls back to the device-code login on its own.

Do not kill whatever lsof shows without reading the name first; it is sometimes your browser or an editor holding a connection to that port rather than listening on it. When you want Hermes to avoid the question altogether, --port 0 works for the dashboard and a fixed, unusual number you set yourself works for everything else.

Ports on ReadyHermes

On ReadyHermes you do not manage ports. Your own Hermes Agent runs in its own container on our servers, and there is no ports setting in the workspace, nothing to publish and no bind address to choose. You reach the agent through the browser workspace and the chat apps you connect.

The Channels page connects Telegram, WhatsApp, Discord, WeChat and Lark, and it also shows the details for the free Hermes Desktop app: a remote URL, a username and a password that works only for your assistant and expires after 30 days, with new details available on the same page. For hands-on administration, the SSH tab under Bot tools connects your assistant to your own Tailscale network and gives you a command to run in your own terminal; its own wording says nothing is opened to the public internet. That is the managed equivalent of the tunnel option above.

The ReadyHermes workspace does not expose the upstream dashboard pages. Under Bot tools, the API endpoint panel lets you turn on an OpenAI-compatible endpoint for your assistant and copy its base URL and API key, so your own apps and scripts can call it. The key is shown once when you turn the endpoint on, you can turn the endpoint off again, and the assistant has to be running to turn it on. Requests through it use your assistant just as chatting does. The self-hosting versus managed comparison explains what you give up and gain, and managed Hermes Agent hosting lists what is included. If you want to choose every port and run a local API server yourself, self-hosting is the better fit. If you would rather chat with an agent that stays on, a new one is ready in about 10 seconds and the free trial lasts one hour.