Hermes Workspace AI Agent UI

Skill by ara.so — Hermes Skills collection.

Hermes Workspace is a native web interface for Hermes Agent that provides chat, terminal, memory browser, skills catalog, MCP integration, multi-agent orchestration, and a complete control plane for autonomous AI workflows. Unlike chat wrappers, it's a full workspace with file browsing, persistent sessions, role-based agent dispatch, and swarm mode for managing multiple Hermes Agent workers.

What It Does

Chat Interface: Real-time SSE streaming, tool call rendering, multi-session support, markdown + syntax highlighting
Memory Browser: Search, edit, and manage agent memory with live markdown editor
Skills Catalog: Browse 2,000+ skills with origin badges, filters, source paths
MCP Integration: Full Model Context Protocol catalog, marketplace, and source management
Terminal & Files: Monaco-powered file browser and cross-platform PTY terminal
Multi-Agent Dashboard: Manage multiple Hermes Agent instances with profile presets (Sage/Trader/Builder/Scribe/Ops)
Swarm Mode: Persistent tmux-backed agent workers with role-based dispatch and Kanban task board
Conductor: Mission decomposition and dispatch with fallback to native swarm orchestration
PWA Support: Install as native app, access over Tailscale

Installation

Docker Compose (Recommended for Self-Hosting)

bash

# Clone repository
git clone https://github.com/outsourc-e/hermes-workspace.git
cd hermes-workspace

# Start with docker-compose
docker-compose up -d

# Access at http://localhost:3000

One-Line Install (macOS/Linux)

bash

curl -fsSL https://raw.githubusercontent.com/outsourc-e/hermes-workspace/main/install.sh | bash

# Terminal 1: Start Hermes Agent gateway
hermes gateway run

# Terminal 2: Start workspace
cd ~/hermes-workspace && pnpm dev

Manual Installation

bash

# Prerequisites: Node.js 22+, pnpm
git clone https://github.com/outsourc-e/hermes-workspace.git
cd hermes-workspace

# Install dependencies
pnpm install

# Configure environment
cp .env.example .env

# Edit .env with your settings
echo 'HERMES_API_URL=http://127.0.0.1:8642' >> .env
echo 'HERMES_DASHBOARD_URL=http://127.0.0.1:9119' >> .env

# Start development server
pnpm dev

Attach to Existing Hermes Agent

If you already have a Hermes Agent gateway running:

bash

git clone https://github.com/outsourc-e/hermes-workspace.git
cd hermes-workspace
pnpm install
cp .env.example .env

# Point to existing gateway
echo 'HERMES_API_URL=http://127.0.0.1:8642' >> .env
echo 'HERMES_DASHBOARD_URL=http://127.0.0.1:9119' >> .env

# If gateway requires auth
echo 'HERMES_API_TOKEN=your_api_server_key' >> .env

pnpm dev

Configuration

Environment Variables

bash

# Required: OpenAI-compatible backend URL
HERMES_API_URL=http://127.0.0.1:8642

# Optional: Dashboard API for enhanced features
HERMES_DASHBOARD_URL=http://127.0.0.1:9119

# Optional: Gateway authentication token
HERMES_API_TOKEN=your_api_server_key

# Optional: UI password protection
HERMES_PASSWORD=your_password

# Optional: Provider API keys (only if using these providers)
OPENAI_API_KEY=sk-...
OPENROUTER_API_KEY=sk-or-v1-...
GOOGLE_API_KEY=AIza...
ANTHROPIC_API_KEY=sk-ant-...

# Optional: Custom port
PORT=3000

Gateway Requirements

For full functionality, the Hermes Agent gateway needs:

bash

# In ~/.hermes/.env or gateway config
API_SERVER_ENABLED=true
API_SERVER_HOST=0.0.0.0
API_SERVER_PORT=8642

# Optional: Enable authentication
API_SERVER_KEY=your_secret_key

Start gateway and dashboard:

bash

hermes gateway run        # Port 8642
hermes dashboard          # Port 9119

Remote Access (Tailscale/VPN)

For access from remote devices:

bash

# Use Tailscale/LAN IP instead of localhost
echo 'HERMES_API_URL=http://100.x.y.z:8642' >> .env
echo 'HERMES_DASHBOARD_URL=http://100.x.y.z:9119' >> .env

# Gateway must bind to 0.0.0.0
echo 'API_SERVER_HOST=0.0.0.0' >> ~/.hermes/.env

Usage Patterns

Connecting to Local Models

Ollama

bash

