# Hermes Workspace: a self-hosted control plane for Hermes Agent

> Hermes Workspace is a React and TypeScript web front end for Nous Research's Hermes Agent, covering chat, memory, skills, terminal and multi-agent Swarm dispatch. It is a UI layer, not an agent: without a reachable gateway it has nothing to talk to.

**outsourc-e/hermes-workspace** — Native web workspace for Hermes Agent — chat, terminal, memory, skills, inspector.

- Repository: https://github.com/outsourc-e/hermes-workspace
- Website: https://hermes-workspace.com
- Stars: 6,677 · Forks: 1,052
- Language: JavaScript
- License: MIT
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/outsourc-e-hermes-workspace

## The problem Hermes Workspace solves for Hermes Agent users

Hermes Agent ships as a gateway process. You start it, it serves an API, and you drive it from a terminal or from whatever client you already have. That works for one session. It gets awkward once you have several sessions open, a memory directory you want to read as markdown, a skills tree with thousands of entries, and a set of long-running workers you need to watch. Hermes Workspace is the browser surface for that second stage.

The README is explicit about the boundary: "Not a chat wrapper. A complete workspace." The pages it lists are chat, memory, skills, MCP, files, terminal, Operations, Conductor, Agent View, Swarm Mode, Dashboard and Settings. Each one maps to something the agent already exposes, so the workspace is a client rather than a second agent. That distinction decides everything else in this article. If you have no Hermes Agent running, this project has nothing to show you.

## Zero-fork: how the workspace talks to the agent

The v2 release line is built around a rule the README calls "zero-fork": clone, don't fork. The workspace runs against vanilla NousResearch/hermes-agent installed through Nous's own installer, and the README claims vanilla parity for chat, sessions, memory, skills, jobs, MCP, terminal, dashboard, Agent View and Operations. Nothing in the workspace patches the agent.

The connection is two URLs. HERMES_API_URL points at the gateway, defaulting to http://127.0.0.1:8642. HERMES_DASHBOARD_URL points at a separate dashboard API on port 9119, which the docker-compose.yml comment describes as running as a background process reachable only on the private Docker network. The dashboard API backs config, sessions, skills and jobs. Chat streaming runs over SSE, which is why the chat page can render tool calls as they arrive rather than after the turn finishes.

Conductor is the interesting case. The README says it uses the dashboard mission API when available and falls back to Workspace-native Swarm dispatch with mode: native-swarm when the dashboard endpoint is absent, preserving zero-fork behavior. That fallback is a deliberate design choice: a missing upstream endpoint degrades one feature instead of breaking the install. The same thinking shows up in capability gates, which the README says show a clean placeholder for features that need upstream endpoints rather than failing mid-action.

## Installing Hermes Workspace with Docker Compose

The README offers three install paths and puts Docker Compose first, at roughly two minutes. The compose file pulls pre-built images rather than building locally: nousresearch/hermes-agent:latest for the agent and ghcr.io/outsourc-e/hermes-workspace:latest for the workspace. To build from source instead, the compose comment gives a second command that layers docker-compose.dev.yml on top.

Start by copying the environment file and adding one provider key. The .env.example lists Anthropic, Nous, OpenAI, OpenRouter, Google, Google AI Studio and MiniMax as options, and notes that Ollama or another local server needs no key at all.

```bash
cp .env.example .env
docker compose up
```

After the containers come up, the compose comment says to open http://localhost:3000. Two named volumes carry state: hermes-agent-data holds agent config, sessions, skills, memory and credentials, and hermes-workspace-files holds files created from the workspace file browser. Both survive container recreation and docker compose down. Only docker compose down -v removes them, which is the command to avoid if you care about the memory directory.

## Attaching the workspace to an agent you already run

If Hermes Agent is already installed through Nous's installer, a source checkout, systemd or Docker, and it serves the gateway at http://<host>:8642, the README says you do not need to reinstall anything. Clone the workspace, install dependencies, copy the environment file and point it at your services.

```bash
git clone https://github.com/outsourc-e/hermes-workspace.git
cd hermes-workspace
pnpm install
cp .env.example .env
echo 'HERMES_API_URL=http://127.0.0.1:8642' >> .env
echo 'HERMES_DASHBOARD_URL=http://127.0.0.1:9119' >> .env
pnpm dev
```

The README notes that zero-fork installs need the separate dashboard API for config, sessions, skills and jobs, which is why both URLs are set here. If your gateway was started with API_SERVER_KEY, the README says to set the same value in HERMES_API_TOKEN. The dev server listens on http://localhost:3000, overridable with PORT=4000 pnpm dev. There is also a one-line installer that runs the whole sequence, including Nous's official agent installer, from a curl pipe into bash.

The requirement that trips people up is on the agent side. The .env.example states plainly that the Hermes Agent gateway HTTP API server is opt-in: you need API_SERVER_ENABLED=true in ~/.hermes/.env and a gateway restart. Without it the gateway serves messaging platforms but not port 8642, and the workspace has nothing to connect to.

## Swarm mode and what it assumes about your machine

Swarm Mode is the part of the workspace that goes past a single agent. The README describes it as unlimited Hermes Agents behind one orchestrator with zero humans manually dispatching, backed by persistent tmux workers that keep context across tasks, rotate, and report checkpoints. Roles cover builders, reviewers, docs, research, ops, triage, QA and lab lanes, and a byte-verified review gate is said to protect release branches before PRs ship.

That is a lot of machinery, and it is not free. Persistent tmux workers mean the host keeps processes alive between tasks, and the TUI view attaches to those tmux-backed workers or falls back to a live shell and log stream. This is a design for a machine you leave running, not a laptop you close at night. The swarm documentation lives under docs/swarm/, and swarm.yaml sits at the repository root, so the topology is configuration rather than something the UI invents at runtime.

