hermes web ui startup

AI Community

Skill notes

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.

Start Frontend Dev Server

Access at: http://localhost:5173

Start Backend Dashboard

Access at: http://localhost:9119

Issue 1: TypeScript Build Errors

Symptom: npm run build fails with TS errors like: Fix: Skip TypeScript check and start dev server directly:

Issue 2: Python 3.9 Compatibility

Symptom: Backend fails with: Cause: Code uses Python 3.10+ type union syntax (Path | None) Fix:

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
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
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@tomevault-io · no license declared
Token usage
Lean
Setup complexity
Guided setup
External API key
Not required
Operating systems
macOS · Linux · Windows
Runtime requirements
Node.js · Python >=3.9
Detected file/system behavior
  • Read-only
Network behavior
External requests
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

Author source file 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

**Symptom**: `npm run dev` fails immediately

**Fix**:
```bash
cd ~/.hermes/hermes-agent/web
npm install
npm run sync-assets
```

## Verification Steps

1. **Check frontend running**:
   ```bash
   curl -s http://localhost:5173 | head -5
   # Should return HTML doctype
   ```

2. **Check backend running**:
   ```bash
   curl -s http://localhost:9119/health
   # Should return OK or JSON status
   ```

3. **Check processes**:
   ```bash
   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:
```bash
# 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](https://github.com/54laowang/hermes-agent) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.