Hermes Workspace

Your AI agent's command center — chat, files, memory, skills, and terminal in one place.

Not a chat wrapper. A complete workspace — orchestrate agents, browse memory, manage skills, and control everything from one interface.

---

✨ Features

• 🤖 Hermes Agent Integration — Direct gateway connection with real-time SSE streaming
• 🎨 8-Theme System — Official, Classic, Slate, Mono — each with light and dark variants
• 🔒 Security Hardened — Auth middleware on all API routes, CSP headers, exec approval prompts
• 📱 Mobile-First PWA — Full feature parity on any device via Tailscale
• ⚡ Live SSE Streaming — Real-time agent output with tool call rendering
• 🧠 Memory & Skills — Browse, search, and edit agent memory; explore 2,000+ skills

---

📸 Screenshots

Chat	Files

Terminal	Memory

Skills	Settings

---

🚀 Quick Start

Hermes Workspace works with any OpenAI-compatible backend. If your backend also exposes Hermes gateway APIs, enhanced features like sessions, memory, skills, and jobs unlock automatically.

Prerequisites

• Node.js 22+ — nodejs.org
• An OpenAI-compatible backend — local, self-hosted, or remote
• Optional: Python 3.11+ if you want to run a Hermes gateway locally

Step 1: Start your backend

Point Hermes Workspace at any backend that supports:

• POST /v1/chat/completions
• GET /v1/models recommended

Example Hermes gateway setup:

git clone https://github.com/outsourc-e/hermes-agent.git
cd hermes-agent
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .
hermes setup
hermes --gateway

If you're using another OpenAI-compatible server, just note its base URL.

Step 2: Install & Run Hermes Workspace

# In a new terminal
git clone https://github.com/outsourc-e/hermes-workspace.git
cd hermes-workspace
pnpm install
cp .env.example .env
printf '\nHERMES_API_URL=http://127.0.0.1:8642\n' >> .env
pnpm dev                   # Starts on http://localhost:3000

Verify: Open http://localhost:3000 and complete the onboarding flow. First connect the backend, then verify chat works. If your gateway exposes Hermes APIs, advanced features appear automatically.

Environment Variables

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

# Gemini API key (recommended — free tier available at https://aistudio.google.com/apikey)
GOOGLE_API_KEY=your-gemini-api-key-here

# Optional: Anthropic key (if you also want Claude models)
# ANTHROPIC_API_KEY=your-anthropic-key-here

# Optional: password-protect the web UI
# HERMES_PASSWORD=your_password

---

🧠 Local Models (Ollama, LM Studio, vLLM)

Hermes Workspace supports two modes with local models:

Portable Mode (Easiest)

Point the workspace directly at your local server — no Hermes gateway needed:

# Start Ollama
OLLAMA_ORIGINS=* ollama serve

# Start workspace pointed at Ollama
HERMES_API_URL=http://127.0.0.1:11434 pnpm dev

Chat works immediately. Sessions, memory, and skills show "Not Available" — that's expected in portable mode.

Enhanced Mode (Full Features)

Route through the Hermes gateway for sessions, memory, skills, jobs, and tools:

1. Configure your local model in ~/.hermes/config.yaml:

provider: ollama
model: qwen2.5:7b  # or any model you have pulled
custom_providers:
  - name: ollama
    base_url: http://127.0.0.1:11434/v1
    api_key: ollama
    api_mode: chat_completions

2. Enable the API server in ~/.hermes/.env:

API_SERVER_ENABLED=true

3. Start the gateway and workspace:

hermes gateway run          # Starts on :8642
HERMES_API_URL=http://127.0.0.1:8642 pnpm dev

All workspace features unlock automatically — sessions persist, memory saves across chats, skills are available, and the dashboard shows real usage data.

Works with any OpenAI-compatible server — Ollama, LM Studio, vLLM, llama.cpp, LocalAI, etc. Just change the base_url and model in the config above.

---

☁️ Deploy to Vercel

✅ No local installation required. Everything runs inside Vercel — just click the button below, paste your backend URL, and you're live.

Vercel forks the repo and builds it automatically. You only need to fill in one variable:

Variable	Description
HERMES_API_URL	Public URL of your Hermes Agent backend, e.g. https://your-vps-ip-or-domain:8642

Heads-up: Vercel hosts the frontend only. The Hermes Agent backend must be running somewhere accessible (e.g. your Ubuntu VPS — see below). Terminal and workspace-daemon features also require a persistent server; use the Ubuntu VPS or Docker path for those.

---

🖥️ Ubuntu VPS — Self-Hosted

Run the full stack (frontend + agent) on any Ubuntu 22.04/24.04 VPS in one shot. No local installation needed — run these commands directly on the server.

Prerequisites

