Hermes Agent Integration

OPTX integration with upstream Hermes Agent v0.17.0 — native gateway APIs, MCP, and the jettoptx-hermes-api bridge for JettChat.

Tracked release: Hermes Agent v0.17.0 — The Reach Release (NousResearch tag v2026.6.19, June 19, 2026). Install/update with hermes update. Full upstream notes: hermes-agent releases.

This page describes how AstroJOE / JOE on the OPTX agent mesh integrates with upstream Hermes — what the gateway provides natively in v0.17, what the jettoptx-hermes-api bridge adds, and which v0.17 features matter for edge deployments.

OPTX stack

JettChat / DOJO  →  hermes-optx-api (:8643)  →  Hermes gateway (:8642)  →  HEDGEHOG → Grok
                              │                         │
                              │                         ├── /v1/runs (async agent lifecycle)
                              │                         ├── /api/sessions/*/chat/stream
                              │                         ├── /v1/capabilities
                              │                         └── MCP servers (config.yaml)
                              │
                              └── OPTX-only: tasks, SpacetimeDB memory, Tempo wallet, MPP gate

Component	Repo / docs
Hermes Agent (upstream)	NousResearch/hermes-agent
OPTX bridge sidecar	jettoptx-hermes-api · API reference
Edge MCP (token-gated)	jettoptx-aaron-public · Edge Gateway
LLM routing	HEDGEHOG (`OPENAI_BASE_URL`)

Native Hermes gateway (v0.17)

Since v0.12, Hermes ships an OpenAI-compatible API server on port 8642. v0.17 expands this surface — JettChat can call upstream directly for many flows; the bridge proxies /v1/* and adds OPTX-specific routes.

Route	Purpose
`POST /v1/chat/completions`	Stateless chat; optional `X-Hermes-Session-Id` for continuity
`POST /v1/responses`	Stateful Responses API (`previous_response_id`)
`GET /v1/capabilities`	Machine-readable API discovery for UIs
`GET/POST /api/sessions`	Session CRUD + message history
`POST /api/sessions/{id}/chat/stream`	Native session streaming
`POST /v1/runs`	Start async agent run (returns `run_id`)
`GET /v1/runs/{id}/events`	SSE lifecycle events (tools, approvals, completion)
`GET /health/detailed`	Rich probe for cross-container dashboards

Probe from the bridge: GET /api/gateway-status on port 8643 reports upstream_version, runs_api_upstream, and capabilities_endpoint.

What the OPTX bridge still adds

Upstream Hermes does not replace these JettChat / mesh concerns — they live in jettoptx-hermes-api v0.4.0+:

JettChat SSE envelope — session / content / done events on /api/sessions/new/chat/stream
SpacetimeDB memory — edge optx-cortex backend for AstroJOE persistent state
Task orchestration — claim/complete/swarm DAG for multi-agent workflows
Tempo / MPP billing — metered HEDGEHOG calls and gaze-gated escrow
Auth gate — API key + pay-per-request for public-facing deployments

See Hermes OPTX API for endpoint tables.

v0.17 highlights for the OPTX mesh

Features from v0.17.0 that affect JOE edge + operator workflows:

Agent execution

Background subagents — delegate_task(background=true) returns immediately; result re-enters the conversation when finished. Useful for long research or build steps on the mesh without blocking the primary session.
/v1/runs lifecycle — structured SSE events for tool calls, approvals, and interrupts; alternative to raw chat-completions streaming for Workspace-style UIs.
Memory tool batch edits — atomic operations array against the character budget; fewer failed multi-turn memory updates on edge nodes.

Skills + MCP

Skills Hub rehaul — dashboard browser with previews and security scan before install (OpenAI, Anthropic, HuggingFace, NVIDIA hubs).
Curator cost optimization — stale-skill prune runs by default; LLM consolidation is opt-in (curator.consolidate: true). Routine curation costs zero aux-model tokens.
MCP — attach servers in ~/.hermes/config.yaml; profile builder in dashboard. Edge deployments also expose tools via HEDGEHOG MCP at mcp.jettoptics.ai.

Platforms + reach

iMessage (Photon) — hermes photon login; no Mac relay required.
Raft agent network — bundled adapter; privacy-by-contract wake channel.
WhatsApp Business Cloud API — official Meta adapter alongside existing bridges.
Hermes Desktop — full operator UI (optional); mesh primary remains hermes gateway on Jetson/VPS.

Models + providers

Cursor Composer via xAI OAuth — grok-composer-2.5-fast in xAI Grok subscription picker.
Nous Portal Tool Gateway — hermes setup --portal for unified model + tool billing.

For the full v0.17 changelog (~800 PRs since v0.16), see upstream release notes.

Version alignment (OPTX)

Artifact	Version	Notes
Hermes Agent (upstream)	v0.17.0 (`v2026.6.19`)	Canonical target for new mesh deploys
hermes-optx-api (bridge)	v0.4.0	Probes `/v1/capabilities` + `/health/detailed`
Minimum Hermes gateway	v0.12.0+	Native `/api/sessions`; older gateways fall back to `/v1/chat/completions`

Previous docs pinned v0.12.0 (The Curator release, April 2026). v0.13–v0.16 added Hermes Desktop, expanded gateway plugins, and the /v1/runs API — superseded by v0.17 for OPTX tracking.

Upgrading on the OPTX mesh

Operator workstation (canonical):

hermes update          # or: git pull in hermes-agent clone && pip install -e .
hermes doctor
pip install -e .       # in jettoptx-hermes-api — restart sidecar

Edge-node Docker: rebuild images pinned to v2026.6.19. Until rebuilt, /api/gateway-status may report an older upstream_version — the operator workstation is the source of truth for mesh version.

Verify after upgrade:

curl -s http://localhost:8642/v1/capabilities | jq .endpoints
curl -s http://localhost:8643/api/gateway-status | jq .upstream_version,.features

Hermes OPTX API — bridge endpoints, auth, Docker
JOE Overview — AstroJOE architecture
Skills — SKILL.md system (upstream agentskills.io)
Orchestration — task DAG + swarm
Upstream docs — install, gateway, MCP, desktop

Hermes Agent Integration

On this page