# Start Ollama with CORS enabled
OLLAMA_ORIGINS=* ollama serve

# Start workspace pointing to Ollama
HERMES_API_URL=http://127.0.0.1:11434 pnpm dev

LM Studio

bash

# Start LM Studio server on port 1234
# In workspace:
HERMES_API_URL=http://127.0.0.1:1234/v1 pnpm dev

Atomic Chat

bash

# Start Atomic Chat desktop app
# In workspace:
HERMES_API_URL=http://127.0.0.1:1337/v1 pnpm dev

Swarm Mode Setup

Enable multi-agent orchestration:

bash

# Start multiple agent workers
cd ~/hermes-workspace
pnpm swarm:start

# View swarm docs
cat docs/swarm/README.md

# Configure roles in workspace UI:
# Settings → Swarm → Configure Roles
# - builder: Code implementation
# - reviewer: PR review and validation
# - docs: Documentation
# - research: Investigation
# - ops: Operations and deployment
# - triage: Issue classification
# - qa: Quality assurance
# - lab: Experiments

API Integration

For programmatic access:

typescript

// Next.js API route example
import { NextRequest, NextResponse } from 'next/server';

export async function POST(req: NextRequest) {
  const { message, sessionId } = await req.json();
  
  const response = await fetch(`${process.env.HERMES_API_URL}/v1/chat/completions`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.HERMES_API_TOKEN || ''}`
    },
    body: JSON.stringify({
      model: 'hermes-3',
      messages: [{ role: 'user', content: message }],
      stream: true
    })
  });
  
  return new NextResponse(response.body);
}

Custom Theme Configuration

Create or modify themes in

src/styles/themes

typescript

// src/styles/themes/custom.ts
export const customTheme = {
  name: 'custom',
  colors: {
    background: '#0a0a0a',
    foreground: '#ffffff',
    primary: '#6366f1',
    secondary: '#8b5cf6',
    accent: '#ec4899',
    muted: '#374151',
    border: '#1f2937'
  },
  fonts: {
    sans: 'Inter, system-ui, sans-serif',
    mono: 'JetBrains Mono, monospace'
  }
};

Docker Deployment

yaml

# docker-compose.yml
version: '3.8'

services:
  hermes-workspace:
    build: .
    ports:
      - "3000:3000"
    environment:
      - HERMES_API_URL=http://hermes-gateway:8642
      - HERMES_DASHBOARD_URL=http://hermes-gateway:9119
      - HERMES_API_TOKEN=${HERMES_API_TOKEN}
    depends_on:
      - hermes-gateway
    volumes:
      - ./data:/app/data

  hermes-gateway:
    image: nousresearch/hermes-agent:latest
    ports:
      - "8642:8642"
      - "9119:9119"
    environment:
      - API_SERVER_ENABLED=true
      - API_SERVER_HOST=0.0.0.0
      - API_SERVER_KEY=${HERMES_API_TOKEN}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    volumes:
      - ./hermes-data:/root/.hermes

Conductor Mission Dispatch

typescript

// Dispatching a mission programmatically
const dispatchMission = async (mission: string) => {
  const response = await fetch('/api/conductor/dispatch', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      mission,
      mode: 'auto', // or 'native-swarm'
      decompose: true
    })
  });
  
  const result = await response.json();
  return result;
};

// Example usage
await dispatchMission('Review and merge PR #42, update docs');

Key Commands

Development

bash

# Start development server
pnpm dev

# Build for production
pnpm build

# Start production server
pnpm start

# Run tests
pnpm test

# Lint code
pnpm lint

# Type check
pnpm type-check

Swarm Management

bash

# Start swarm workers
pnpm swarm:start

# Stop swarm workers
pnpm swarm:stop

# View swarm status
pnpm swarm:status

# Attach to worker terminal
pnpm swarm:attach <worker-name>

Docker

bash

# Build image
docker build -t hermes-workspace .

# Run container
docker run -p 3000:3000 \
  -e HERMES_API_URL=http://gateway:8642 \
  -e HERMES_DASHBOARD_URL=http://gateway:9119 \
  hermes-workspace

# Docker Compose
docker-compose up -d
docker-compose logs -f
docker-compose down

Troubleshooting

Connection Issues

bash

# Verify gateway is running
curl http://127.0.0.1:8642/health
# Expected: {"status":"ok"}

# Verify dashboard is running
curl http://127.0.0.1:9119/api/status
# Expected: dashboard metadata JSON

# Check gateway logs
hermes gateway run --verbose

# Check workspace logs
pnpm dev
# Look for connection probe results

Authentication Failures

bash

# Ensure API_SERVER_KEY matches HERMES_API_TOKEN
# In gateway config (~/.hermes/.env):
API_SERVER_KEY=your_secret

# In workspace .env:
HERMES_API_TOKEN=your_secret

# Or disable auth entirely:
# Remove API_SERVER_KEY from gateway
# Remove HERMES_API_TOKEN from workspace

Features Not Appearing

bash

# Check capability detection in browser console:
# Settings → Connection → Test Connection

# Verify dashboard is running for enhanced features:
ps aux | grep "hermes dashboard"

# Check HERMES_DASHBOARD_URL is set correctly:
echo $HERMES_DASHBOARD_URL

# Restart both services:
pkill -f "hermes gateway"
pkill -f "hermes dashboard"
hermes gateway run &
hermes dashboard &

Swarm Workers Not Starting

bash

# Check tmux sessions
tmux ls

# Verify worker processes
ps aux | grep hermes

# Check worker logs
tail -f ~/.hermes/logs/worker-*.log

# Reset swarm state
pnpm swarm:stop
rm -rf ~/.hermes/swarm-state
pnpm swarm:start

Memory/Performance Issues

bash

# Increase Node.js memory
NODE_OPTIONS="--max-old-space-size=4096" pnpm dev

# Clear workspace cache
rm -rf .next
pnpm build

# Check Docker resource limits
docker stats
# Increase in Docker Desktop settings if needed

Remote Access Not Working

bash

# Verify gateway binds to 0.0.0.0
grep API_SERVER_HOST ~/.hermes/.env
# Should be: API_SERVER_HOST=0.0.0.0

# Test from remote device
curl http://<tailscale-ip>:8642/health

# Check firewall rules
sudo ufw status
sudo ufw allow 8642/tcp
sudo ufw allow 9119/tcp

# Verify Tailscale connectivity
tailscale status
ping <tailscale-ip>

Build Errors

bash

# Clear all caches and reinstall
rm -rf node_modules .next pnpm-lock.yaml
pnpm install
pnpm build

# Verify Node.js version
node --version
# Must be 22.0.0 or higher

# Check for TypeScript errors
pnpm type-check

Advanced Configuration

Custom Skills Integration

bash

# Add custom skills directory
export HERMES_SKILLS_PATH=/path/to/custom/skills

# Skills should follow format:
# /custom/skills/
#   ├── skill-name/
#   │   ├── SKILL.md
#   │   └── metadata.json

Persistent Sessions

bash

# Sessions stored in ~/.hermes/sessions/
# Backup sessions:
tar -czf sessions-backup.tar.gz ~/.hermes/sessions/

# Restore sessions:
tar -xzf sessions-backup.tar.gz -C ~/

Custom API Routes

typescript

// app/api/custom/route.ts
import { NextRequest } from 'next/server';

export async function POST(req: NextRequest) {
  // Custom endpoint logic
  const data = await req.json();
  
  // Forward to gateway with custom headers
  const response = await fetch(`${process.env.HERMES_API_URL}/custom`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Custom-Header': 'value'
    },
    body: JSON.stringify(data)
  });
  
  return response;
}

Resources

GitHub: https://github.com/outsourc-e/hermes-workspace
Documentation: https://hermes-workspace.com
Hermes Agent: https://github.com/NousResearch/hermes-agent
Swarm Docs:
```
docs/swarm/README.md
```
in repository
Issues: https://github.com/outsourc-e/hermes-workspace/issues

hermes-workspace-ai-agent-ui

NPX Install

Tags

SKILL.md Content

Hermes Workspace AI Agent UI

What It Does

Installation

Docker Compose (Recommended for Self-Hosting)

One-Line Install (macOS/Linux)

Manual Installation

Attach to Existing Hermes Agent

Configuration

Environment Variables

Gateway Requirements

Remote Access (Tailscale/VPN)

Usage Patterns

Connecting to Local Models

Ollama

LM Studio

Atomic Chat

Swarm Mode Setup

API Integration

Custom Theme Configuration

Docker Deployment

Conductor Mission Dispatch

Key Commands

Development

Swarm Management

Docker

Troubleshooting

Connection Issues

Authentication Failures

Features Not Appearing

Swarm Workers Not Starting

Memory/Performance Issues

Remote Access Not Working

Build Errors

Advanced Configuration

Custom Skills Integration

Persistent Sessions

Custom API Routes

Resources