Hermes Control Interface: A Password-Gated Dashboard for the Hermes Agent Stack
A self-hosted web dashboard for the Hermes AI agent stack. Provides a browser-based terminal, file explorer, session overview, cron management, system metrics, and an agent status panel — all behind a single password gate.
At a glance
- What is it?
- HCI puts a browser terminal, file explorer, cron manager, kanban swarm monitor and token analytics in front of a local Hermes agent install. It is an operator console for machines that already run the hermes CLI, not a hosted service.
- Who is it for?
- Adopt HCI if you already run the hermes CLI on a machine you control and you want an operator console for it, especially if several people share the box and need profile-scoped logins. Do not adopt it if Hermes is not installed on the same host, if you need a horizontally scaled multi-tenant panel, or if you are unwilling to read a roughly 6K-line server.js before exposing it.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 80 days ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap HCI fills between a CLI agent and the people running it
Hermes is driven from a command line, and the repository treats that as a given: the requirements list is Node.js 20+, Hermes Agent installed on the same machine, and the hermes CLI available on PATH. Everything HCI does assumes that CLI is present locally. The problem it solves is operational rather than architectural. Once more than one agent profile exists, and once those profiles have their own sessions, gateways, cron entries and token spend, the state you need is spread across a config.yaml, a kanban.db SQLite file, gateway logs, and the CLI's own output. HCI gathers those into eleven pages behind one login.
The audience is narrow and specific. This is for someone who already operates Hermes on a server and wants a browser in front of it: a terminal, a file editor, a cron view, a usage chart, a swarm board. The README's own framing, "Manage agents, chat, terminals, files, cron, token analytics, MCP servers, and swarm pipelines," reads as a list of things an operator does rather than things an end user does. If you have never installed Hermes, nothing here applies to you yet.
One Express process, four data sources, and a WebSocket for streaming
The architecture diagram in the README is unusually honest about shape. A browser SPA with eleven pages talks to an Express server over port 10274, and that server is described as "monolithic, ~6K+ lines" in server.js. Inside it sit auth (bcrypt, sessions, CSRF), an RBAC layer with 20 permissions across 3 roles, more than 30 REST routes, and a WebSocket channel for real-time work.
Downstream, the server reaches four places. It shells out to the Hermes CLI for agent states and gateway control. It reads kanban.db, a SQLite file, through better-sqlite3 for the task pipeline. It reads the filesystem for config.yaml, logs and skills. It talks to external MCP servers and fetches token pricing. That is the whole data flow, and it explains most of the product's behaviour: the dashboard is a rendering layer over files and a CLI that already exist. Nothing is duplicated into a separate database of HCI's own, at least not according to the material provided. The Office v3 panel is the clearest example of the trade-off being managed: the README claims agent states are read with "zero-subprocess" access via config.yaml and kanban.db at roughly 100ms versus 3000ms. That number is the project's own, and it is the only performance figure in the README. It is a claim about avoiding CLI calls, not a benchmark you can generalize.
Getting it running: two secrets, a build step, and Node 20
The quick start is four commands and one file copy. Clone the repository, cd into it, copy .env.example to .env, then set HERMES_CONTROL_PASSWORD and HERMES_CONTROL_SECRET. Then `npm install && npm run build`, followed by `node server.js`, which the README says lands on http://localhost:10274.
The configuration surface is small enough to list in full. HERMES_CONTROL_PASSWORD is the login password and the README states it is bcrypt hashed. HERMES_CONTROL_SECRET is the session secret. PORT defaults to 10274. HERMES_CONTROL_HOME defaults to ~/.hermes and is described as the Hermes state directory. HERMES_PROJECTS_ROOT defaults to the parent of the repository and is the projects directory. Only the first two are required; the rest have defaults. The README points to docs/INSTALL.md for production setup, nginx and systemd, and to docs/CONFIG.md for the complete variable list, so treat the table above as the minimum rather than the ceiling.
Updating is a four-step manual sequence: `git pull upstream main`, `npm install`, `npm run build`, then restarting the service, with the README's example being `systemctl restart hci-staging` and an explicit note to adjust the service name. There is no migration command in the material, which is consistent with a design that keeps state in Hermes files rather than in its own schema.
Profile-based access control is the feature that decides your deployment shape
Most self-hosted dashboards have one admin login and stop there. HCI's v3.6.2 release is titled "Profile-Based Access Control & Windows Compatibility," and the README gives worked examples of the mechanism. Each user record carries an allowed_profiles field. `["*"]` means full access; a list of names means that user sees only those agents. The examples are `createUser('cx-team', 'password', 'custom', ['jorah'])`, `createUser('influencer-team', 'password', 'custom', ['varys'])`, and an admin with `['*']`.
The enforcement is not cosmetic. According to the README, the filter applies to /api/profiles, /api/office/agent-states, and all :profile endpoints, and a requireProfileAccess middleware guards the gateway, config and keys routes. Nav tabs are hidden based on permissions, with Files and Maintenance marked admin-only. That combination matters: hiding a tab is presentation, but the middleware is the actual boundary, and the README names both. If you are running a shared box where one team should not see another team's agent sessions or API keys, this is the reason to pick HCI over a plain terminal multiplexer.
The broader security posture is stated rather than demonstrated. The README lists a CSP without unsafe-eval, CSRF on all mutating endpoints, rate limiting on both global and chat paths, WebSocket RBAC, path traversal prevention, and XSS protection. Those are claims in a document. None of them are accompanied by a threat model in the material provided, and the security documentation is referenced as docs/SECURITY.md without its contents. Treat the list as a set of things to verify by reading the code, not as an audit result.
Where HCI is the wrong tool
The hard constraint is in the requirements section: Hermes Agent must be installed on the same machine, and the hermes CLI must be on PATH. HCI is not a remote control for an agent running elsewhere, and nothing in the material suggests a remote-execution mode. If your Hermes install lives on a different host, the architecture diagram's arrows from server.js to the Hermes CLI simply do not resolve.
The second limitation is the monolith. A single server.js of roughly 6K+ lines holds auth, RBAC, 30+ REST routes, WebSocket handling, SQLite access, filesystem access and CLI invocation. That is a lot of trust concentrated in one file, and it is the file you must read before putting this on a public interface. It also shapes upgrades: because the surface is one process, a restart is a full outage for the dashboard, which is why the README points to docs/DEPLOY.md for zero-downtime deploys rather than describing them inline.
Third, the panel is only as available as the things it reads. If kanban.db is locked or absent, the Office board has nothing to render. If gateway logs rotate, the live feed loses history. The README describes the Live Feed as 50 events from gateway logs, which is a window, not an archive. Anyone expecting durable audit history from this dashboard will be disappointed; the durable record lives wherever Hermes writes it.
Finally, the Windows compatibility mentioned in the v3.6.2 release title appears only in that title. The material does not say what was fixed, which commands differ, or whether systemd-style deployment advice translates. If you are on Windows, that is an open question, not a supported path you can plan around.
Compared with running Hermes over SSH plus tmux
The obvious alternative is what most people do before a dashboard exists: SSH into the box, run the hermes CLI directly, keep long-running work in tmux, and read logs with tail. That approach has real advantages. There is no web attack surface, no session secret to rotate, no CSRF or CSP configuration to get right, and no build step. Everything HCI shows you is reachable from a shell, because HCI is reading the same files and calling the same CLI.
The difference is in what the browser layer adds. A shared terminal gives everyone the same view and the same privileges; HCI's allowed_profiles field and requireProfileAccess middleware let you hand a teammate a login that only exposes the Varys profile and its sessions. A terminal gives you a log stream; HCI's Usage page adds daily token trends and cost projections with budget alerts, which the README lists as a distinct page. A terminal gives you a process list; Office v3 gives you an eight-lane kanban board (triage through done) with dependency arrows, a board switcher, and a task popup with run history and a workspace file browser.
So the choice is not capability against capability. It is whether the coordination and access-control layer is worth running an Express server with a password gate on your network. For a single operator on a private host, SSH and tmux is fewer moving parts. For a small team sharing agents, the profile scoping is the thing that is hard to replicate with shell accounts.
Licence, maintenance cost, and what the release cadence implies
HCI is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are preserved. That is a permissive licence, and it is the same licence Hermes itself carries according to the README's link. Nothing here is legal advice; if you are embedding HCI in a product, read the LICENSE file in the repository and, where it matters, talk to counsel.
The practical cost is the upgrade path. The README's update sequence is `git pull upstream main`, `npm install`, `npm run build`, then a service restart. There is no migration tooling mentioned, which is consistent with the design: the state lives in Hermes files, and HCI holds no schema of its own beyond what it reads. That lowers upgrade risk in one direction and raises it in another. You will not run a database migration, but you also will not get a compatibility shim if a Hermes release changes config.yaml, kanban.db or the CLI's output format. The dependency is on Hermes' internals, and the material does not describe a version-pinning mechanism.
The release history shows three versions in roughly a month: v3.6.0 (Office v3 Kanban Swarm Monitor) on 2026-06-03, v3.6.1 (Workspace) on 2026-06-16, and v3.6.2 (Profile-Based Access Control & Windows Compatibility) on 2026-06-28. Each is a feature release with a named theme. That cadence is a maintenance signal in both directions: the project is moving, and a moving surface is one you should expect to re-read after each pull. The README's own version line still reads 3.6.1 while v3.6.2 is the latest release, which is a small reminder to check the tag rather than the documentation header.
Editorial conclusion
Adopt HCI if you already run the hermes CLI on a machine you control and you want an operator console for it, especially if several people share the box and need profile-scoped logins. Do not adopt it if Hermes is not installed on the same host, if you need a horizontally scaled multi-tenant panel, or if you are unwilling to read a roughly 6K-line server.js before exposing it. Before installing, confirm three things: that `hermes` resolves on PATH for the service user, that HERMES_CONTROL_HOME points at the real state directory rather than the default ~/.hermes, and that the Node version is 20 or newer.
Community notes