rainysy/hermes-workspace
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: pairing/setup flow — dashboard on 9119, verify /api/sessions before starting another gateway, Codex auth (codex login + Hermes import) for gpt-5.4 default

Browse Source
This commit is contained in:
Aurora
2026-06-05 17:51:51 -04:00
parent fab418b9fe
commit 40ad61ea6b
4 changed files with 127 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
AGENTS.md
View File

@@ -23,6 +23,8 @@ This workspace uses semantic Hermes swarm workers, not numbered-only lanes. The
- Prefer GBrain-first lookup for context-sensitive RAZSOC/Hermes/workflow decisions.
- Builder implements; Reviewer gates; QA verifies behavior; Orchestrator routes and enforces greenlight.
- Do not enable optional Hermes plugins globally unless the task explicitly needs them; record plugin/toolset alignment in `swarm.yaml` first.
- For local Workspace pairing/debugging, treat **one gateway + one dashboard** as canonical: `hermes gateway run` on `:8642` and `hermes dashboard` on `:9119`. Before starting another gateway, verify `curl http://127.0.0.1:3000/api/sessions` (or the active workspace port) first. If Sessions already returns data, refresh/reprobe the UI instead of spawning a duplicate gateway.
- If the default model is `gpt-5.4` / `openai-codex`, remember that chat depends on a live local Codex CLI login (`codex login`).
## Windows-specific notes (2026-06-01)

11
README.md
View File

@@ -138,6 +138,15 @@ Verify both services before opening the workspace:
- `curl http://127.0.0.1:8642/health` should return ok.
- `curl http://127.0.0.1:9119/api/status` should return dashboard metadata.
- `curl http://127.0.0.1:3000/api/sessions` (after the workspace boots) should return a sessions payload or an empty list.
If `/api/sessions` is already returning data, **do not start another gateway just because the UI still says Offline** — refresh or reprobe the Workspace UI first.
If your default model is `gpt-5.4` / `openai-codex`, make sure Codex CLI auth is live before testing chat:
```bash
codex login
```
Then start the workspace and complete onboarding — it should detect the gateway + dashboard pair and unlock the enhanced panes automatically.
@@ -403,6 +412,8 @@ If you've already started the workspace, change either URL from **Settings → C
- **`Could not reach Hermes gateway on 8645, 8642, or 8643`** — gateway isn't running, or `HERMES_API_URL` points somewhere unreachable. Run `hermes gateway run` and re-check.
- **Workspace shows "portable mode" / extended APIs missing** — dashboard isn't running. Start `hermes dashboard` in another terminal and refresh.
- **Sessions probe says unavailable / UI claims Offline but pairing should be live** — verify `curl http://localhost:3000/api/sessions` before starting another gateway. If it returns sessions (or an empty array), the backend pairing is alive and the UI needs a refresh/reprobe.
- **Chat send fails on `gpt-5.4` / Codex** — Codex CLI auth is stale. Run `codex login`, then retry the chat without starting another gateway.
- **`Unauthorized` on every API call** — gateway has `API_SERVER_KEY` set but workspace is missing `HERMES_API_TOKEN`. Match them.
- **`Could not connect` from your phone over Tailscale** — gateway is bound to loopback. Set `API_SERVER_HOST=0.0.0.0` in `~/.hermes/.env` and restart it.

92
docs/AGENT-PAIRING.md
View File

