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: 353400
  supports_vision: true

agent:
  image_input_mode: native

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

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 also expose an SDK-readable context_length value on /v1/models, derived from the effective Codex context_window metadata, so Hermes’ automatic probes can resolve the Pooler window. For the GPT-5.6 examples here, use the Codex raw 372000 window and the 353400 effective advertised value. Keep context_length: 353400 in Hermes config as an explicit override when Hermes cannot read /v1/models first.

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.

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: 353400
  supports_vision: true

agent:
  image_input_mode: native

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.