Hermes Agent connector configuration

This reference describes the configuration accepted by aip-host-hermes-agent at the reviewed source revision. A complete process combines two Hermes-specific file settings with the 45 shared connector-host settings.

Endpoint, operator-policy, identity, topology, limit, and provider-token values are read at startup. Only the optional shared credential-revision policy is re-read before provider side effects.

Configuration identity

Every setting is available through the listed environment variable. The two Hermes-specific settings also expose the listed command-line flag. Shared settings use the equivalent kebab-case connector-host flag.

Environment variables and flags contain non-secret values or paths. Endpoint tokens, database credentials, and signing material belong in bounded files.

Hermes-specific settings

The endpoint file is required even when it contains only one endpoint. The operator-policy file is optional; omission uses the built-in governed operator policy with first-class delegation disabled.

Endpoint descriptor file

The endpoint file is a non-empty JSON array. This example contains no secret bytes:

[
  {
    "id": "primary",
    "base_url": "https://hermes-primary.example.internal:8642",
    "api_key_file": "/run/secrets/hermes-primary-api-key",
    "display_name": "Primary Hermes",
    "tenant_id": "tenant-acme"
  }
]

Descriptor fields

Endpoint objects reject unknown fields. IDs that collide after trimming and lowercasing make connector construction fail. Action input cannot replace an endpoint ID, URL, tenant, or token.

The URL parser enforces only a valid http or https URL. It does not prove destination ownership or impose the stricter credential, query, fragment, and origin rules used by shared host endpoints. Deployment policy should require a credential-free HTTPS origin outside a controlled local network.

Endpoint bounds and manifest effects

Fifteen endpoints produce 525 capabilities and fail common host preparation. The parser’s 1000-item bound is therefore not a deployable catalog limit.

Changing endpoint IDs, base URLs, tenant values, or membership changes the discovered manifest and requires a corresponding immutable version and admission update. Changing only token bytes or display_name does not alter the current manifest, but a new process must load those startup values.

Provider authentication and client constants

Basic health is the only operation that does not require an endpoint token. The other 34 operations fail with connector.hermes_agent.missing_credential when no usable key is loaded. Protected requests use Authorization: Bearer <endpoint key>.

The default Hermes client has these fixed properties:

Operation-specific request and stream paths can apply narrower bounds. These constants are not environment settings.

Operator-policy file

The optional operator-policy file is a non-secret JSON object of at most 512 KiB. It is parsed and validated once at startup.

Omitting the file constructs the complete built-in defaults. Supplying a file does not merge it with those defaults: every field marked required below must be present.

Every prefix must be non-empty after trimming and at most 512 bytes. When delegation_enabled is true, both allowed-prefix lists must be non-empty. The literal * explicitly opts into an unrestricted dimension; use a complete capability or narrow namespace whenever possible.

Approval-exempt prefixes waive only this connector’s delegation approval gate. They do not bypass native AIP authorization, tenant, scope, capability, approval, or lifecycle controls.

Unlike endpoint descriptors, HermesOperatorPolicy does not deny unknown JSON fields at this revision. Serde ignores an unrecognized key. Treat such a key as an invalid deployment input during review; its presence is not evidence that a control is active.

Disabled-delegation example

This complete file preserves first-class delegation as disabled while making the operator limits explicit:

{
  "delegation_enabled": false,
  "delegation_requires_approval": true,
  "model": null,
  "system_instructions": "Operate only within the admitted AIP contract.",
  "timeout_ms": 900000,
  "poll_interval_ms": 250,
  "max_events": 4096,
  "max_input_bytes": 1048576,
  "max_delegation_depth": 16,
  "start_claim_ttl_ms": 60000,
  "cancel_grace_ms": 15000,
  "allowed_capability_prefixes": [],
  "allowed_scope_prefixes": []
}

The built-in system instructions contain additional invariants. Replacing them with this short example changes behavior; use a reviewed deployment policy, not the example text, for production.

Shared process and peer settings