• Ubuntu 22.04 or 24.04 VPS (1 GB RAM minimum, 2 GB recommended)
• A Google Gemini API key — get one free here (no credit card required)

One-command setup

# 1. Install Docker & Docker Compose (skip if already installed)
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER && newgrp docker

# 2. Clone the workspace
git clone https://github.com/Primosphered/hermes-workspace.git
cd hermes-workspace

# 3. Configure your API key
cp .env.example .env
sed -i 's/your-gemini-api-key-here/YOUR_GEMINI_KEY/' .env

# 4. Start everything
docker compose up -d

Replace YOUR_GEMINI_KEY with your real key (format: AIza...), or open .env in a text editor (nano .env) and paste it there.

Access the workspace

http://<your-vps-ip>:3000

Service	Port
Hermes Workspace (UI)	3000
Hermes Agent (API)	8642

Firewall: open ports 3000 and 8642 in your VPS security group / ufw (sudo ufw allow 3000/tcp && sudo ufw allow 8642/tcp).

Keep it running after reboot

Both containers use restart: unless-stopped — they start automatically when Docker starts (i.e. on reboot). No extra steps needed.

To restart manually at any time:

docker compose restart

Pair with Vercel

Once the VPS is running, copy http://<your-vps-ip>:8642 and paste it as HERMES_API_URL when you click the Vercel deploy button above. The Vercel frontend will connect to your VPS backend.

---

🐳 Docker Quickstart

The Docker setup runs both the Hermes Agent gateway and Hermes Workspace together.

Prerequisites

• Docker
• Docker Compose
• Google Gemini API Key — Get one free here (no credit card required)

Step 1: Configure Environment

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

Edit .env and add your Gemini API key:

GOOGLE_API_KEY=AIza-your-key-here

Note: The hermes-agent container uses GOOGLE_API_KEY for Gemini by default. You can also add ANTHROPIC_API_KEY if you want Claude models available too.

Step 2: Start the Services

docker compose up

This starts two services:

• hermes-agent — The AI agent gateway (port 8642)
• hermes-workspace — The web UI (port 3000)

Step 3: Access the Workspace

Open http://localhost:3000 and complete the onboarding.

Verify: Check the Docker logs for [gateway] Connected to Hermes — this confirms the workspace successfully connected to the agent.

---

📱 Install as App (Recommended)

Hermes Workspace is a Progressive Web App (PWA) — install it for the full native app experience with no browser chrome, keyboard shortcuts, and offline support.

🖥️ Desktop (macOS / Windows / Linux)

1. Open Hermes Workspace in Chrome or Edge at http://localhost:3000
2. Click the install icon (⊕) in the address bar
3. Click Install — Hermes Workspace opens as a standalone desktop app
4. Pin to Dock / Taskbar for quick access

macOS users: After installing, you can also add it to your Launchpad.

📱 iPhone / iPad (iOS Safari)

1. Open Hermes Workspace in Safari on your iPhone
2. Tap the Share button (□↑)
3. Scroll down and tap "Add to Home Screen"
4. Tap Add — the Hermes Workspace icon appears on your home screen
5. Launch from home screen for the full native app experience

🤖 Android

1. Open Hermes Workspace in Chrome on your Android device
2. Tap the three-dot menu (⋮) → "Add to Home screen"
3. Tap Add — Hermes Workspace is now a native-feeling app on your device

---

📡 Mobile Access via Tailscale

Access Hermes Workspace from anywhere on your devices — no port forwarding, no VPN complexity.

Setup

1. Install Tailscale on your Mac and mobile device:

   • Mac: tailscale.com/download
   • iPhone/Android: Search "Tailscale" in the App Store / Play Store

2. Sign in to the same Tailscale account on both devices

3. Find your Mac's Tailscale IP:

   tailscale ip -4
   # Example output: 100.x.x.x

4. Open Hermes Workspace on your phone:

   http://100.x.x.x:3000
   

5. Add to Home Screen using the steps above for the full app experience

💡 Tailscale works over any network — home wifi, mobile data, even across countries. Your traffic stays end-to-end encrypted.

---

🖥️ Native Desktop App

Status: In Development — A native Electron-based desktop app is in active development.

The desktop app will offer:

• Native window management and tray icon
• System notifications for agent events and mission completions
• Auto-launch on startup
• Deep OS integration (macOS menu bar, Windows taskbar)

In the meantime: Install Hermes Workspace as a PWA (see above) for a near-native desktop experience — it works great.

---

☁️ Cloud & Hosted Setup

Status: Coming Soon

A fully managed cloud version of Hermes Workspace is in development:

• One-click deploy — No self-hosting required
• Multi-device sync — Access your agents from any device
• Team collaboration — Shared mission control for your whole team
• Automatic updates — Always on the latest version

Features pending cloud infrastructure:

• Cross-device session sync
• Team shared memory and workspaces
• Cloud-hosted backend with managed uptime
• Webhook integrations and external triggers

