name	hermes-workspace-ai-agent-ui
description	Native web workspace for Hermes Agent with chat, terminal, memory, skills, inspector, and multi-agent orchestration
triggers	set up hermes workspace, configure hermes agent ui, connect workspace to hermes gateway, enable swarm mode for multiple agents, customize hermes workspace theme, troubleshoot hermes workspace connection, deploy hermes workspace with docker, configure conductor missions

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)

# 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)

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

# 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:

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

# 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:

# 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:

hermes gateway run        # Port 8642
hermes dashboard          # Port 9119

Remote Access (Tailscale/VPN)

For access from remote devices:

# 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

# 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

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

Atomic Chat

# 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:

# 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:

// 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:

// 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

# 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

// 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

// 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