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

AGENTS.md

@@ -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)
 

README.md

@@ -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.
 

docs/AGENT-PAIRING.md

@@ -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
+> Run these steps in order. Each step has a verification command. Do not skip
-> skip to the next until the check passes.
+> 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.
+Workspace talks to Hermes Agent over HTTP. No WebSocket. No magic.
-If `curl http://127.0.0.1:8642/health` returns JSON, they can pair.
+
+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")"
+HERMES_ENV="$(hermes config env-path 2>/dev/null || echo "$HOME/.hermes/.env")"
-echo "Claude env file: $CLAUDE_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")"
+HERMES_ENV="$(hermes config env-path 2>/dev/null || echo "$HOME/.hermes/.env")"
-mkdir -p "$(dirname "$CLAUDE_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 && \
+grep -q '^API_SERVER_ENABLED=' "$HERMES_ENV" 2>/dev/null && \
-  sed -i.bak 's/^API_SERVER_ENABLED=.*/API_SERVER_ENABLED=true/' "$CLAUDE_ENV" || \
+  sed -i.bak 's/^API_SERVER_ENABLED=.*/API_SERVER_ENABLED=true/' "$HERMES_ENV" || \
-  echo 'API_SERVER_ENABLED=true' >> "$CLAUDE_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
+# 1. Find Hermes env
-CLAUDE_ENV="$(claude config env-path 2>/dev/null || echo "$HOME/.claude/.env")"
+HERMES_ENV="$(hermes config env-path 2>/dev/null || echo "$HOME/.hermes/.env")"
-mkdir -p "$(dirname "$CLAUDE_ENV")"
+mkdir -p "$(dirname "$HERMES_ENV")"
 
 # 2. Enable API server (idempotent)
-grep -q '^API_SERVER_ENABLED=' "$CLAUDE_ENV" 2>/dev/null && \
+grep -q '^API_SERVER_ENABLED=' "$HERMES_ENV" 2>/dev/null && \
-  sed -i.bak 's/^API_SERVER_ENABLED=.*/API_SERVER_ENABLED=true/' "$CLAUDE_ENV" || \
+  sed -i.bak 's/^API_SERVER_ENABLED=.*/API_SERVER_ENABLED=true/' "$HERMES_ENV" || \
-  echo 'API_SERVER_ENABLED=true' >> "$CLAUDE_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

docs/troubleshooting.md

@@ -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.