@@ -1,8 +1,9 @@
# Agent Pairing Guide — Workspace ↔ Claude Gateway
# Agent Pairing Guide — Workspace ↔ Hermes Agent
> **Audience:** AI agents helping users set up Hermes Workspace.
> Run these steps in order. Each step has a verification command — don't
> skip to the next until the check passes.
> Run these steps in order. Each step has a verification command. Do not skip
> ahead, and do not start a second gateway until the current one fails the
> checks below.
## Architecture (30-second version)
@@ -15,15 +16,22 @@
└─────────────────┘ └──────────────────┘
```
Workspace talks to the gateway over HTTP. No WebSocket. No magic.
If `curl http://127.0.0.1:8642/health` returns JSON, they can pair.
Workspace talks to Hermes Agent over HTTP. No WebSocket. No magic.
A fully paired local setup has two services:
- `hermes gateway run` on **:8642** for chat, models, and streaming
- `hermes dashboard` on **:9119** for sessions, skills, config, and jobs
If `curl http://127.0.0.1:8642/health` and `curl http://127.0.0.1:9119/` both
return successfully, they can pair.
---
## Step 1 — Is hermes-agent installed?
```bash
claude --version
hermes --version
```
**Pass:** prints `Hermes Agent vX.Y.Z`.
@@ -39,7 +47,7 @@ curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scri
After install, restart your shell or run:
```bash
export PATH="$HOME/.local/bin:$PATH"
claude --version
hermes --version
```
---
@@ -47,15 +55,15 @@ claude --version
## Step 2 — Is the API server enabled?
The gateway exposes an HTTP API on port 8642, but only if `API_SERVER_ENABLED=true`
is set in the claude env file.
is set in the Hermes env file.
```bash
# Find the env file
CLAUDE_ENV="$(claude config env-path 2>/dev/null || echo "$HOME/.claude/.env")"
echo "Claude env file: $CLAUDE_ENV"
HERMES_ENV="$(hermes config env-path 2>/dev/null || echo "$HOME/.hermes/.env")"
echo "Hermes env file: $HERMES_ENV"
# Check for the key
grep -i "API_SERVER" "$CLAUDE_ENV" 2>/dev/null || echo "NO API_SERVER KEYS FOUND"
grep -i "API_SERVER" "$HERMES_ENV" 2>/dev/null || echo "NO API_SERVER KEYS FOUND"
```
**Pass:** output includes `API_SERVER_ENABLED=true` (with underscores).
@@ -78,16 +86,16 @@ API_SERVER_HOST=127.0.0.1
### Fix
```bash
CLAUDE_ENV="$(claude config env-path 2>/dev/null || echo "$HOME/.claude/.env")"
mkdir -p "$(dirname "$CLAUDE_ENV")"
HERMES_ENV="$(hermes config env-path 2>/dev/null || echo "$HOME/.hermes/.env")"
mkdir -p "$(dirname "$HERMES_ENV")"
# Remove any typo'd versions first
sed -i.bak '/^APISERVERENABLED/d; /^APISERVERHOST/d; /^APISERVERKEY/d; /^APISERVERPORT/d' "$CLAUDE_ENV" 2>/dev/null || true
sed -i.bak '/^APISERVERENABLED/d; /^APISERVERHOST/d; /^APISERVERKEY/d; /^APISERVERPORT/d' "$HERMES_ENV" 2>/dev/null || true
# Write correct keys (idempotent — updates existing or appends)
grep -q '^API_SERVER_ENABLED=' "$CLAUDE_ENV" 2>/dev/null && \
sed -i.bak 's/^API_SERVER_ENABLED=.*/API_SERVER_ENABLED=true/' "$CLAUDE_ENV" || \
echo 'API_SERVER_ENABLED=true' >> "$CLAUDE_ENV"
grep -q '^API_SERVER_ENABLED=' "$HERMES_ENV" 2>/dev/null && \
sed -i.bak 's/^API_SERVER_ENABLED=.*/API_SERVER_ENABLED=true/' "$HERMES_ENV" || \
echo 'API_SERVER_ENABLED=true' >> "$HERMES_ENV"
```
**Do NOT set `API_SERVER_HOST=0.0.0.0`** unless the user explicitly wants
@@ -100,7 +108,7 @@ correct for local Workspace.
## Step 3 — Is the gateway process running?
```bash
pgrep -af "claude.*gateway" || echo "NOT RUNNING"
pgrep -af "hermes.*gateway" || echo "NOT RUNNING"
```
**Pass:** shows a `hermes gateway run` (or similar) process.
@@ -117,7 +125,7 @@ hermes gateway install # creates the service
systemctl --user start claude-gateway
```
**First run:** claude may prompt for initial setup (provider, model). Complete
**First run:** Hermes may prompt for initial setup (provider, model). Complete
the interactive setup before continuing.
---
@@ -148,6 +156,20 @@ ss -tlnp | grep 8642 # Linux
# Kill the stale process, then restart gateway
```
## Step 4b — Is the dashboard running on 9119?
```bash
curl -sf http://127.0.0.1:9119/ && echo "DASHBOARD OK" || echo "DASHBOARD NOT REACHABLE"
```
**Pass:** returns HTTP 200 (HTML or JSON is fine).
### Fix
```bash
hermes dashboard
```
---
## Step 5 — Is Workspace pointed at the gateway?
@@ -159,10 +181,19 @@ cat .env | grep HERMES_API_URL
**Pass:** `HERMES_API_URL=http://127.0.0.1:8642`
Also set the dashboard URL:
```bash
grep HERMES_DASHBOARD_URL .env
```
**Pass:** `HERMES_DASHBOARD_URL=http://127.0.0.1:9119`
**Fail or missing:**
```bash
# In the hermes-workspace directory
echo 'HERMES_API_URL=http://127.0.0.1:8642' >> .env
echo 'HERMES_DASHBOARD_URL=http://127.0.0.1:9119' >> .env
```
If `.env` doesn't exist:
@@ -189,6 +220,17 @@ pnpm dev
**`mode=enhanced-fork`** = paired successfully. Sessions, memory, skills all
available.
### Critical verification before starting another gateway
```bash
curl -sf http://127.0.0.1:8642/health
curl -sf http://127.0.0.1:3000/api/sessions | jq '.sessions | length' 2>/dev/null || curl -sf http://127.0.0.1:3000/api/sessions
```
If `/api/sessions` returns sessions (or an empty array) the pairing is alive.
**Do not start another gateway just because the UI still says Offline** —
refresh or reprobe the workspace UI first.
**`mode=disconnected`** = pairing failed. Go back to Step 4.
---
@@ -210,14 +252,14 @@ Open `http://localhost:3000` (or whatever port Vite reports).
For users who just want it to work — run this entire block:
```bash
# 1. Find claude env
CLAUDE_ENV="$(claude config env-path 2>/dev/null || echo "$HOME/.claude/.env")"
mkdir -p "$(dirname "$CLAUDE_ENV")"
# 1. Find Hermes env
HERMES_ENV="$(hermes config env-path 2>/dev/null || echo "$HOME/.hermes/.env")"
mkdir -p "$(dirname "$HERMES_ENV")"
# 2. Enable API server (idempotent)
grep -q '^API_SERVER_ENABLED=' "$CLAUDE_ENV" 2>/dev/null && \
sed -i.bak 's/^API_SERVER_ENABLED=.*/API_SERVER_ENABLED=true/' "$CLAUDE_ENV" || \
echo 'API_SERVER_ENABLED=true' >> "$CLAUDE_ENV"
grep -q '^API_SERVER_ENABLED=' "$HERMES_ENV" 2>/dev/null && \
sed -i.bak 's/^API_SERVER_ENABLED=.*/API_SERVER_ENABLED=true/' "$HERMES_ENV" || \
echo 'API_SERVER_ENABLED=true' >> "$HERMES_ENV"
# 3. Clean up common typos
sed -i.bak '/^APISERVERENABLED/d; /^APISERVERHOST/d' "$CLAUDE_ENV" 2>/dev/null || true

50
docs/troubleshooting.md
View File

@@ -51,6 +51,14 @@ After fixing, restart the gateway: `hermes gateway run --replace`
If the gateway is running and healthy but Workspace still disconnects, check for port conflicts (another process on 8642) or firewall rules.
Before starting a second gateway, verify the workspace probe directly:
```bash
curl http://127.0.0.1:3000/api/sessions
```
If that returns sessions (or an empty list), the backend pairing is already alive and the UI needs a refresh/reprobe — **do not start another gateway**.
---
## 3. Port 8642 already in use
@@ -73,7 +81,43 @@ hermes gateway run --replace
---
## 4. WSL: Gateway health check times out on first boot
## 4. Dashboard not running (sessions / skills / jobs missing)
**Symptom:** Chat works, but Sessions/Skills/Jobs stay offline or `/api/sessions` says the backend does not support the sessions API.
**Cause:** `hermes dashboard` is not running on port 9119.
**Fix:**
```bash
hermes dashboard
curl -sf http://127.0.0.1:9119/ && echo "dashboard ok"
```
Workspace needs both:
- `hermes gateway run` on `:8642`
- `hermes dashboard` on `:9119`
---
## 5. Codex / GPT-5.4 chat fails with missing access token
**Symptom:** Sending chat through Workspace fails with an error like `Codex auth is missing access_token`.
**Cause:** The default model is `gpt-5.4` / `openai-codex`, but the local Codex CLI login is stale or missing.
**Fix:**
```bash
codex login
```
Then retry the chat. Do not restart the gateway unless auth still fails after re-login.
---
## 6. WSL: Gateway health check times out on first boot
**Symptom:** Workspace starts, checks the gateway, reports "disconnected". But if you wait 15 seconds and refresh, it works.
@@ -92,7 +136,7 @@ cd ~/hermes-workspace && pnpm dev
---
## 5. Dev server crashes immediately after boot
## 7. Dev server crashes immediately after boot
**Symptom:** `pnpm dev` starts, shows the Vite banner, then crashes with ELIFECYCLE or a stack trace.
@@ -105,7 +149,7 @@ cd ~/hermes-workspace && pnpm dev
---
## 6. "No compatible backend detected" in onboarding
## 8. "No compatible backend detected" in onboarding
**Symptom:** Clicked "Connect Backend", health check runs, shows error.