{"id":48647917,"url":"https://github.com/outsourc-e/hermes-workspace","last_synced_at":"2026-04-20T06:14:43.257Z","repository":{"id":344879029,"uuid":"1182887460","full_name":"outsourc-e/hermes-workspace","owner":"outsourc-e","description":"Native web workspace for Hermes Agent — chat, terminal, memory, skills, inspector.","archived":false,"fork":false,"pushed_at":"2026-04-18T20:05:23.000Z","size":20579,"stargazers_count":1576,"open_issues_count":1,"forks_count":181,"subscribers_count":9,"default_branch":"main","last_synced_at":"2026-04-18T20:23:29.343Z","etag":null,"topics":["agent-ui","ai-workspace","hackathon","hermes-agent","nous-research","react","typescript"],"latest_commit_sha":null,"homepage":"https://hermes-workspace.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/outsourc-e.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-16T03:53:28.000Z","updated_at":"2026-04-18T18:27:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/outsourc-e/hermes-workspace","commit_stats":null,"previous_names":["outsourc-e/hermes-workspace"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/outsourc-e/hermes-workspace","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/outsourc-e%2Fhermes-workspace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/outsourc-e%2Fhermes-workspace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/outsourc-e%2Fhermes-workspace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/outsourc-e%2Fhermes-workspace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/outsourc-e","download_url":"https://codeload.github.com/outsourc-e/hermes-workspace/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/outsourc-e%2Fhermes-workspace/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32035369,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-20T00:18:06.643Z","status":"online","status_checked_at":"2026-04-20T02:00:06.527Z","response_time":94,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-ui","ai-workspace","hackathon","hermes-agent","nous-research","react","typescript"],"created_at":"2026-04-10T07:59:49.376Z","updated_at":"2026-04-20T06:14:43.249Z","avatar_url":"https://github.com/outsourc-e.png","language":"TypeScript","readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"./public/hermes-avatar.webp\" alt=\"Hermes Workspace\" width=\"80\" style=\"border-radius: 16px\" /\u003e\n\n# Hermes Workspace\n\n**Your AI agent's command center — chat, files, memory, skills, and terminal in one place.**\n\n[![Version](https://img.shields.io/badge/version-2.0.0-2557b7.svg)](CHANGELOG.md)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Node](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen.svg)](https://nodejs.org/)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-6366F1.svg)](CONTRIBUTING.md)\n\n\u003e Not a chat wrapper. A complete workspace — orchestrate agents, browse memory, manage skills, and control everything from one interface.\n\n\u003e **v2 — zero-fork. Clone, don't fork.** Runs on vanilla [`pip install hermes-agent`](https://github.com/NousResearch/hermes-agent). No patches, no drift. Upgrade any time with `pip install -U hermes-agent`.\n\n![Hermes Workspace](./docs/screenshots/splash.png)\n\n\u003c/div\u003e\n\n---\n\n## ✨ Features\n\n- 🤖 **Hermes Agent Integration** — Direct gateway connection with real-time SSE streaming\n- 🎨 **8-Theme System** — Official, Classic, Slate, Mono — each with light and dark variants\n- 🔒 **Security Hardened** — Auth middleware on all API routes, CSP headers, exec approval prompts\n- 📱 **Mobile-First PWA** — Full feature parity on any device via Tailscale\n- ⚡ **Live SSE Streaming** — Real-time agent output with tool call rendering\n- 🧠 **Memory \u0026 Skills** — Browse, search, and edit agent memory; explore 2,000+ skills\n\n---\n\n## 📸 Screenshots\n\n|                 Chat                 |                  Conductor                   |\n| :----------------------------------: | :------------------------------------------: |\n| ![Chat](./docs/screenshots/chat.png) | ![Conductor](./docs/screenshots/conductor.png) |\n\n|                   Dashboard                  |                  Memory                  |\n| :------------------------------------------: | :--------------------------------------: |\n| ![Dashboard](./docs/screenshots/dashboard.png) | ![Memory](./docs/screenshots/memory.png) |\n\n|                   Terminal                   |                   Settings                   |\n| :------------------------------------------: | :------------------------------------------: |\n| ![Terminal](./docs/screenshots/terminal.png) | ![Settings](./docs/screenshots/settings.png) |\n\n|                  Tasks                  |                 Jobs                 |\n| :--------------------------------------: | :----------------------------------: |\n| ![Tasks](./docs/screenshots/tasks.png) | ![Jobs](./docs/screenshots/jobs.png) |\n\n---\n\n## 🚀 Quick Start\n\n### One-line install (recommended)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/outsourc-e/hermes-workspace/main/install.sh | bash\n```\n\nThis installs `hermes-agent` from PyPI, clones this repo, sets up `.env`, and installs deps. Then:\n\n```bash\nhermes gateway run                  # terminal 1\ncd ~/hermes-workspace \u0026\u0026 pnpm dev   # terminal 2\n```\n\nOpen http://localhost:3000. That's it.\n\n---\n\n### Manual install\n\nHermes 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.\n\n#### Prerequisites\n\n- **Node.js 22+** — [nodejs.org](https://nodejs.org/)\n- **An OpenAI-compatible backend** — local, self-hosted, or remote\n- **Optional:** Python 3.11+ if you want to run a Hermes gateway locally\n\n#### Step 1: Start your backend\n\nPoint Hermes Workspace at any backend that supports:\n\n- `POST /v1/chat/completions`\n- `GET /v1/models` recommended\n\nExample Hermes gateway setup:\n\n```bash\npython -m venv .venv\nsource .venv/bin/activate   # Windows: .venv\\Scripts\\activate\npip install hermes-agent\nhermes setup\nhermes gateway run\n```\n\nIf you're using another OpenAI-compatible server, just note its base URL.\n\n### Step 2: Install \u0026 Run Hermes Workspace\n\n```bash\n# In a new terminal\ngit clone https://github.com/outsourc-e/hermes-workspace.git\ncd hermes-workspace\npnpm install\ncp .env.example .env\nprintf '\\nHERMES_API_URL=http://127.0.0.1:8642\\n' \u003e\u003e .env\npnpm dev                   # Starts on http://localhost:3000\n```\n\n\u003e **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.\n\n#### Environment Variables\n\n```env\n# OpenAI-compatible backend URL\nHERMES_API_URL=http://127.0.0.1:8642\n\n# Optional provider keys for Hermes gateway-managed config\nANTHROPIC_API_KEY=your-key-here\n\n# Optional: password-protect the web UI\n# HERMES_PASSWORD=your_password\n```\n\n---\n\n## 🧠 Local Models (Ollama, Atomic Chat, LM Studio, vLLM)\n\nHermes Workspace supports two modes with local models:\n\n### Portable Mode (Easiest)\n\nPoint the workspace directly at your local server — no Hermes gateway needed.\n\n### Atomic Chat\n\n```bash\n# Start workspace pointed at Atomic Chat\nHERMES_API_URL=http://127.0.0.1:1337/v1 pnpm dev\n```\n\nDownload [Atomic Chat](https://atomic.chat/), launch the desktop app, and make sure a model is loaded before starting Hermes Workspace.\n\n### Ollama\n\n```bash\n# Start Ollama\nOLLAMA_ORIGINS=* ollama serve\n\n# Start workspace pointed at Ollama\nHERMES_API_URL=http://127.0.0.1:11434 pnpm dev\n```\n\nChat works immediately. Sessions, memory, and skills show \"Not Available\" — that's expected in portable mode.\n\n### Enhanced Mode (Full Features)\n\nRoute through the Hermes gateway for sessions, memory, skills, jobs, and tools.\n\nHere are two explicit `~/.hermes/config.yaml` examples for the local providers we support directly in the workspace:\n\n**Atomic Chat**\n\n```yaml\nprovider: atomic-chat\nmodel: your-model-name\ncustom_providers:\n  - name: atomic-chat\n    base_url: http://127.0.0.1:1337/v1\n    api_key: atomic-chat\n    api_mode: chat_completions\n```\n\n**Ollama**\n\n```yaml\nprovider: ollama\nmodel: qwen3:32b\ncustom_providers:\n  - name: ollama\n    base_url: http://127.0.0.1:11434/v1\n    api_key: ollama\n    api_mode: chat_completions\n```\n\nYou can adapt the same shape for other OpenAI-compatible local runners, but `Atomic Chat` and `Ollama` are the two built-in local paths documented in the workspace UI.\n\n**2. Enable the API server in `~/.hermes/.env`:**\n\n```env\nAPI_SERVER_ENABLED=true\n```\n\n**3. Start the gateway and workspace:**\n\n```bash\nhermes gateway run          # Starts on :8642\nHERMES_API_URL=http://127.0.0.1:8642 pnpm dev\n```\n\nAll workspace features unlock automatically — sessions persist, memory saves across chats, skills are available, and the dashboard shows real usage data.\n\n\u003e **Works with any OpenAI-compatible server** — Atomic Chat, Ollama, LM Studio, vLLM, llama.cpp, LocalAI, etc. Just change the `base_url` and `model` in the config above.\n\n---\n\n## 🐳 Docker Quickstart\n\n[![Open in GitHub Codespaces](https://img.shields.io/badge/GitHub%20Codespaces-Open-181717?logo=github)](https://github.com/codespaces/new?hide_repo_select=true\u0026ref=main\u0026repo=outsourc-e/hermes-workspace)\n\nThe Docker setup runs both the **Hermes Agent gateway** and **Hermes Workspace** together.\n\n### Prerequisites\n\n- **Docker**\n- **Docker Compose**\n- **Anthropic API Key** — [Get one here](https://console.anthropic.com/settings/keys) (required for the agent gateway)\n\n### Step 1: Configure Environment\n\n```bash\ngit clone https://github.com/outsourc-e/hermes-workspace.git\ncd hermes-workspace\ncp .env.example .env\n```\n\nEdit `.env` and add your API key:\n\n```env\nANTHROPIC_API_KEY=your-key-here\n```\n\n\u003e **Important:** The `hermes-agent` container requires `ANTHROPIC_API_KEY` to function. Without it, the gateway will fail to authenticate.\n\n### Step 2: Start the Services\n\n```bash\ndocker compose up\n```\n\nThis starts two services:\n\n- **hermes-agent** — The AI agent gateway (port 8642)\n- **hermes-workspace** — The web UI (port 3000)\n\n### Step 3: Access the Workspace\n\nOpen `http://localhost:3000` and complete the onboarding.\n\n\u003e **Verify:** Check the Docker logs for `[gateway] Connected to Hermes` — this confirms the workspace successfully connected to the agent.\n\n---\n\n## 📱 Install as App (Recommended)\n\nHermes Workspace is a **Progressive Web App (PWA)** — install it for the full native app experience with no browser chrome, keyboard shortcuts, and offline support.\n\n### 🖥️ Desktop (macOS / Windows / Linux)\n\n1. Open Hermes Workspace in **Chrome** or **Edge** at `http://localhost:3000`\n2. Click the **install icon** (⊕) in the address bar\n3. Click **Install** — Hermes Workspace opens as a standalone desktop app\n4. Pin to Dock / Taskbar for quick access\n\n\u003e **macOS users:** After installing, you can also add it to your Launchpad.\n\n### 📱 iPhone / iPad (iOS Safari)\n\n1. Open Hermes Workspace in **Safari** on your iPhone\n2. Tap the **Share** button (□↑)\n3. Scroll down and tap **\"Add to Home Screen\"**\n4. Tap **Add** — the Hermes Workspace icon appears on your home screen\n5. Launch from home screen for the full native app experience\n\n### 🤖 Android\n\n1. Open Hermes Workspace in **Chrome** on your Android device\n2. Tap the **three-dot menu** (⋮) → **\"Add to Home screen\"**\n3. Tap **Add** — Hermes Workspace is now a native-feeling app on your device\n\n---\n\n## 📡 Mobile Access via Tailscale\n\nAccess Hermes Workspace from anywhere on your devices — no port forwarding, no VPN complexity.\n\n### Setup\n\n1. **Install Tailscale** on your Mac and mobile device:\n   - Mac: [tailscale.com/download](https://tailscale.com/download)\n   - iPhone/Android: Search \"Tailscale\" in the App Store / Play Store\n\n2. **Sign in** to the same Tailscale account on both devices\n\n3. **Find your Mac's Tailscale IP:**\n\n   ```bash\n   tailscale ip -4\n   # Example output: 100.x.x.x\n   ```\n\n4. **Open Hermes Workspace on your phone:**\n\n   ```\n   http://100.x.x.x:3000\n   ```\n\n5. **Add to Home Screen** using the steps above for the full app experience\n\n\u003e 💡 Tailscale works over any network — home wifi, mobile data, even across countries. Your traffic stays end-to-end encrypted.\n\n---\n\n## 🖥️ Native Desktop App\n\n\u003e **Status: In Development** — A native Electron-based desktop app is in active development.\n\nThe desktop app will offer:\n\n- Native window management and tray icon\n- System notifications for agent events and mission completions\n- Auto-launch on startup\n- Deep OS integration (macOS menu bar, Windows taskbar)\n\n**In the meantime:** Install Hermes Workspace as a PWA (see above) for a near-native desktop experience — it works great.\n\n---\n\n## ☁️ Cloud \u0026 Hosted Setup\n\n\u003e **Status: Coming Soon**\n\nA fully managed cloud version of Hermes Workspace is in development:\n\n- **One-click deploy** — No self-hosting required\n- **Multi-device sync** — Access your agents from any device\n- **Team collaboration** — Shared mission control for your whole team\n- **Automatic updates** — Always on the latest version\n\nFeatures pending cloud infrastructure:\n\n- Cross-device session sync\n- Team shared memory and workspaces\n- Cloud-hosted backend with managed uptime\n- Webhook integrations and external triggers\n\n---\n\n## ✨ Features\n\n### 💬 Chat\n\n- Real-time SSE streaming with tool call rendering\n- Agent-authored artifact events surfaced in the inspector\n- Multi-session management with full history\n- Markdown + syntax highlighting\n- Chronological message ordering with merge dedup\n- Inspector panel for session activity, memory, and skills\n\n### 🧠 Memory\n\n- Browse and edit agent memory files\n- Search across memory entries\n- Markdown preview with live editing\n\n### 🧩 Skills\n\n- Browse 2,000+ skills from the registry\n- View skill details, categories, and documentation\n- Skill management per session\n\n### 📁 Files\n\n- Full workspace file browser\n- Navigate directories, preview and edit files\n- Monaco editor integration\n\n### 💻 Terminal\n\n- Full PTY terminal with cross-platform support\n- Persistent shell sessions\n- Direct workspace access\n\n### 🎨 Themes\n\n- 8 themes: Official, Classic, Slate, Mono — each with light and dark variants\n- Theme persists across sessions\n- Full mobile dark mode support\n\n### 🔒 Security\n\n- Auth middleware on all API routes\n- CSP headers via meta tags\n- Path traversal prevention on file/memory routes\n- Rate limiting on endpoints\n- Optional password protection for web UI\n\n---\n\n## 🔧 Troubleshooting\n\n### \"Workspace loads but chat doesn't work\"\n\nThe workspace auto-detects your gateway's capabilities on startup. Check your terminal for a line like:\n\n```\n[gateway] http://127.0.0.1:8642 available: health, models; missing: sessions, skills, memory, config, jobs\n[gateway] Missing Hermes APIs detected. Update Hermes: pip install -U hermes-agent \u0026\u0026 hermes gateway run\n```\n\n**Fix:** Upgrade to the latest stock `hermes-agent`, which now ships the extended endpoints:\n\n```bash\npip install -U hermes-agent\nhermes gateway run\n```\n\nIf you were on the old `outsourc-e/hermes-agent` fork, it's no longer needed as of v2 — uninstall it and install upstream instead.\n\n### \"Connection refused\" or workspace hangs on load\n\nYour Hermes gateway isn't running. Start it:\n\n```bash\ncd hermes-agent\nsource .venv/bin/activate\nhermes gateway run\n```\n\n### Ollama: chat returns empty or model shows \"Offline\"\n\nMake 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.\n\nAlso ensure Ollama is running with CORS enabled:\n\n```bash\nOLLAMA_ORIGINS=* ollama serve\n```\n\nUse `http://127.0.0.1:11434/v1` (not `localhost`) as the base URL.\n\nVerify: `curl http://localhost:8642/health` should return `{\"status\": \"ok\"}`.\n\n### \"Using upstream NousResearch/hermes-agent\"\n\nv2+ runs on vanilla `hermes-agent` with full feature parity. `pip install -U hermes-agent` gets you the extended endpoints (sessions, memory, skills, config). **No fork required, ever.**\n\nIf you're pinned to an older `hermes-agent` version and missing endpoints, the workspace will degrade gracefully to **portable mode** with basic chat — upgrade upstream to restore full features.\n\n### Docker: \"Unauthorized\" or \"Connection refused\" to hermes-agent\n\nIf using Docker Compose and getting auth errors:\n\n1. **Check your API key is set:**\n\n   ```bash\n   cat .env | grep ANTHROPIC_API_KEY\n   # Should show: ANTHROPIC_API_KEY=sk-ant-...\n   ```\n\n2. **View the agent container logs:**\n\n   ```bash\n   docker compose logs hermes-agent\n   ```\n\n   Look for startup errors or missing API key warnings.\n\n3. **Verify the agent health endpoint:**\n\n   ```bash\n   curl http://localhost:8642/health\n   # Should return: {\"status\": \"ok\"}\n   ```\n\n4. **Restart with fresh containers:**\n\n   ```bash\n   docker compose down\n   docker compose up --build\n   ```\n\n5. **Check workspace logs for gateway status:**\n   ```bash\n   docker compose logs hermes-workspace\n   ```\n   Look for: `[gateway] http://hermes-agent:8642 mode=...` — if it shows `mode=disconnected`, the agent isn't running correctly.\n\n### Docker: \"hermes webapi command not found\"\n\nThe `hermes webapi` command referenced in older docs doesn't exist. The correct command is:\n\n```bash\nhermes --gateway   # Starts the FastAPI gateway server\n```\n\nThe Docker setup uses `hermes --gateway` automatically — no action needed if using `docker compose up`.\n\n---\n\n## 🗺️ Roadmap\n\n| Feature                       | Status            |\n| ----------------------------- | ----------------- |\n| Chat + SSE Streaming          | ✅ Shipped        |\n| Files + Terminal              | ✅ Shipped        |\n| Memory Browser                | ✅ Shipped        |\n| Skills Browser                | ✅ Shipped        |\n| Mobile PWA + Tailscale        | ✅ Shipped        |\n| 8-Theme System                | ✅ Shipped        |\n| Native Desktop App (Electron) | 🔨 In Development |\n| Model Switching \u0026 Config      | 🔨 In Development |\n| Chat Abort / Cancel           | 🔨 In Development |\n| Cloud / Hosted Version        | 🔜 Coming Soon    |\n| Team Collaboration            | 🔜 Coming Soon    |\n\n---\n\n## ⭐ Star History\n\n## [![Star History Chart](https://api.star-history.com/svg?repos=outsourc-e/hermes-workspace\u0026type=date\u0026logscale\u0026legend=top-left)](https://www.star-history.com/#outsourc-e/hermes-workspace\u0026type=date\u0026logscale\u0026legend=top-left)\n\n## 💛 Support the Project\n\nHermes Workspace is free and open source. If it's saving you time and powering your workflow, consider supporting development:\n\n**ETH:** `0xB332D4C60f6FBd94913e3Fd40d77e3FE901FAe22`\n\n[![GitHub Sponsors](https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink?logo=github)](https://github.com/sponsors/outsourc-e)\n\nEvery contribution helps keep this project moving. Thank you 🙏\n\n---\n\n## 🤝 Contributing\n\nPRs are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n- Bug fixes → open a PR directly\n- New features → open an issue first to discuss\n- Security issues → see [SECURITY.md](SECURITY.md) for responsible disclosure\n\n---\n\n## 📄 License\n\nMIT — see [LICENSE](LICENSE) for details.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n  \u003csub\u003eBuilt with ⚡ by \u003ca href=\"https://github.com/outsourc-e\"\u003e@outsourc-e\u003c/a\u003e and the Hermes Workspace community\u003c/sub\u003e\n\u003c/div\u003e\n","funding_links":["https://github.com/sponsors/outsourc-e"],"categories":["Quick Start Path"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foutsourc-e%2Fhermes-workspace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foutsourc-e%2Fhermes-workspace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foutsourc-e%2Fhermes-workspace/lists"}