Hermes Agent

Hermes Agent should use Codex Pooler through the narrow OpenAI-compatible /v1 surface unless a Codex backend route is documented for the specific Hermes path you are testing.

The recommended setup is the Hermes openai-api provider. It keeps Hermes on its OpenAI API path, sends model requests to /v1, configures image generation on the OpenAI image provider, and keeps the Pool API key separate from the optional operator MCP token.

For a deployed instance, use these URLs:

OpenAI API base URL:
https://codex-pooler.example.com/v1

Operator MCP URL:
https://codex-pooler.example.com/mcp

For local setup, replace the host with http://localhost:4000.

Recommended openai-api provider

Store the Pool API key in a private Hermes environment file such as ~/.hermes/.env. Add the operator MCP token only if you want the optional read-only metadata tools.

OPENAI_API_KEY=<pool-api-key>
OPENAI_BASE_URL=https://codex-pooler.example.com/v1
# Optional operator-only MCP metadata add-on:
CODEX_POOLER_MCP_KEY=<operator-mcp-token>

Then point ~/.hermes/config.yaml at the same /v1 base URL, force the Responses transport mode, and include the image_gen block for Hermes image generation and edits.

model:
  default: gpt-5.6-terra
  provider: openai-api
  base_url: https://codex-pooler.example.com/v1
  api_mode: codex_responses
  context_length: 828400
  supports_vision: true

agent:
  image_input_mode: native

image_gen:
  provider: openai
  model: gpt-image-2-medium

compression:
  threshold: 0.95

auxiliary:
  compression:
    timeout: 900

# Optional operator-only MCP metadata add-on. Omit for model/runtime use.
mcp_servers:
  codex_pooler:
    url: https://codex-pooler.example.com/mcp
    headers:
      Authorization: "Bearer ${CODEX_POOLER_MCP_KEY}"
    enabled: true
    timeout: 120
    connect_timeout: 15

Use http://localhost:4000/v1 and http://localhost:4000/mcp for a local Codex Pooler instance.

Image generation note: image_gen.provider: openai is the recommended image provider for this setup. Hermes exposes gpt-image-2-low, gpt-image-2-medium, and gpt-image-2-high as quality tiers; for example, gpt-image-2-medium sends gpt-image-2 to the API with quality: medium. This provider uses the OpenAI SDK environment, so OPENAI_API_KEY and OPENAI_BASE_URL must be visible to the running Hermes process, not only to the shell where you edited the config. model.base_url configures Hermes’ text/model provider path; the OpenAI image provider still needs the SDK environment so image requests go through Codex Pooler’s /v1 surface instead of OpenAI directly.

If text requests work but image generation fails with invalid_api_key, check the environment of the long-running Hermes process or gateway service first. It may not have loaded OPENAI_BASE_URL, so the OpenAI SDK image client may be using OpenAI’s default endpoint instead of Codex Pooler.

Current Codex Pooler releases expose an SDK-readable context_length on /v1/models, flattened from the selected native raw context window and its effective percentage. Treat that per-model endpoint value as authoritative because provider accounts can temporarily report different catalog ceilings. The 828400 value in this example is a long-profile fallback for a Pool whose selected model source reports 872000 raw tokens; a short 272000-token profile reports 258400 instead. Match an explicit fallback to the Pool’s /v1/models result rather than configuring the raw ceiling. With the long-profile example, compression.threshold: 0.95 starts Hermes compression at 786980 tokens. Hermes context compression uses its own auxiliary request timeout. Keep auxiliary.compression.timeout: 900 so large retained contexts can finish instead of cycling through the older 120-second compression budget. This is independent from the optional MCP server timeout and from an application output cap.

Remote HTTP MCP servers require Hermes’ mcp extra. If hermes mcp test codex_pooler reports mcp.client.streamable_http is not available, install MCP support into the Hermes environment, following the Hermes MCP Integration docs, and rerun the test.

Test the model path with a one-shot prompt:

hermes -z 'Reply with exactly: hermes openai api ok' --ignore-rules

That test should create normal /v1 traffic using the Pool API key. The MCP entry is separate and should authenticate only with an operator-owned MCP token.

Alternate openai-codex credential-pool path

Hermes can also use its openai-codex provider against Codex Pooler, but this alternate path is less direct. The preferred setup is the openai-api provider above with api_mode: codex_responses. Hermes treats openai-codex as an OAuth provider by default, so add a Pool API key credential ahead of any device-code credential and keep the credential base_url on /v1.

Keep endpoint and MCP token values in the environment:

HERMES_CODEX_BASE_URL=https://codex-pooler.example.com/v1
CODEX_POOLER_MCP_KEY=<operator-mcp-token>

Set the provider in ~/.hermes/config.yaml:

model:
  default: gpt-5.6-terra
  provider: openai-codex
  base_url: https://codex-pooler.example.com/v1
  context_length: 828400
  supports_vision: true

agent:
  image_input_mode: native

compression:
  threshold: 0.95

auxiliary:
  compression:
    timeout: 900

# Optional operator-only MCP metadata add-on. Omit for model/runtime use.
mcp_servers:
  codex_pooler:
    url: https://codex-pooler.example.com/mcp
    headers:
      Authorization: "Bearer ${CODEX_POOLER_MCP_KEY}"
    enabled: true
    timeout: 120
    connect_timeout: 15

Add a credential-pool entry for Codex Pooler in the Hermes auth.json file. This example shows only placeholders. Don’t paste a real key into public docs or shared files.

{
  "active_provider": "openai-codex",
  "credential_pool": {
    "openai-codex": [
      {
        "label": "codex-pooler",
        "auth_type": "api_key",
        "priority": -10,
        "source": "manual",
        "access_token": "<pool-api-key>",
        "base_url": "https://codex-pooler.example.com/v1"
      }
    ]
  }
}

Use the openai-api path first unless you specifically need to test Hermes credential-pool behavior.

Compatibility notes

Hermes model requests use Codex Pooler’s narrow OpenAI-compatible /v1 support for selected SDK routes. Codex Pooler doesn’t provide full OpenAI API parity.

GET /v1/responses is narrow Responses websocket compatibility, not /v1/realtime support. /v1/realtime and OpenAI Realtime SDK websocket or session routes are unsupported.

The operator MCP endpoint is rooted at /mcp. It uses an operator-owned MCP token, not a Pool API key.