OPTX Documentation

FastAPI bridge between JettChat and Hermes Agent — SSE chat, SpacetimeDB memory, tasks, Tempo billing. Targets Hermes v0.17.

The Hermes OPTX API (jettoptx-hermes-api v0.4.0) is a FastAPI sidecar beside upstream Hermes Agent. Hermes v0.12+ provides native sessions, streaming, /v1/runs, and MCP via its gateway on port 8642; this bridge on port 8643 adds JettChat SSE formatting, SpacetimeDB memory, task orchestration, and Tempo wallet billing.

Integration guide: Hermes Agent Integration · Upstream tracked release: v0.17.0 (v2026.6.19)

Architecture split

Concern	Owner
Sessions, `/v1/chat/completions`, `/v1/runs`, MCP config	Hermes gateway (:8642)
JettChat SSE envelope, tasks, STDB memory, Tempo/MPP	hermes-optx-api (:8643)

Hermes OPTX API Architecture — JettChat to API sidecar to Hermes Agent with all endpoint routes — Hermes OPTX API v0.4.0 — bridge + upstream gateway

Gateway capability probing

At startup the bridge probes upstream for /v1/capabilities, /health/detailed, and /api/sessions:

curl http://localhost:8643/api/gateway-status

{
  "status": "connected",
  "mode": "enhanced-hermes",
  "version": "0.4.0",
  "upstream_version": "0.17.0",
  "upstream_target": "0.17.0",
  "features": {
    "sessions_api_upstream": true,
    "runs_api_upstream": true,
    "capabilities_endpoint": true,
    "health_detailed": true,
    "chat_stream": true,
    "tasks": true,
    "wallet": true,
    "tempo_billing": true,
    "mcp_servers": true
  }
}

Mode	Description
enhanced-hermes	Hermes v0.12+ gateway with sessions and/or capabilities
portable	Basic `/health` only
disconnected	Upstream unreachable; local bridge routes may still respond

SSE Streaming Chat

Primary JettChat integration — wraps upstream session streaming in a fixed SSE event shape.

New Session + Stream

curl -N -X POST http://localhost:8643/api/sessions/new/chat/stream \
  -H "Content-Type: application/json" \
  -d '{"message": "What is OPTX?"}'

Stream Into Existing Session

curl -N -X POST http://localhost:8643/api/sessions/abc123/chat/stream \
  -H "Content-Type: application/json" \
  -d '{"message": "Tell me more", "model": "grok-4.20-0309-reasoning"}'

SSE Event Format

Event	Data	Description
`session`	`{session_id, status}`	Session created or opened
`content`	`{content, session_id}`	Token chunk
`done`	`{session_id, status}`	Stream complete
`error`	`{error, session_id}`	Error occurred

Upstream also exposes POST /api/sessions/{id}/chat/stream and POST /v1/runs + GET /v1/runs/{id}/events — proxied through /v1/* on the bridge when clients use port 8643.

Bridge endpoints (OPTX-specific)

Sessions · Skills · Config

Method	Path	Description
`GET`	`/api/sessions`	List sessions
`POST`	`/api/sessions/new/chat/stream`	Create + stream
`GET`	`/api/skills`	List skills
`GET/POST`	`/api/config`	Read/update Hermes config

Memory (pluggable backend)

Method	Path	Description
`POST`	`/api/memory`	Store
`POST`	`/api/memory/search`	Search
`GET`	`/api/memory/stats`	Health

Backends: holographic (default), sqlite, spacetimedb — see Memory.

Tasks · Wallet

Method	Path	Description
`POST`	`/api/tasks`	Create task
`POST`	`/api/tasks/swarm`	DAG decomposition
`POST`	`/api/wallet/tempo/call`	Metered HEDGEHOG call
`POST`	`/api/wallet/escrow/release`	Gaze-gated release

Full tables: API Reference

Passthrough

Method	Path	Description
`*`	`/v1/*`	Proxy to Hermes gateway (streaming-aware)
`GET`	`/health`	Bridge + upstream probe

Authentication

Credential	Result
Valid `API_KEY` in `Authorization: Bearer`	Subscriber access
Valid MPP payment credential	Pay-per-request (Tempo)
No credential, nothing configured	Open access

Configuration

Variable	Default	Description
`HERMES_AGENT_URL`	`http://localhost:8642`	Hermes gateway
`HERMES_HOME`	`~/.hermes`	Skills + config path
`OPTX_API_PORT`	`8643`	Bridge port
`MEMORY_BACKEND`	`holographic`	Memory backend
`HEDGEHOG_URL`	—	Metered inference gateway

Installation

git clone https://github.com/jettoptx/jettoptx-hermes-api
pip install -e .
hermes-optx-api --hermes-url http://localhost:8642

Requires Hermes Agent v0.12.0+ (target v0.17.0). Install upstream: hermes-agent.nousresearch.com/docs

Hermes OPTX API

On this page