For each peer DID, configure the inline value or file, not both. Both peers are required and must decode to usable verification keys.

Public and control endpoints require HTTPS, contain no embedded credentials, query, or fragment, and use their protocol paths. The HTTP exception is valid only when explicitly enabled for a loopback listener and loopback URLs.

The shared TLS CA is not passed into the default Hermes HTTP client by this binary. Configure Hermes provider trust through the process or container trust store, and review it independently from the control, callback, and event root.

Durable storage and replica identity

Hermes operator run bindings, approvals, native actions, streams, and other runtime projections share this PostgreSQL boundary. Do not move one replica to a different database while claiming the same instance and durable state.

Tenant and external-account settings

External-account ID and system must be configured together or omitted together. Every endpoint tenant must equal the shared host tenant. A normal Hermes host uses hermes_agent as its external-account system by deployment convention; the common parser validates the pair but does not require that literal.

Trust, topology, and secret-provider identity

Topology values describe the replica to the registry. They do not move a process, configure the network, or raise local concurrency.

The secret-provider reference is not a Hermes token. The binary reads actual endpoint tokens only from descriptor-selected files.

Credential identity and revision policy

ID, issuer, at least one scope, and revision must be configured together or all omitted. A configured credential handle is tenant-bound. Its revision must be authorized at startup and immediately before provider side effects.

The policy object has current_revision_ref, accepted_previous_revisions, and revoked_revisions. Entries cannot overlap, and each opaque revision is 1 through 256 bytes. A read, parse, validation, or authorization failure denies provider work.

This revision policy does not load, choose, or reload an endpoint token.

Callback and event-delivery settings

Both dispatchers use the host signing identity and optional private TLS root. Setting an exception without its corresponding endpoint fails startup. These settings do not configure Hermes MCP or model-provider callbacks.

Lifecycle and resource limits

The common host also fixes a 4 MiB canonical manifest limit, 512 capability definitions, and a 4 MiB native request-body limit. This binary exposes no environment setting for those three bounds.

File requirements

The reader validates metadata before and after opening a file. On Unix it also rejects an inode or device change during the read.

Configuration supplements

These snippets contain only Hermes additions. They are not complete host or production configurations and contain no token bytes.

One endpoint with built-in operator policy

AIP_HERMES_ENDPOINTS_FILE=/etc/aip/hermes-endpoints.json

Explicit operator policy

AIP_HERMES_ENDPOINTS_FILE=/etc/aip/hermes-endpoints.json
AIP_HERMES_OPERATOR_POLICY_FILE=/etc/aip/hermes-operator-policy.json

Tenant and external-account alignment

AIP_CONNECTOR_HOST_TENANT_ID=tenant-acme
AIP_CONNECTOR_HOST_EXTERNAL_ACCOUNT_ID=primary-hermes
AIP_CONNECTOR_HOST_EXTERNAL_ACCOUNT_SYSTEM=hermes_agent

The endpoint file should either omit tenant_id or use the exact tenant-acme value in this supplement.

Startup and reload behavior

Startup proceeds in this order:

1. Parse Hermes-specific and common host arguments.
2. Read and validate the endpoint descriptor array.
3. Normalize endpoints, bind every endpoint to the host tenant, and read API keys.
4. Build the 35-operation-per-endpoint connector and default HTTP client.
5. Read and validate the optional operator policy.
6. Validate host identity, trust, endpoints, files, limits, and credential policy.
7. Discover and validate the source-derived manifest without provider I/O.
8. Open PostgreSQL runtime stores and attach operator, approval, action, and lifecycle state.
9. Register, acquire a lease, become ready, and serve the common host surface.

Readiness includes durable storage and connector-local health across the configured endpoint set. A syntactically valid configuration can remain unready because admission, registration, storage, TLS, DNS, or provider health fails.

Configuration failures

Related documentation

• Authenticate and bind Hermes endpoints
• Hermes Agent connector
• Shared connector-host configuration
• Rotate connector credentials
• Security model