Addresses #514 by documenting the env vars needed for LAN/Tailscale
deployments (HERMES_PASSWORD, COOKIE_SECURE, API_SERVER_KEY,
GATEWAY_ALLOW_ALL_USERS) and providing a docker-compose.override.yml
example for publishing ports without loopback binding.
Added troubleshooting table for common Docker startup errors.
Co-authored-by: Aurora <myaurora.agi@gmail.com>
* fix(start): use server-entry wrapper for production
* fix(swarm): reconcile oneshot checkpoints and ignore phantom blockers
* fix(profiles): sync editable descriptions from profile config
* fix: show cron jobs across Hermes profiles
* fix(capabilities): clarify dashboard-backed API detection
* feat: make Conductor use native Swarm fallback
Treat Workspace-native Swarm as the official Conductor fallback when the dashboard mission API is unavailable. Preserve dashboard-first dispatch, native status/cancel handling, provider-neutral setup docs, and regression coverage for gateway capability detection, swarm health, roster/profile handling, and native Conductor responses.
* fix(usage-meter): reposition menu trigger for better alignment
- Adjusted the position of the menu trigger in the usage meter component to enhance layout consistency and user experience.
fix(chat-panel): adjust position of chat panel toggle button
- Updated the positioning of the chat panel toggle button to improve visibility and accessibility by changing its bottom and right offsets.
* fix(stt): wire Groq/OpenAI voice transcription into chat
* Fix Workspace Kanban loopback dashboard link
* fix(update): do not open historical release notes on startup
* fix(chat): clear stale thinking runs reliably
* fix(dashboard): trust sessions endpoint for status
* fix(settings): address review — local default, OAuth lifecycle, validation
* fix(dashboard): always scrape live session token from HTML
* fix(chat): avoid portable history replay on bound sessions
* fix(settings): remove dead smart routing controls
* fix(tasks-api): guard against HTML catch-all in probeBackend
The /api/hermes-tasks route was renamed to /api/claude-tasks in commit
efcb7d14, but the probe logic still listed the old route as a candidate.
When probed, the SPA catch-all returned a 200 HTML response instead of
a 404, so probeBackend() treated it as a valid (empty) backend and then
failed when the actual task fetch threw.
Fixes:
- probeBackend() now checks Content-Type: application/json and returns
-1 for non-JSON responses, so future route renames degrade gracefully.
- resolveBackend() now only selects hermes if hermesCount > 0, defaulting
to claude-tasks (the active backend post rename) when hermes is absent.
* fix(terminal): default cwd to ~ and fallback if path missing
PTY helper chdir fails when ~/.hermes is absent (common in Docker).
Default shell cwd to home; server falls back to HOME if cwd does not exist.
Co-authored-by: Cursor <cursoragent@cursor.com>
* fix(settings): satisfy lint on custom providers UI
* fix(docker): add -m flag to useradd so workspace home dir is created
Without -m, the system account has no /home/workspace directory.
The auth middleware tries to write the session store at
/home/workspace/.hermes/workspace-sessions.json; mkdirSync fails with
EACCES because /home/ is root-owned (755), causing the 'Failed to
persist session store' warning and a 500 on every authenticated route.
Adding -m causes useradd to create and chown /home/workspace correctly
so the session store can be written on first login.
* fix(tasks): preserve real session links and restore task launch flow
* fix(launchd): install macOS plist from server-entry template
* fix(docker): expose dashboard API and persist workspace volumes
* fix(jobs): serialize deliver targets for cron API
* Make Hermes Workspace installable as PWA
* chore(deps): pin direct tanstack versions
* feat: align semantic Hermes swarm agents
Add semantic swarm roster metadata, profile/tool/skill docs, shared semantic worker ID validation, focused roster regression coverage, and one-shot checkpoint capture for dispatch smoke tests.
* fix(conductor): pass through sessionKeyPrefix from portable spawn result
sessionKeyPrefix was hardcoded to null in conductor-spawn.ts, breaking
async session resolution when the dashboard backend returns a prefix.
Now mirrors the sessionKey pattern and passes through the value from
the spawn result.
Co-authored-by: Hermes Agent
* feat(swarm): bridge workspace kanban to native Hermes
* fix(chat): keep portable main pinned without breaking resolved sessions
* Add Windows startup script for Hermes Workspace
Document PowerShell usage for launching and restarting gateway + workspace via WSL tmux.
Co-Authored-By: Oz <oz-agent@warp.dev>
* fix(config): name Hermes Agent in restart notice
* fix(swarm): reconcile aggregate semantic worker exports
---------
Co-authored-by: Aurora release bot <release@outsourc-e.com>
Co-authored-by: motoki takahashi <motokitakahashi@motokinoMac-mini.local>
Co-authored-by: Vicky Wonder <vicky@openclaw.ai>
Co-authored-by: Vitaliy Isikov <visikov+supagoku@gmail.com>
Co-authored-by: Hermes Agent <hermes-agent@local>
Co-authored-by: Nikolay Mohr <nikomohr96@gmail.com>
Co-authored-by: Niko Mohr <niko@friendsfromcollege.de>
Co-authored-by: wtchronos <262830926+wtchronos@users.noreply.github.com>
Co-authored-by: Dak0verflow <dakotaferris@gmail.com>
Co-authored-by: norema <mamadou.marone.19@gmail.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: daoyuan <ludaoyuan1989@gmail.com>
Co-authored-by: firemountain <firemountain@gmail.com>
Co-authored-by: RAZSOC Local <razsoc@local>
Co-authored-by: Waylon Kenning <waylonkenning@Waylons-MacBook-Pro.local>
Co-authored-by: Kublai <kublai@kublai.local>
Co-authored-by: justa <justa@local>
Co-authored-by: Oz <oz-agent@warp.dev>
- Remove the MseeP.ai security badge - the crocodile mascot doesn't fit
Workspace branding and Workspace isn't an MCP server (it's an agent UI),
so the audit badge was confusing for users skimming the readme.
- Bump the visible version badge from 2.1.3 to 2.3.0 to match the actual
shipped version.
- Add a dedicated 'Pair an Agent with the Workspace' section between the
install paths and Docker, covering:
- Architecture diagram (which service does what on which port)
- Three-command pairing workflow
- Verify-pairing curl checks
- .env reference table
- Common pairing scenarios (local, Tailscale/VPN, multi-profile, remote)
- Live re-pairing without restart
- Troubleshooting for the four most common pairing errors
The previous readme split this information across the 'Already running
hermes-agent? Attach the workspace to it' and 'Manual install' sections,
which was hard to follow if your question was just 'how do I connect
agent X to workspace Y'.
Co-authored-by: Aurora release bot <release@outsourc-e.com>
The README's feature list and roadmap were stale: missing the new MCP
page (#231), Operations dashboard, Agent View panel, Conductor screen,
and capability-gate work landed in the past 24-48h. Roadmap still
listed shipped features as 'In Development'.
Changes:
- Replace short 'Features' bullet list with a comprehensive 'What's
inside' that mentions every major surface, including the explicit
Conductor caveat with a link to #262.
- Roadmap restructured into Shipped / In progress / Coming sections.
Conductor gets its own 'in progress' row with the upstream-plugin
caveat. Native Desktop App moved to 'in progress' per spec status.
Multi-provider support called out explicitly so users know what
works on day one.
- Drop the in-house 'Agent W Managed Companion' subsection from public
README \u2014 it's internal-team-only deployment notes that don't apply
to anyone running upstream.
- Collapse the duplicate '## Features' section near the bottom into the
consolidated security section. Avoids saying the same thing twice.
- Tighten security headings: now '## Security & deployment env vars'
with two clean subsections: 'Built-in safeguards' and 'Env vars for
remote / Docker deployments'.
Build clean. No code changes.
Co-authored-by: Aurora release bot <release@outsourc-e.com>
The 2026-05-01 codename rename swept most of the repo from 'Claude' to
'Hermes' but left a few env vars and README copy that still referenced
the old name. Users on fresh installs were configuring HERMES_PASSWORD
based on the docs but the auth middleware only read CLAUDE_PASSWORD,
silently bypassing the guard.
Changes:
- src/server/auth-middleware.ts: read HERMES_PASSWORD first, fall back
to CLAUDE_PASSWORD for back-compat with pre-rename setups.
- server-entry.js: same fallback for HERMES_PASSWORD +
HERMES_ALLOW_INSECURE_REMOTE. Error messages updated to point at the
new names.
- README.md:
- Drop the misleading 'v2 zero-fork = full feature parity' framing;
call out that Conductor specifically requires an upstream dashboard
plugin not yet shipped (per #262), with a link.
- Theme list updated to current names (Hermes / Nous / Bronze /
Slate / Mono \u2014 the v2.1 rename) instead of the old 'Official /
Classic' labels.
- Replace CLAUDE_PASSWORD / CLAUDE_ALLOW_INSECURE_REMOTE references
with HERMES_* primary names + back-compat note.
- Add HERMES_API_TOKEN to the security env-var list (previously
undocumented despite being honored by the gateway-capabilities probe).
- Inline note on the avatar PNG asset name being retained for cache
stability \u2014 the 'claude-avatar' filename is intentional.
- .env.example: HERMES_PASSWORD + HERMES_ALLOW_INSECURE_REMOTE primary
names with legacy notes.
- docker-compose.yml: HERMES_PASSWORD: ${HERMES_PASSWORD:-${CLAUDE_PASSWORD:-}}
so existing compose files that set CLAUDE_PASSWORD keep working while
new files use HERMES_PASSWORD.
Build + auth-middleware tests pass.
No public-facing breaking change: every previous CLAUDE_* env var still
resolves correctly through the back-compat fallbacks.
Co-authored-by: Aurora release bot <release@outsourc-e.com>
Removes `docker/agent/Dockerfile` and `docker/workspace/Dockerfile`:
- `docker/agent/Dockerfile` cloned the wrong repo (`outsourc-e/hermes-agent`
is the workspace fork, not the agent) and ran the old `claude` binary
name. It would not build successfully.
- `docker/workspace/Dockerfile` was a dev-mode (`pnpm dev`) variant that
duplicated the production root `Dockerfile` for no benefit; the dev
overlay now reuses the root Dockerfile with hot-build instead.
Updates `docker-compose.dev.yml` to build only the workspace from local
source via the canonical root Dockerfile. The Hermes Agent service stays
on the canonical `nousresearch/hermes-agent:latest` upstream image
(~750k pulls), with a clear note in the overlay header explaining how
to override if a custom agent image is genuinely needed.
Adds a quick-start path table at the top of README pointing 'compose
gig' users straight at the Docker section, and rewrites the dev-overlay
section to match the simpler reality.
This addresses the recurring 'can we get a docker image so I can set
up a compose gig instead of building from source' community ask. The
image already exists at `ghcr.io/outsourc-e/hermes-workspace:latest`,
the compose file just works \u2014 the stale local Dockerfiles were the
only thing making the dev overlay confusing.
Co-authored-by: Aurora release bot <release@outsourc-e.com>
NODE_ENV=production enables the Secure flag on session cookies. Browsers
silently drop Secure cookies over plain HTTP, causing login to fail with
no visible error when HOST=0.0.0.0 is used on a LAN without HTTPS.
- Add startup warning in server-entry.js when non-loopback host +
production + COOKIE_SECURE not explicitly disabled
- Document COOKIE_SECURE=0 in .env.example alongside the existing =1 case
- Add COOKIE_SECURE entry to README env-vars table
Closes#149
Worked with Interstellar Code
(cherry picked from commit d88d899481871f2d9ac5d01f5c318f668d1e6873)
Addresses the 5 security findings from @kiosvantra's audit (thank you!).
## #121 — Path traversal via naive startsWith()
src/routes/api/files.ts: ensureWorkspacePath now uses path.relative()
to enforce the workspace boundary. The previous string-prefix check
accepted sibling paths (e.g. /root/.hermes2 when root is /root/.hermes).
Added regression tests in src/routes/api/-files.test.ts.
## #122 — Deployment defaults expose control plane
server-entry.js: default HOST to 127.0.0.1. If HOST is non-loopback
and HERMES_PASSWORD is unset, the server refuses to start with a
clear banner explaining the fix. An explicit
HERMES_ALLOW_INSECURE_REMOTE=1 escape hatch is available for operators
who understand the risk.
docker-compose.yml: gateway defaults to 127.0.0.1 (no host binding),
workspace publishes on 127.0.0.1:3000 and passes HERMES_PASSWORD /
COOKIE_SECURE / TRUST_PROXY through.
## #123 — Session cookie missing Secure
src/server/auth-middleware.ts: createSessionCookie() now appends
Secure by default in production (and when COOKIE_SECURE=1 overrides).
Docs clarify when dev-HTTP exemption is safe.
## #124 — Dashboard token scraped from HTML
src/server/gateway-capabilities.ts: fetchDashboardToken() now prefers
an explicit HERMES_DASHBOARD_TOKEN (or HERMES_API_TOKEN) env bearer.
The HTML-scrape path remains as a logged fallback for existing
deployments, with a deprecation warning pointing at #124. This removes
the brittle trust boundary in production.
## #125 — x-forwarded-for trusted unconditionally
src/server/auth-middleware.ts + src/server/rate-limit.ts: both IP
resolvers now ignore forwarded headers unless TRUST_PROXY=1 is set.
Without that opt-in, clients cannot spoof local classification or
rotate rate-limit keys via x-forwarded-for. Added regression tests.
## Env + docs
.env.example: new Security section documenting HOST, HERMES_PASSWORD,
COOKIE_SECURE, TRUST_PROXY, HERMES_DASHBOARD_TOKEN, and the bypass.
README.md: Security section updated to reflect the new posture and
credit the audit.
## Verification
- tsc --noEmit: clean
- vitest: 43/43 pass (added 16 new tests across files, auth-middleware,
rate-limit)
- Fail-closed guard verified manually:
HOST=0.0.0.0 \u2192 exit 1 with banner
HOST=0.0.0.0 HERMES_PASSWORD=x \u2192 starts
HOST=0.0.0.0 HERMES_ALLOW_INSECURE_REMOTE=1 \u2192 starts with warn
HOST=127.0.0.1 \u2192 starts
Closes#121, #122, #123, #124, #125
Co-authored-by: Eric <eric@outsourc-e.com>
Adds a Settings > Connection section where users can edit the gateway
and dashboard URLs at runtime. Solves the Tailscale / LAN / remote-host
UX hole @diegodefieth-hash flagged in #101.
Implementation:
- gateway-capabilities.ts now supports setGatewayUrl() / setDashboardUrl()
that update the in-process HERMES_API / HERMES_DASHBOARD_URL values
AND persist to ~/.hermes/workspace-overrides.json. On process start
the overrides file takes precedence over env vars, which still win
over the localhost defaults.
- New PUT /api/connection-settings endpoint. Validates http(s) URLs,
calls the setters, force-reprobes capabilities so the UI sees the
unlock/lock immediately.
- New Connection settings section with two inputs (gateway + dashboard),
Save/Reset buttons, source label, and a Tailscale/remote tip callout.
- Workspace overrides file written with 0600 perms (tokens/URLs are
sensitive context about the user's network topology).
- README updated: no more 'stop + edit .env + start'.
Fixes#101
Co-authored-by: Eric <eric@outsourc-e.com>
The 'dev' and 'start:dev' scripts hardcoded --port 3000 on the CLI,
which collided with Baileys/WhatsApp bridges and other services that
also default to 3000. Users couldn't relocate the workspace without
editing package.json.
Changes:
- Drop --port from the CLI scripts; vite.config.ts now owns the port
- vite.config.ts reads process.env.PORT (default 3000) so users can run:
PORT=4000 pnpm dev
- README snippet updated to mention the override
- Default stays at 3000 so every existing install, docker-compose file,
and reverse-proxy rule keeps working
Fixes#96
Co-authored-by: Eric <eric@outsourc-e.com>
#101 reported that running the workspace on a Tailscale-exposed server
and accessing it from a phone ended up probing 127.0.0.1:8642 instead
of the Tailscale IP. Root cause is user-facing: both HERMES_API_URL and
HERMES_DASHBOARD_URL must be set to reachable URLs at process start,
and the gateway needs API_SERVER_HOST=0.0.0.0.
This PR adds:
- README section 'Running on a remote host (Tailscale / VPN / LAN)' with
a worked example covering both env vars + gateway bind config
- Clearer console warning when the localhost probe fails, pointing users
at the env vars and the gateway bind requirement
No code behaviour change. A UI-side backend-URL override is tracked as
a future enhancement in #101.
Co-authored-by: Eric <eric@outsourc-e.com>
Closes#76.
Clarifies that users who already have a running hermes-agent gateway
(systemd, Docker, pip install, Nous installer, etc.) don't need to
bootstrap a fresh one \u2014 they can point the workspace at the existing
gateway via HERMES_API_URL (and HERMES_API_TOKEN if auth is enabled).
Documents the three requirements on the agent side:
- Gateway bound to a reachable address
- API_SERVER_ENABLED=true for enhanced endpoints
- Matching HERMES_API_TOKEN when API_SERVER_KEY is set
Co-authored-by: Aurora <aurora@outsourc-e.dev>
Swap docker-compose.yml from local builds to pulling the official
upstream images by default. No more 'wait 10 minutes for git clone +
pip install + uv venv' on first run.
- hermes-agent -> nousresearch/hermes-agent:latest (upstream)
- hermes-workspace -> ghcr.io/outsourc-e/hermes-workspace:latest (our GHCR)
Also:
- Persist agent state to a named 'hermes-data' volume mounted at /opt/data
(config, sessions, skills, memory, creds survive container recreation).
- Add docker-compose.dev.yml overlay so contributors can still build from
source via: docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build
- Harden the healthcheck to CMD-SHELL so exit codes propagate.
- README + CHANGELOG updated to match.
Closes#82.
Co-authored-by: Aurora <aurora@outsourc-e.dev>
Community request: pre-built Docker image for Coolify / Easypanel /
Dokploy / Unraid / any PaaS that takes a container URL.
- Add production Dockerfile (multi-stage: build on node:22-slim, run as
non-root, tini PID 1, healthcheck on port 3000).
- Add .github/workflows/docker-publish.yml that builds + pushes on every
commit to main and every v* tag, multi-arch (amd64 + arm64), with
GHCR tags: latest, semver, branch-sha, etc.
- README: add 'Using a Pre-Built Image' section with Coolify/Easypanel
example config and the list of published tags.
First published image will appear at ghcr.io/outsourc-e/hermes-workspace
on next push to main.
User on Discord reported our docs saying ANTHROPIC_API_KEY is required.
It's not — hermes-agent supports Anthropic, OpenAI, OpenRouter (incl. free
models), Google, local Ollama/LM Studio, etc. Users only need the key for
the provider they actually picked in `hermes setup`.
Also replaced the 'pip install hermes-agent' references that snuck in — the
package isn't on PyPI, it installs from source via Nous's official script.
Changes:
- .env.example: list all common provider keys, all commented out, users
uncomment whichever they use
- docker-compose.yml: pass through ANTHROPIC / OPENAI / OPENROUTER / GOOGLE /
GROQ / MISTRAL keys (all optional, whichever is set wins)
- README.md: remove 'ANTHROPIC_API_KEY required' claim, replace pip install
references with the Nous installer path, generalize Docker troubleshooting
to match any provider
- FEATURES-INVENTORY.md: list all supported provider env vars
- Connection error helper now says 'hermes gateway run', not hermes-webapi
- Startup screen no longer tells users to clone outsourc-e/hermes-agent
- Replace editable-install / venv instructions with vanilla pip install +
hermes setup + hermes gateway run
- README troubleshooting line now upgrades stock hermes-agent instead of
suggesting 'git pull && pip install -e .'
This closes the last major user-facing fork confusion inside the workspace UI.
- Add install.sh: preflight-checked installer that pulls vanilla
hermes-agent from PyPI, clones the repo, configures .env, installs
deps. Idempotent, re-runnable.
- README: new 'One-line install' section with curl | bash command.
Demote Manual install section to secondary path.
- Banner tightened: 'v2 — zero-fork. Clone, don't fork.'
- Remove 'Earlier versions required a fork' retrospective from banner;
the fork is gone, we don't need to apologize for it.
- Model switch toast: drop 'enhanced fork' phrasing, use 'enhanced
runtime' (the fork no longer exists as a distinct thing; vanilla
provides the enhanced runtime).
- Update pinned-copy test accordingly.
One-liner for users:
curl -fsSL https://raw.githubusercontent.com/outsourc-e/hermes-workspace/main/install.sh | bash
- Lead with zero-fork banner under the tagline
- Replace all 'clone outsourc-e/hermes-agent fork' instructions with
stock pip install hermes-agent
- Update troubleshooting: upstream now has full endpoint parity
- Keep the migration note so old fork users know to uninstall and
reinstall from PyPI
Closes the last doc gap before v2 tag/push.
* feat: add support for Atomic Chat provider
- Introduced new provider 'Atomic Chat' with associated logo and configuration.
- Updated onboarding and settings components to include Atomic Chat.
- Added necessary files for provider integration, including images and configuration files.
- Updated provider catalog to include details for Atomic Chat.
This enhances the application by allowing users to utilize local LLMs via the Atomic Chat desktop app.
* refactor: remove deprecated configuration files and update README for Atomic Chat
- Deleted obsolete `.pnpm-approved-builds.json` and `mise.toml` files.
- Updated README to reflect the addition of Atomic Chat, including new usage instructions and configuration examples.
- Enhanced onboarding component to support Atomic Chat provider.
- Adjusted provider wizard description to include Atomic Chat alongside Ollama.
---------
Co-authored-by: SankaManka <rita@bagoodex.com>
Adds dedicated section for portable mode (direct to Ollama) and
enhanced mode (through Hermes gateway with custom_providers config).
Updated troubleshooting for common Ollama issues.
