Run it
The port that never opened
Non-loopback binding is not a flag that works by itself. Started with <code>--host 0.0.0.0</code> and no auth provider configured, the server refused to bind, printed why, closed with exit code 0, and left nothing listening. The exit code is the trap: a start script that checks for zero reports success while the port is empty. Binding to loopback starts normally and prints a ready line, which is the only reliable signal.
Every article about exposing a service starts with the same instruction: bind to 0.0.0.0 and put authentication in front. We tried the first half on its own, expecting a warning and an open port. What happened instead is a better story, and a worse one for anyone automating it.
What the command actually did
$ timeout 15 hermes serve --host 0.0.0.0 --port 9123
Refusing to bind dashboard to 0.0.0.0 — the auth gate engages on non-loopback binds
(0.0.0.0), but no auth providers are registered.
Configure an auth provider before exposing the dashboard:
• Password: set dashboard.basic_auth.username + password_hash in config.yaml
(hash with: python -c "from plugins.dashboard_auth.basic import hash_password; print(hash_password('your-password'))")
• OAuth: run `hermes dashboard register` (Nous Portal) or install a DashboardAuthProvider plugin.
There is no unauthenticated public-dashboard option. For local-only use, bind 127.0.0.1
and leave dashboard.public_url unset; a configured external public URL requires auth
even when a local reverse proxy reaches a loopback backend.
It refused, and it said exactly why. That part is good design. The rest of the behaviour is what this article is about.
The exit code is the trap
$ timeout 12 hermes serve --host 0.0.0.0 --port 9123 >/tmp/a.log 2>&1; echo "退出码=$?"
退出码=0
$ ss -tlnp | grep 9123
9123 无监听
Zero. Nothing listening. Those two lines do not belong together in most people’s mental model of a failed start, and that combination is how you lose an hour: a supervisor with Restart=on-failure sees success and stops trying; a deployment script that checks $? prints “started” and moves on; a health check that runs thirty seconds later reports the port as down, and the log you would have read was ten lines of explanation that scrolled past.
If you take one operational lesson from this page, take the pair: a start command that exits zero has not necessarily started anything, and the only cheap verification is the socket, not the status.
Why refusing is the right default
Non-loopback binding is the moment a local tool becomes reachable by anything that can route to it, and the thing behind it can run commands on your machine. The overwhelming majority of exposed-and-compromised incidents are not sophisticated: an agent backend on a public address with no auth is a remote shell with extra steps.
So the gate is not an inconvenience to work around, it is the design: no auth provider, no non-loopback bind. The two supported ways to satisfy it are printed in the message itself - a password hash stored in the config, or OAuth through the dashboard registration flow. Both are one-time steps, and both are strictly better than a flag that quietly opens the port.
Loopback starts, and says so
The contrast run, same binary and same port:
$ ( hermes serve --host 127.0.0.1 --port 9123 >/tmp/b.log 2>&1 & ); sleep 7
$ ss -tlnp | grep 9123
LISTEN 0 2048 127.0.0.1:9123 0.0.0.0:* users:(("hermes",pid=628,fd=14))
$ head -2 /tmp/b.log
HERMES_BACKEND_READY port=9123
Hermes backend listening on 127.0.0.1:9123
Two independent confirmations, and neither is an exit code: a ready line naming the port, and a listening socket owned by the process id. If a setup has only one of them, it is not verified - the ready line can print before a later problem, and a listening socket can belong to a stale process from an earlier attempt.
That stale process point is worth a habit: ss shows the pid, so compare it with the process you just started rather than assuming the port is yours.
The reverse-proxy shortcut is closed too
The plausible workaround is to keep the backend on loopback and put a proxy in front, so the gate never fires. The message anticipates it: a configured external public URL requires auth even when a local reverse proxy reaches a loopback backend. In other words the decision is not “which interface am I bound to” but “is this service meant to be reached from outside”, and configuration that says yes brings the auth requirement with it.
That is the correct trade. A proxy terminates TLS and sets headers; it does not know who is calling, and it cannot ask your agent to be careful. If the deployment is genuinely local, bind loopback and leave the public URL unset - the tool stays out of the auth business because nothing outside can reach it.
How you know it worked
For the refusing case, three checks that would have caught it immediately:
- The port exists on the address you asked for:
ss -tlnp | grep 9123returns aLISTENline with your pid. - The log contains a ready line for that port - and if the log contains “Refusing to bind”, stop there and fix the auth provider rather than retrying.
- A request to the port returns something:
curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:9123/api/statusgives a status code, not an empty response.
For the exposed case, add a fourth: from a different machine, the port is reachable and unauthenticated requests are rejected. A port that answers without credentials is not a success, it is the failure this whole mechanism exists to prevent.
How to undo it
The refused start changed nothing, which is easy to verify and worth verifying:
md5sum ~/.hermes/config.yaml # same hash before and after the refused bind
For a change that did take effect, the order matters. Stop the process, confirm the port is free, then revert the config from the copy you made before editing. If you added a password hash, deleting the basic_auth block returns the tool to “no provider, loopback only” - and any session created under that password is gone with it. If you exposed the port and are stepping back, revert the bind address first and the client configuration second, because a client pointed at a dead address looks exactly like a broken backend.
What we did not test
An actual bind on a public interface with a password hash configured, the OAuth registration flow end to end, and TLS termination in front of a loopback backend. What we did test is the refusal path and the loopback path on one machine, twice, with the socket inspected both times - and the finding that survived is the one about exit codes, not about flags.
Related
Questions people actually ask
Why did it refuse to bind to 0.0.0.0?
Because the auth gate engages on non-loopback binds and no auth provider was registered. The server explains that it has no unauthenticated public option and tells you to configure either a password or OAuth before exposing it.
Did it fail loudly?
It printed a clear explanation, then exited with code 0. That is why this is worth writing down: a script or a supervisor that only checks the exit status will record a success, while ss shows nothing on the port.
Does binding to loopback behind a reverse proxy avoid the gate?
Not if an external public URL is configured. The message is explicit that a configured external URL requires auth even when a local reverse proxy reaches a loopback backend, so the proxy path is not a way around authentication.
How do I create the password it asks for?
It prints the command: hash a password with the dashboard_auth helper and put the username plus hash into the config. The plaintext is never stored, so the hash is the only artefact you keep.
What is the reliable way to know it started?
Two signals together: the process prints a ready line naming the port, and the port appears as a listener on the address you asked for. A zero exit code tells you nothing about either.
Sources
Last checked: 2026-11-19 · The refusal text, the exit code, the empty port and the working loopback listener were observed on this machine on 2026-11-19; the config file hash was identical before and after the refused start.