hermes-web-ui-startup

AI Community

Repo stars 0
Author repo skills-registry

Interpretation is structured for decision-making; original keeps the upstream SKILL.md unchanged.

Decide Fit First

Core job: Start and troubleshoot the Hermes Agent Web UI (Vite + React frontend with Python backend) Use when this capability is needed. H…
Best fit: Use it when the task has reusable inputs, steps, and validation criteria rather than a one-off answer.
Avoid forcing it: If the source lacks commands, platform support, or external-service evidence, keep those fields unknown instead of guessing.

Design Intent

Structure: The skill is organized around “Architecture Overview”, “Quick Start”, “Start Frontend Dev Server”, “Start Backend Dashboard”, showing how the author expects the agent to judge fit, collect context, and produce verifiable output.
Trigger evidence: Prioritize the author’s wording around when to use it, what context to collect, and what output shape to produce.
Evidence boundary: Author text states facts, repository files prove commands and paths, and Fluxly only adds fit, limits, and usage judgment.

How To Use It

Inputs: Provide target material, scope, expected result, forbidden changes, and validation method.
Invocation: Name hermes-web-ui-startup directly; if the source includes slash commands, start with the command and then add task context.
Validation: Start small and check whether the result follows “Architecture Overview / Quick Start / Start Frontend Dev Server” before expanding.

Boundaries And Review

Dependencies: It usually needs no extra API key, so start with a small validation task.
Permissions: Declared permissions include read; ask the agent to state file, command, and rollback boundaries before acting.
Quality bar: A useful result names the deliverable, evidence, and next action. Generic prose means the task needs tighter context.

Hermes Web UI Startup & Troubleshooting

Architecture Overview

Hermes Web UI consists of two components:

Frontend: Vite + React (hermes-agent/web/) - Port 5173
Backend: Python web server (hermes_cli/web_server.py) - Port 9119