---

✨ Features

💬 Chat

• Real-time SSE streaming with tool call rendering
• Multi-session management with full history
• Markdown + syntax highlighting
• Chronological message ordering with merge dedup
• Inspector panel for session activity, memory, and skills

🧠 Memory

• Browse and edit agent memory files
• Search across memory entries
• Markdown preview with live editing

🧩 Skills

• Browse 2,000+ skills from the registry
• View skill details, categories, and documentation
• Skill management per session

📁 Files

• Full workspace file browser
• Navigate directories, preview and edit files
• Monaco editor integration

💻 Terminal

• Full PTY terminal with cross-platform support
• Persistent shell sessions
• Direct workspace access

🎨 Themes

• 8 themes: Official, Classic, Slate, Mono — each with light and dark variants
• Theme persists across sessions
• Full mobile dark mode support

🔒 Security

• Auth middleware on all API routes
• CSP headers via meta tags
• Path traversal prevention on file/memory routes
• Rate limiting on endpoints
• Optional password protection for web UI

---

🔧 Troubleshooting

"Workspace loads but chat doesn't work"

The workspace auto-detects your gateway's capabilities on startup. Check your terminal for a line like:

[gateway] http://127.0.0.1:8642 available: health, models; missing: sessions, skills, memory, config, jobs
[gateway] Missing Hermes APIs detected. Update Hermes: cd hermes-agent && git pull && pip install -e . && hermes --gateway

Fix: Use our fork which includes extended gateway endpoints:

git clone https://github.com/outsourc-e/hermes-agent.git
cd hermes-agent && pip install -e . && hermes --gateway

"Connection refused" or workspace hangs on load

Your Hermes gateway isn't running. Start it:

cd hermes-agent
source .venv/bin/activate
hermes gateway run

Ollama: chat returns empty or model shows "Offline"

Make sure your ~/.hermes/config.yaml has the custom_providers section and API_SERVER_ENABLED=true in ~/.hermes/.env. See Local Models above.

Also ensure Ollama is running with CORS enabled:

OLLAMA_ORIGINS=* ollama serve

Use http://127.0.0.1:11434/v1 (not localhost) as the base URL.

Verify: curl http://localhost:8642/health should return {"status": "ok"}.

"Using upstream NousResearch/hermes-agent"

The upstream hermes-agent supports basic chat via hermes --gateway, but doesn't include extended endpoints (sessions, memory, skills, config) yet. The workspace will work in portable mode with basic chat. For full features, use our fork (outsourc-e/hermes-agent).

Docker: "Unauthorized" or "Connection refused" to hermes-agent

If using Docker Compose and getting auth errors:

1. Check your API key is set:

   cat .env | grep GOOGLE_API_KEY
   # Should show: GOOGLE_API_KEY=AIza...

2. View the agent container logs:

   docker compose logs hermes-agent

   Look for startup errors or missing API key warnings.

3. Verify the agent health endpoint:

   curl http://localhost:8642/health
   # Should return: {"status": "ok"}

4. Restart with fresh containers:

   docker compose down
   docker compose up --build

5. Check workspace logs for gateway status:

   docker compose logs hermes-workspace

   Look for: [gateway] http://hermes-agent:8642 mode=... — if it shows mode=disconnected, the agent isn't running correctly.

Docker: "hermes webapi command not found"

The hermes webapi command referenced in older docs doesn't exist. The correct command is:

hermes --gateway   # Starts the FastAPI gateway server

The Docker setup uses hermes --gateway automatically — no action needed if using docker compose up.

---

🗺️ Roadmap

Feature	Status
Chat + SSE Streaming	✅ Shipped
Files + Terminal	✅ Shipped
Memory Browser	✅ Shipped
Skills Browser	✅ Shipped
Mobile PWA + Tailscale	✅ Shipped
8-Theme System	✅ Shipped
Native Desktop App (Electron)	🔨 In Development
Model Switching & Config	🔨 In Development
Chat Abort / Cancel	🔨 In Development
Cloud / Hosted Version	🔜 Coming Soon
Team Collaboration	🔜 Coming Soon

---

⭐ Star History

💛 Support the Project

Hermes Workspace is free and open source. If it's saving you time and powering your workflow, consider supporting development:

ETH: 0xB332D4C60f6FBd94913e3Fd40d77e3FE901FAe22

Every contribution helps keep this project moving. Thank you 🙏

---

🤝 Contributing

PRs are welcome! See CONTRIBUTING.md for guidelines.

• Bug fixes → open a PR directly
• New features → open an issue first to discuss
• Security issues → see SECURITY.md for responsible disclosure

---

📄 License

MIT — see LICENSE for details.

---

_{Built with ⚡ by @outsourc-e and the Hermes Workspace community}