Hermes Visual Workspace

A local, branchable research canvas powered by real Hermes Agent sessions.

Project status: Alpha. The core session, branching, selection, persistence and security boundaries are tested, but APIs and installation details may change before 1.0.

Every document node maps to an independent Hermes session. Selecting text, asking a follow-up, or creating a sibling produces a real fork with isolated context—not a decorative frontend branch.

Features

• Infinite visual canvas with persisted layout
• Real Hermes root, child and sibling sessions
• Concurrent branches without cross-talk
• Streaming answers and compact tool progress
• Select text to Explain, ELI5, get an Example, or Go Deeper
• Reader and canvas modes
• Crisp fractional zoom and semantic overview cards
• IBM Plex document typography
• Native card scrolling, header-only dragging and touch containment
• Dark and light themes
• Same-origin security boundary: provider credentials never reach the browser

Requirements

• Hermes Agent installed and configured
• Hermes API Server listening on 127.0.0.1:8642
• Python 3.11 or newer
• A browser

Node.js is required only for development. The production frontend is committed under web/hermes-dist/.

Install

git clone https://github.com/Nextbasedev/hermes-visual-workspace.git
cd hermes-visual-workspace
./scripts/install.sh

The installer never prints or copies model/provider credentials. It looks for the local Hermes API_SERVER_KEY in the active environment or Hermes configuration and validates the loopback API.

Start

./scripts/start.sh

Open:

http://127.0.0.1:4180

Defaults can be overridden without editing source:

HERMES_VISUAL_HOST=127.0.0.1 \
HERMES_VISUAL_PORT=4180 \
HERMES_VISUAL_DB="$HOME/.hermes/visual-workspace/workspaces.sqlite3" \
./scripts/start.sh

Keep the default loopback bind unless you intentionally place the app behind a trusted Tailscale or local reverse proxy. There is no public-network authentication layer.

Diagnose setup

./scripts/doctor.sh

It checks Python, the prebuilt frontend, local API credentials and Hermes API health without displaying secrets.

If the Hermes API is not enabled, run Hermes's setup flow and enable the API Server adapter on 127.0.0.1:8642, then restart the Hermes gateway. See the current Hermes messaging/API documentation.

Run as a user service

Generate a service from the included template:

./scripts/install-service.sh

Then inspect it with:

systemctl --user status hermes-visual-workspace
journalctl --user -u hermes-visual-workspace -f

To survive logout/reboot without an active user session:

loginctl enable-linger "$USER"

Update

git pull --ff-only
./scripts/install.sh
systemctl --user restart hermes-visual-workspace  # if installed as a service

Local data

By default, workspace metadata and layout are stored in:

~/.hermes/visual-workspace/workspaces.sqlite3

Hermes remains the canonical store for conversation history. The app database stores only application ownership, node mappings, rendered documents and layout.

Back up the SQLite database before destructive maintenance. Uninstalling the service does not remove data.

Security model

Browser → same-origin local backend → Hermes API on 127.0.0.1:8642

• Browser JavaScript never receives API_SERVER_KEY or provider tokens.
• The backend rejects non-loopback Hermes API URLs and redirects.
• Only app-generated rh_... sessions and rw_... workspaces are exposed.
• Unrelated CLI, Telegram, Discord and cron sessions are not listed.
• Static files are contained after path and symlink resolution.

This is a local/trusted-network application. Do not expose it directly to the public Internet.

Please report security vulnerabilities privately through GitHub's Security → Report a vulnerability flow. See SECURITY.md; do not open a public issue for suspected vulnerabilities.

Development

npm ci
npx playwright install chromium
npm run verify
git diff --check

Focused suites cover backend ownership/transactions/SSE behavior, browser branching and concurrency, IBM font loading, semantic zoom, real mouse selection, card-native scrolling, canvas pan/zoom and persisted layout.

Architecture

• backend/ — Python stdlib same-origin server, Hermes adapter and SQLite store
• src/hermes-workspace/ — application UI
• src/core/ — MIT-licensed Rabbithole document renderer and canvas primitives used by the UI
• web/hermes-dist/ — committed production build
• test/ and tests/ — browser and backend acceptance suites
• docs/hermes-workspace/ — product and API contracts

License and attribution

MIT. The visual workspace reuses portions of Shlok Khemani's MIT-licensed Rabbithole project. IBM Plex fonts are distributed under the SIL Open Font License 1.1. See THIRD_PARTY_NOTICES.md and licenses/.

Contributions are welcome. Read CONTRIBUTING.md before opening a pull request.