Hermes Agent | JoyToken | Documentation

What is Hermes Agent?

Hermes Agent is a terminal-native autonomous coding and task agent. When Hermes supports an OpenAI-compatible provider, you can route its model calls through JoyToken with a single API key, centralized policy, model routing, wallet checks, and usage attribution.

Hermes configuration keys can differ by version. This page describes the provider contract JoyToken expects: OpenAI-compatible base URL, bearer API key, and auto or a concrete JoyToken model key.

Setup

Step 1: Create a JoyToken API key

Create a dedicated key such as dev-hermes-agent.

Setting	Recommendation
Model	Start with `auto`
Budget	Daily or weekly development cap
Policy	Limit approved tiers and models
Logs	Keep enabled

Step 2: Set environment variables

.env

$ JOY_TOKEN_API_KEY="jt_xxx"
$ JOY_TOKEN_OPENAI_BASE_URL="https://api-dev.joytokens.ai/openai/v1"
$ JOY_TOKEN_DEFAULT_MODEL="auto"

Step 3: Configure the Hermes provider

If Hermes exposes a generic OpenAI-compatible provider, use this shape:

hermes.yaml

1 model:
2   provider: openai-compatible
3   base_url: ${JOY_TOKEN_OPENAI_BASE_URL}
4   api_key_env: JOY_TOKEN_API_KEY
5   default: ${JOY_TOKEN_DEFAULT_MODEL}

Step 4: Start Hermes

Start Hermes using your normal CLI or TUI command. Requests should now go through JoyToken.

Manual Configuration

If Hermes separates primary and auxiliary models, point each JoyToken-backed role explicitly at the JoyToken provider:

hermes.yaml

1 providers:
2   joytoken:
3     type: openai-compatible
4     base_url: https://api-dev.joytokens.ai/openai/v1
5     api_key_env: JOY_TOKEN_API_KEY
6 
7 models:
8   primary:
9     provider: joytoken
10     model: auto
11   planner:
12     provider: joytoken
13     model: auto
14   summarizer:
15     provider: joytoken
16     model: auto

Model Format

Value	Behavior
`auto`	JoyToken router selects a model within policy
Concrete model key	Pins the role to a JoyToken model while still passing policy and wallet checks
API key fixed model	Key policy restricts or overrides requested model values

Recommended starting point:

Hermes role	JoyToken model setting	Notes
Primary agent	`auto`	Let JoyToken route during early evaluation
Planner	`auto`	Pin later if planning quality needs consistency
Summarizer	`auto` or small pinned model	Keep background cost predictable
Evaluator	Separate key or fixed model	Easier to audit quality checks

Monitoring Usage

If Hermes supports custom headers, pass request IDs:

headers.yaml

1 headers:
2   X-Request-ID: hermes-session-${SESSION_ID}

For multi-step runs, include role and step:

hermes-support-42-planner-step-03
hermes-support-42-summarizer-step-01

Check JoyToken Logs and Usage after the first run.

Why use JoyToken with Hermes Agent?

Cost attribution

Use a dedicated Hermes key, or split keys by role, to separate primary agent cost from background summarization and evaluation.

Policy controls

Apply model, tier, IP, and budget policy before unattended Hermes workflows spend credits.

Model routing

Use auto during evaluation, then pin roles that need deterministic quality or predictable cost.

Troubleshooting

Symptom	Check
Hermes still calls another provider	Default model points to the JoyToken provider
`401 Unauthorized`	`JOY_TOKEN_API_KEY` is loaded by the Hermes process
`403 Forbidden`	JoyToken policy allows the requested model, tier, and IP
Unexpected cost	Split planner, summarizer, and evaluator into separate keys or pinned models
Broken streaming	Hermes handles OpenAI-compatible SSE chunks