Frontend proxies /api/* requests to the backend.

Quick Start

Start Frontend Dev Server

cd ~/.hermes/hermes-agent/web
npm run dev
# or directly: npx vite

Access at: http://localhost:5173

Start Backend Dashboard

cd ~/.hermes
hermes dashboard
# or directly: python3 -m hermes_cli.web_server --port 9119

Access at: http://localhost:9119

Common Issues & Fixes

Issue 1: TypeScript Build Errors

Symptom: npm run build fails with TS errors like:

src/components/ModelPickerDialog.tsx(285,22): error TS2552: Cannot find name 'loadProviders'

Fix: Skip TypeScript check and start dev server directly:

# TypeScript errors don't prevent dev server from running
npx vite --no-open

Issue 2: Python 3.9 Compatibility

Symptom: Backend fails with:

TypeError: unsupported operand type(s) for |: 'type' and 'NoneType'

Cause: Code uses Python 3.10+ type union syntax (Path | None)

Fix:

# Option 1: Upgrade to Python 3.10+
brew install python@3.10

# Option 2: Use frontend only (some features may not work)
# Frontend dev server still works standalone
npx vite

Issue 3: Backend Connection Warnings

Symptom: Browser console shows warnings about dashboard unreachable:

[hermes] Dashboard at http://127.0.0.1:9119 unreachable

Fix: Start the backend separately or ignore if you only need UI preview:

# In separate terminal
cd ~/.hermes && hermes dashboard

Issue 4: Dependencies Not Installed

Symptom: npm run dev fails immediately

Fix:

cd ~/.hermes/hermes-agent/web
npm install
npm run sync-assets

Verification Steps

Check frontend running:

curl -s http://localhost:5173 | head -5
# Should return HTML doctype

Check backend running:

curl -s http://localhost:9119/health
# Should return OK or JSON status

Check processes:

ps aux | grep -E "(vite|hermes.*dashboard)" | grep -v grep

Development vs Production

Development

Frontend: npm run dev (port 5173)
Backend: hermes dashboard (port 9119)
Hot reload enabled
CORS handled via Vite proxy

Production

Build frontend: npm run build (outputs to hermes_cli/web_dist/)
Backend serves static files directly
Single port (9119) for both UI and API

Troubleshooting Checklist

Node.js 20+ installed (node --version)
Python 3.10+ installed (python3 --version)
npm dependencies installed (cd web && npm install)
Assets synced (npm run sync-assets)
No other process using ports 5173 or 9119
Backend running before making API calls
Session token properly injected (handled by Vite plugin)

Background Process Management

When running in background:

# Start frontend in background
cd ~/.hermes/hermes-agent/web && npx vite --no-open &

# Verify startup (may take 2-3 seconds)
sleep 3 && curl -s http://localhost:5173 > /dev/null && echo "Frontend OK"

Source: 54laowang/hermes-agent — distributed by TomeVault.

Fluxly profile Author and license come from source; runtime, permissions, and network are Fluxly detections or estimates

Fluxly category: AI
Author-declared agents: No explicit declaration found; this is not inferred or tested compatibility
Static check: 88 / 100 · heuristic scan, not runtime safety proof
Author / version / license: @tomevault-io · no license declared
Fluxly token estimate: Lean
Fluxly setup estimate: Guided setup
External API key: No requirement detected
Detected OS requirements: macOS · Linux · Windows
Runtime requirements: Node.js · Python >=3.9
Detected file/system behavior: Read-only
Detected network behavior: External requests
Install commands: None (reference only)

Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.

Heads up: 未限定 allowed-tools，默认拥有全部工具权限。

Output preview hermes-web-ui-startup.preview

The current SKILL.md does not define a fixed output example.

SKILL.md SKILL.md

# Hermes Web UI Startup & Troubleshooting

## Architecture Overview

Hermes Web UI consists of two components:
1. **Frontend**: Vite + React (`hermes-agent/web/`) - Port 5173
2. **Backend**: Python web server (`hermes_cli/web_server.py`) - Port 9119

Frontend proxies `/api/*` requests to the backend.

## Quick Start

### Start Frontend Dev Server
```bash
cd ~/.hermes/hermes-agent/web
npm run dev
# or directly: npx vite
```

Access at: `http://localhost:5173`

### Start Backend Dashboard
```bash
cd ~/.hermes
hermes dashboard
# or directly: python3 -m hermes_cli.web_server --port 9119
```

Access at: `http://localhost:9119`

## Common Issues & Fixes

### Issue 1: TypeScript Build Errors

**Symptom**: `npm run build` fails with TS errors like:
```
src/components/ModelPickerDialog.tsx(285,22): error TS2552: Cannot find name 'loadProviders'
```

**Fix**: Skip TypeScript check and start dev server directly:
```bash
# TypeScript errors don't prevent dev server from running
npx vite --no-open
```

### Issue 2: Python 3.9 Compatibility

**Symptom**: Backend fails with:
```
TypeError: unsupported operand type(s) for |: 'type' and 'NoneType'
```

**Cause**: Code uses Python 3.10+ type union syntax (`Path | None`)

**Fix**:
```bash
# Option 1: Upgrade to Python 3.10+
brew install python@3.10

# Option 2: Use frontend only (some features may not work)
# Frontend dev server still works standalone
npx vite
```

### Issue 3: Backend Connection Warnings

**Symptom**: Browser console shows warnings about dashboard unreachable:
```
[hermes] Dashboard at http://127.0.0.1:9119 unreachable
```

**Fix**: Start the backend separately or ignore if you only need UI preview:
```bash
# In separate terminal
cd ~/.hermes && hermes dashboard
```

### Issue 4: Dependencies Not Installed

…

Evidence boundary and execution chain

Author text anchors workflow facts; Fluxly only indexes current sections, terms, files, and commands.

sections -> Architecture Overview → Quick Start → Start Frontend Dev Server → Start Backend Dashboard → Common Issues & Fixes → Issue 1: TypeScript Build Errors
terms    -> Frontend · Backend · Symptom · Fix · Cause · Check frontend running · Check backend running · Check processes
files/cmd -> hermes-agent/web/ · hermescli/webserver.py · /api/ · http://localhost:5173 · http://localhost:9119 · npm run build · Path | None · npm run dev
body sha256 -> 033330bec291