Read the Swarm section as an opinionated workflow, not a general feature. Teams that want one chat window and a memory browser can ignore it entirely. Teams that want autonomous PR and issue lanes are buying into a specific operating model, and the README's framing ("keeps the machine moving while humans handle judgment") tells you where the human is expected to sit.

## Where Hermes Workspace is the wrong tool

The clearest limitation is architectural. Hermes Workspace is a client. The README states it runs on vanilla hermes-agent, and package.json marks the package private with a main field pointing at electron/main.cjs. There is no bundled agent, no model serving, and no provider abstraction of its own beyond what the agent already does. If you want to try an agent without installing one, this is the wrong starting point.

The second limitation is the dashboard dependency. The .env.example notes that zero-fork installs need the separate dashboard API for config, sessions, skills and jobs. The README's Conductor fallback exists precisely because that endpoint may be absent. So a workspace attached to a bare gateway will show some pages fully and others degraded, and you should expect that rather than treat it as a bug.

The third is operational. The Dockerfile installs python3 because scripts/pty-helper.py backs the terminal feature, and a comment records that the dependency was regressed by the 2026-05-01 rename commit and re-added per issue #259. That is a normal maintenance story for a young project, but it means the container image is where the terminal feature either works or does not. The README does not document a rollback procedure for a failed upgrade, which matters if you are running Swarm lanes against a release branch.

## Hermes Workspace compared with Hermes WebUI and the Hermes dashboard

The search data around this project is mostly people trying to place it against neighbouring surfaces: Hermes WebUI, the Hermes desktop app, the Hermes dashboard, and Hermes Agent itself. The README gives enough to draw one line clearly. Hermes Agent is the gateway and the agent runtime. Hermes Workspace is the workspace UI on top of it, and the v2 section claims vanilla parity with the agent's own dashboard, Agent View and Operations pages rather than replacing them.

The dashboard comparison is the subtler one, because the workspace consumes a dashboard API on port 9119 for config, sessions, skills and jobs. That makes the dashboard an upstream service from the workspace's point of view, not a rival. When the endpoint is missing, Conductor falls back to native Swarm dispatch and the README says the install stays zero-fork.

Against Hermes WebUI, the honest answer from this material is that the README does not compare them. What it does say is that the workspace covers files, terminal, MCP, skills, memory, Operations and Swarm in one interface, which is a wider surface than a chat front end. If your need is a chat window, the extra pages are weight. If your need is to watch several agents and read their memory, they are the reason to pick this.

## Licence, upgrade cost and maintenance signals

The project is MIT licensed, and package.json repeats the MIT identifier with the author listed as Eric. MIT is permissive: you can use, modify and redistribute the code, including commercially, provided the copyright notice and licence text are kept. That is a summary of the licence, not legal advice, and the LICENSE file at the repository root is the text that governs.

The workspace itself is private in package.json, which is normal for an application rather than a published library. You are not consuming it as a dependency, so upgrades mean pulling the repository or the image. The compose file's pre-built images make that a tag change; a source checkout means pnpm install against pnpm-lock.yaml, and the Dockerfile warns that pnpm-workspace.yaml carries the allowBuilds approvals for electron and esbuild, so omitting it makes pnpm 10 or 11 fail on ignored build scripts.

The last push to the repository was on 2026-09-10, and the most recent release is v2.3.0 from 2026-05-08, which added HermesWorld integration, Agent View and dashboard polish. The repository is not archived. Those two dates are the only maintenance facts here; the README does not publish a support policy or a deprecation schedule, so treat the CHANGELOG and the release tags as your upgrade signal.

## Conclusion

Adopt Hermes Workspace if you already run Hermes Agent and want a browser interface for sessions, memory, skills and multi-agent dispatch instead of driving the gateway from a shell. Do not adopt it as a standalone agent: the README states it runs on vanilla NousResearch/hermes-agent, and the .env.example warns the gateway HTTP API is opt-in via API_SERVER_ENABLED=true, so a gateway without that flag leaves the workspace with nothing on port 8642. Verify that first, then check whether you need HERMES_DASHBOARD_URL for config, sessions, skills and jobs.

## FAQ

### What is Hermes Workspace?

It is a native web workspace for Hermes Agent, covering chat, memory, skills, MCP, files, terminal, Operations, Conductor, Agent View and Swarm Mode in one interface. The README describes it as a complete workspace rather than a chat wrapper, and states that it runs on vanilla NousResearch/hermes-agent.

### How do I install Hermes Workspace?

The README gives three paths: Docker Compose with docker compose up after copying .env.example, a one-line curl install script, or attaching to an existing hermes-agent by cloning the repository and running pnpm install and pnpm dev. The Docker path pulls pre-built images and opens on http://localhost:3000.

### What are the differences between Hermes WebUI and Hermes Workspace?

The README does not compare the two, so the distinction has to come from scope. The workspace covers chat plus files, terminal, memory, skills, MCP, Operations and Swarm dispatch, while a chat front end would cover the conversation surface only.

### What is HermesWorld in Hermes Workspace?

HermesWorld integration is listed in the v2.3.0 release notes alongside Agent View and dashboard polish. The README does not document what HermesWorld adds beyond that release entry.

## Sources

- [License: MIT](https://github.com/outsourc-e/hermes-workspace/blob/main/LICENSE)
- [outsourc-e/hermes-workspace on GitHub](https://github.com/outsourc-e/hermes-workspace)
- [Project website](https://hermes-workspace.com)
- [README](https://github.com/outsourc-e/hermes-workspace/blob/main/README.md)
- [Releases](https://github.com/outsourc-e/hermes-workspace/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/outsourc-e-hermes-workspace