# Hermes Workspace
**Your AI agent's command center โ chat, files, memory, skills, and terminal in one place.**
[](CHANGELOG.md)
[](LICENSE)
[](https://nodejs.org/)
[](CONTRIBUTING.md)
> 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](https://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:
```bash
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
```bash
# 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
```env
# OpenAI-compatible backend URL
HERMES_API_URL=http://127.0.0.1:8642
# Optional provider keys for Hermes gateway-managed config
ANTHROPIC_API_KEY=your-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:
```bash
# 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`:**
```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`:**
```env
API_SERVER_ENABLED=true
```
**3. Start the gateway and workspace:**
```bash
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.
---
## ๐ณ Docker Quickstart
[](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=outsourc-e/hermes-workspace)
The Docker setup runs both the **Hermes Agent gateway** and **Hermes Workspace** together.
### Prerequisites
- **Docker**
- **Docker Compose**
- **Anthropic API Key** โ [Get one here](https://console.anthropic.com/settings/keys) (required for the agent gateway)
### Step 1: Configure Environment
```bash
git clone https://github.com/outsourc-e/hermes-workspace.git
cd hermes-workspace
cp .env.example .env
```
Edit `.env` and add your API key:
```env
ANTHROPIC_API_KEY=your-key-here
```
> **Important:** The `hermes-agent` container requires `ANTHROPIC_API_KEY` to function. Without it, the gateway will fail to authenticate.
### Step 2: Start the Services
```bash
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](https://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:**
```bash
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:
```bash
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:
```bash
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](#-local-models-ollama-lm-studio-vllm) above.
Also ensure Ollama is running with CORS enabled:
```bash
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:**
```bash
cat .env | grep ANTHROPIC_API_KEY
# Should show: ANTHROPIC_API_KEY=sk-ant-...
```
2. **View the agent container logs:**
```bash
docker compose logs hermes-agent
```
Look for startup errors or missing API key warnings.
3. **Verify the agent health endpoint:**
```bash
curl http://localhost:8642/health
# Should return: {"status": "ok"}
```
4. **Restart with fresh containers:**
```bash
docker compose down
docker compose up --build
```
5. **Check workspace logs for gateway status:**
```bash
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:
```bash
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
## [](https://www.star-history.com/#outsourc-e/hermes-workspace&type=date&logscale&legend=top-left)
## ๐ 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`
[](https://github.com/sponsors/outsourc-e)
Every contribution helps keep this project moving. Thank you ๐
---
## ๐ค Contributing
PRs are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
- Bug fixes โ open a PR directly
- New features โ open an issue first to discuss
- Security issues โ see [SECURITY.md](SECURITY.md) for responsible disclosure
---
## ๐ License
MIT โ see [LICENSE](LICENSE) for details.
---