{
  "schemaVersion": "1.0",
  "title": "Hermes Agent connector configuration",
  "description": "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.",
  "canonical": "https://getaip.org/docs/connectors/hermes-agent/reference/configuration",
  "route": "/docs/connectors/hermes-agent/reference/configuration",
  "source": "docs/connectors/hermes-agent/reference/configuration.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Connectors",
  "documentType": "Connector",
  "language": "en",
  "downloads": {
    "md": "/docs/download/connectors/hermes-agent/reference/configuration.md",
    "txt": "/docs/download/connectors/hermes-agent/reference/configuration.txt",
    "json": "/docs/download/connectors/hermes-agent/reference/configuration.json",
    "pdf": "/docs/download/connectors/hermes-agent/reference/configuration.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Hermes Agent connector configuration\ndescription: >-\n  Look up every Hermes endpoint, operator-policy, and shared host setting,\n  default, constraint, and reload boundary\nkind: reference\naudience: operator\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\nconnector: hermes-agent\n---\n\n# Hermes Agent connector configuration\n\nThis reference describes the configuration accepted by\n`aip-host-hermes-agent` at the reviewed source revision. A complete process\ncombines two Hermes-specific file settings with the 45 shared connector-host\nsettings.\n\nEndpoint, operator-policy, identity, topology, limit, and provider-token values\nare read at startup. Only the optional shared credential-revision policy is\nre-read before provider side effects.\n\n## Configuration identity\n\n| Property | Value |\n|---|---|\n| Binary | `aip-host-hermes-agent` |\n| AIP workspace version | `1.0.0` |\n| Reviewed AIP source | `97be86e9efedf07ecf1783b03800f683f107fb04` |\n| Connector ID | `hermes-agent` |\n| Connector profile | `aip.connector.hermes_agent.v1` |\n| Pinned Hermes source | `7426c09beee73bdff94d916015bac71384f6bc92` |\n| Capability shape | `cap:hermes_agent:<endpoint_id>:<operation>` |\n| Capability count | 35 per configured endpoint |\n\nEvery setting is available through the listed environment variable. The two\nHermes-specific settings also expose the listed command-line flag. Shared\nsettings use the equivalent kebab-case connector-host flag.\n\nEnvironment variables and flags contain non-secret values or paths. Endpoint\ntokens, database credentials, and signing material belong in bounded files.\n\n## Hermes-specific settings\n\n| Environment variable | Command-line flag | Required | Default | Meaning |\n|---|---|---:|---|---|\n| `AIP_HERMES_ENDPOINTS_FILE` | `--endpoints-file` | Yes | None | JSON array of endpoint descriptors |\n| `AIP_HERMES_OPERATOR_POLICY_FILE` | `--operator-policy-file` | No | Built-in policy | JSON operator and first-class delegation policy |\n\nThe endpoint file is required even when it contains only one endpoint. The\noperator-policy file is optional; omission uses the built-in governed operator\npolicy with first-class delegation disabled.\n\n## Endpoint descriptor file\n\nThe endpoint file is a non-empty JSON array. This example contains no secret\nbytes:\n\n```json\n[\n  {\n    \"id\": \"primary\",\n    \"base_url\": \"https://hermes-primary.example.internal:8642\",\n    \"api_key_file\": \"/run/secrets/hermes-primary-api-key\",\n    \"display_name\": \"Primary Hermes\",\n    \"tenant_id\": \"tenant-acme\"\n  }\n]\n```\n\n### Descriptor fields\n\n| Field | Required | Default | Validation and effect |\n|---|---:|---|---|\n| `id` | Yes | None | Trimmed, restricted to ASCII alphanumeric, `-`, or `_`, then lowercased; becomes the capability segment |\n| `base_url` | Yes | None | URL using the `http` or `https` scheme; fixed source of Hermes request URLs |\n| `api_key_file` | No | None | Owner-only file containing the Bearer token for protected operations |\n| `display_name` | No | None | Retained in endpoint configuration; not projected into capability names, routing, or the manifest |\n| `tenant_id` | No | Host tenant | Must exactly equal `AIP_CONNECTOR_HOST_TENANT_ID` when supplied |\n\nEndpoint objects reject unknown fields. IDs that collide after trimming and\nlowercasing make connector construction fail. Action input cannot replace an\nendpoint ID, URL, tenant, or token.\n\nThe URL parser enforces only a valid `http` or `https` URL. It does not prove\ndestination ownership or impose the stricter credential, query, fragment, and\norigin rules used by shared host endpoints. Deployment policy should require a\ncredential-free HTTPS origin outside a controlled local network.\n\n### Endpoint bounds and manifest effects\n\n| Limit | Reviewed value |\n|---|---:|\n| Descriptor file | 1 byte through 4 MiB |\n| Descriptor count accepted by parser | 1 through 1000 |\n| API-key file | 1 byte through 16 KiB before UTF-8 and trimming checks |\n| Generated capabilities | 35 per endpoint |\n| Common host capability ceiling | 512 |\n| Effective endpoint ceiling | 14, producing 490 capabilities |\n\nFifteen endpoints produce 525 capabilities and fail common host preparation.\nThe parser's 1000-item bound is therefore not a deployable catalog limit.\n\nChanging endpoint IDs, base URLs, tenant values, or membership changes the\ndiscovered manifest and requires a corresponding immutable version and\nadmission update. Changing only token bytes or `display_name` does not alter\nthe current manifest, but a new process must load those startup values.\n\n### Provider authentication and client constants\n\nBasic `health` is the only operation that does not require an endpoint token.\nThe other 34 operations fail with\n`connector.hermes_agent.missing_credential` when no usable key is loaded.\nProtected requests use `Authorization: Bearer <endpoint key>`.\n\nThe default Hermes client has these fixed properties:\n\n| Property | Fixed value |\n|---|---:|\n| Redirect policy | No redirects |\n| Connect timeout | 10 seconds |\n| Overall client timeout | 900 seconds |\n| Basic health timeout | 30 seconds |\n| Default direct-stream event limit | 4096 events |\n\nOperation-specific request and stream paths can apply narrower bounds. These\nconstants are not environment settings.\n\n## Operator-policy file\n\nThe optional operator-policy file is a non-secret JSON object of at most\n512 KiB. It is parsed and validated once at startup.\n\nOmitting the file constructs the complete built-in defaults. Supplying a file\ndoes not merge it with those defaults: every field marked required below must\nbe present.\n\n| JSON field | Required in file | Built-in default | Validation or meaning |\n|---|---:|---|---|\n| `delegation_enabled` | Yes | `false` | Enables first-class delegation routing; does not enable the direct operator capability |\n| `delegation_requires_approval` | Yes | `true` | Requires runtime-verified durable approval for delegated work |\n| `delegation_approval_exempt_capability_prefixes` | No | `[]` | Narrow capability prefixes that bypass only the connector-level delegation approval gate |\n| `model` | No | `null` | Optional Hermes model route selected by deployment policy |\n| `system_instructions` | Yes | Built-in governed operator instructions | Non-empty, at most 131072 bytes |\n| `timeout_ms` | Yes | `900000` | 1000 through 86400000 |\n| `poll_interval_ms` | Yes | `250` | 10 through 60000 |\n| `max_events` | Yes | `4096` | 1 through 100000 |\n| `max_input_bytes` | Yes | `1048576` | 1024 through 16777216 |\n| `max_delegation_depth` | Yes | `16` | 1 through 128 |\n| `start_claim_ttl_ms` | Yes | `60000` | 1000 through 300000 |\n| `cancel_grace_ms` | Yes | `15000` | 1000 through 300000 |\n| `allowed_capability_prefixes` | No | `[]` | Delegated child-capability prefixes |\n| `allowed_scope_prefixes` | No | `[]` | Delegated scope prefixes |\n\nEvery prefix must be non-empty after trimming and at most 512 bytes. When\n`delegation_enabled` is `true`, both allowed-prefix lists must be non-empty.\nThe literal `*` explicitly opts into an unrestricted dimension; use a complete\ncapability or narrow namespace whenever possible.\n\nApproval-exempt prefixes waive only this connector's delegation approval gate.\nThey do not bypass native AIP authorization, tenant, scope, capability,\napproval, or lifecycle controls.\n\nUnlike endpoint descriptors, `HermesOperatorPolicy` does not deny unknown JSON\nfields at this revision. Serde ignores an unrecognized key. Treat such a key as\nan invalid deployment input during review; its presence is not evidence that a\ncontrol is active.\n\n### Disabled-delegation example\n\nThis complete file preserves first-class delegation as disabled while making\nthe operator limits explicit:\n\n```json\n{\n  \"delegation_enabled\": false,\n  \"delegation_requires_approval\": true,\n  \"model\": null,\n  \"system_instructions\": \"Operate only within the admitted AIP contract.\",\n  \"timeout_ms\": 900000,\n  \"poll_interval_ms\": 250,\n  \"max_events\": 4096,\n  \"max_input_bytes\": 1048576,\n  \"max_delegation_depth\": 16,\n  \"start_claim_ttl_ms\": 60000,\n  \"cancel_grace_ms\": 15000,\n  \"allowed_capability_prefixes\": [],\n  \"allowed_scope_prefixes\": []\n}\n```\n\nThe built-in system instructions contain additional invariants. Replacing them\nwith this short example changes behavior; use a reviewed deployment policy, not\nthe example text, for production.\n\n## Shared process and peer settings\n\n| Environment variable | Required | Default | Meaning and constraint |\n|---|---:|---|---|\n| `AIP_CONNECTOR_HOST_BIND` | No | `0.0.0.0:8081` | Local listener behind deployment ingress |\n| `AIP_CONNECTOR_HOST_PUBLIC_ENDPOINT` | Yes | None | Advertised URL ending exactly in `/aip/v1/messages` |\n| `AIP_CONNECTOR_HOST_CONTROL_ENDPOINT` | Yes | None | Lifecycle URL using the exact connector-control path |\n| `AIP_CONNECTOR_HOST_CONTROL_DID` | Alternative | None | Inline lifecycle control-plane `did:key` |\n| `AIP_CONNECTOR_HOST_CONTROL_DID_FILE` | Alternative | None | Owner-only file containing the control-plane `did:key` |\n| `AIP_CONNECTOR_HOST_GATEWAY_PRINCIPAL_ID` | Yes | None | Only central gateway principal accepted by the host |\n| `AIP_CONNECTOR_HOST_GATEWAY_DID` | Alternative | None | Inline central gateway `did:key` |\n| `AIP_CONNECTOR_HOST_GATEWAY_DID_FILE` | Alternative | None | Owner-only file containing the gateway `did:key` |\n| `AIP_CONNECTOR_HOST_TLS_CA_FILE` | No | None | Optional PEM root for control-plane, callback, and event clients |\n| `AIP_CONNECTOR_HOST_ALLOW_LOOPBACK_HTTP` | No | `false` | Allows public and control HTTP only with loopback bind and loopback URLs |\n\nFor each peer DID, configure the inline value or file, not both. Both peers are\nrequired and must decode to usable verification keys.\n\nPublic and control endpoints require HTTPS, contain no embedded credentials,\nquery, or fragment, and use their protocol paths. The HTTP exception is valid\nonly when explicitly enabled for a loopback listener and loopback URLs.\n\nThe shared TLS CA is not passed into the default Hermes HTTP client by this\nbinary. Configure Hermes provider trust through the process or container trust\nstore, and review it independently from the control, callback, and event root.\n\n## Durable storage and replica identity\n\n| Environment variable | Required | Default | Meaning and constraint |\n|---|---:|---|---|\n| `AIP_CONNECTOR_HOST_DATABASE_URL_FILE` | Yes | None | Owner-only PostgreSQL URL file for all host and Hermes operator state |\n| `AIP_CONNECTOR_HOST_SIGNING_SEED_FILE` | Yes | None | Owner-only file containing a 32-byte Ed25519 seed as 64 hexadecimal characters |\n| `AIP_CONNECTOR_HOST_TYPE_ID` | Yes | None | Admitted Hermes connector type ID |\n| `AIP_CONNECTOR_HOST_VERSION_ID` | Yes | None | Immutable admitted connector version ID |\n| `AIP_CONNECTOR_HOST_INSTANCE_ID` | Yes | None | Logical tenant-owned Hermes instance |\n| `AIP_CONNECTOR_HOST_REPLICA_ID` | Yes | None | Pre-provisioned concrete process identity |\n| `AIP_CONNECTOR_HOST_ARTIFACT_DIGEST` | Yes | None | Exact immutable OCI SHA-256 digest for the running host |\n| `AIP_CONNECTOR_HOST_CONFIG_REVISION` | No | `1` | Positive monotonic non-secret configuration revision |\n\nHermes operator run bindings, approvals, native actions, streams, and other\nruntime projections share this PostgreSQL boundary. Do not move one replica to\na different database while claiming the same instance and durable state.\n\n## Tenant and external-account settings\n\n| Environment variable | Required | Default | Meaning and constraint |\n|---|---:|---|---|\n| `AIP_CONNECTOR_HOST_TENANT_ID` | Yes | None | Verified tenant owned by this instance; 1 through 512 bytes |\n| `AIP_CONNECTOR_HOST_TENANT_SYSTEM` | No | None | Optional source system for the tenant reference |\n| `AIP_CONNECTOR_HOST_MEMBERSHIP_ID` | Yes | None | Stable verified membership assertion; 1 through 512 bytes |\n| `AIP_CONNECTOR_HOST_EXTERNAL_ACCOUNT_ID` | Pair | None | Stable Hermes deployment or endpoint-set reference; 1 through 512 bytes |\n| `AIP_CONNECTOR_HOST_EXTERNAL_ACCOUNT_SYSTEM` | Pair | None | Product name for the account reference; 1 through 128 bytes |\n\nExternal-account ID and system must be configured together or omitted\ntogether. Every endpoint tenant must equal the shared host tenant. A normal\nHermes host uses `hermes_agent` as its external-account system by deployment\nconvention; the common parser validates the pair but does not require that\nliteral.\n\n## Trust, topology, and secret-provider identity\n\n| Environment variable | Required | Default | Meaning and constraint |\n|---|---:|---|---|\n| `AIP_CONNECTOR_HOST_TRUST_DOMAIN` | Yes | None | Shared host, gateway, and lifecycle trust domain; at most 253 bytes |\n| `AIP_CONNECTOR_HOST_REGION` | No | `global` | Topology-aware routing region |\n| `AIP_CONNECTOR_HOST_ZONE` | No | `default` | Independent failure zone |\n| `AIP_CONNECTOR_HOST_CAPACITY_CLASS` | No | `standard` | Operator-defined capacity class |\n| `AIP_CONNECTOR_HOST_SECRET_PROVIDER_REF` | Yes | None | Non-secret secret-provider reference; at most 2048 bytes |\n\nTopology values describe the replica to the registry. They do not move a\nprocess, configure the network, or raise local concurrency.\n\nThe secret-provider reference is not a Hermes token. The binary reads actual\nendpoint tokens only from descriptor-selected files.\n\n## Credential identity and revision policy\n\n| Environment variable | Required | Default | Meaning and constraint |\n|---|---:|---|---|\n| `AIP_CONNECTOR_HOST_CREDENTIAL_ID` | Group | None | Opaque non-secret credential handle ID |\n| `AIP_CONNECTOR_HOST_CREDENTIAL_ISSUER` | Group | None | Trusted handle issuer |\n| `AIP_CONNECTOR_HOST_CREDENTIAL_SCOPES` | Group | Empty | Comma-delimited or repeatable non-empty verified scopes |\n| `AIP_CONNECTOR_HOST_CREDENTIAL_REVISION` | Group | None | Opaque assignment-pinned revision, 1 through 256 bytes |\n| `AIP_CONNECTOR_HOST_CREDENTIAL_POLICY_FILE` | No | Static current revision | Reloadable non-secret JSON authorization policy |\n\nID, issuer, at least one scope, and revision must be configured together or all\nomitted. A configured credential handle is tenant-bound. Its revision must be\nauthorized at startup and immediately before provider side effects.\n\nThe policy object has `current_revision_ref`,\n`accepted_previous_revisions`, and `revoked_revisions`. Entries cannot overlap,\nand each opaque revision is 1 through 256 bytes. A read, parse, validation, or\nauthorization failure denies provider work.\n\nThis revision policy does not load, choose, or reload an endpoint token.\n\n## Callback and event-delivery settings\n\n| Environment variable | Required | Default | Meaning and constraint |\n|---|---:|---|---|\n| `AIP_CONNECTOR_HOST_CALLBACK_ENDPOINT` | No | None | Fixed central result and stream callback endpoint |\n| `AIP_CONNECTOR_HOST_CALLBACK_ALLOW_HTTP` | No | `false` | Controlled-network HTTP exception; requires a callback endpoint |\n| `AIP_CONNECTOR_HOST_CALLBACK_ALLOW_PRIVATE` | No | `false` | Private-address exception; requires a callback endpoint |\n| `AIP_CONNECTOR_HOST_EVENT_ENDPOINT` | No | None | Fixed central connector-event ingress endpoint |\n| `AIP_CONNECTOR_HOST_EVENT_ALLOW_HTTP` | No | `false` | Controlled-network HTTP exception; requires an event endpoint |\n| `AIP_CONNECTOR_HOST_EVENT_ALLOW_PRIVATE` | No | `false` | Private-address exception; requires an event endpoint |\n\nBoth dispatchers use the host signing identity and optional private TLS root.\nSetting an exception without its corresponding endpoint fails startup. These\nsettings do not configure Hermes MCP or model-provider callbacks.\n\n## Lifecycle and resource limits\n\n| Environment variable | Default | Valid range or relation | Effect |\n|---|---:|---|---|\n| `AIP_CONNECTOR_HOST_MAX_IN_FLIGHT` | `32` | Greater than zero | Concurrent action permits for one replica |\n| `AIP_CONNECTOR_HOST_LEASE_TTL_MS` | `30000` | 1000 through 300000 | Registry lease lifetime |\n| `AIP_CONNECTOR_HOST_HEARTBEAT_MS` | `10000` | Greater than zero and at most half the lease TTL | Lease renewal interval |\n| `AIP_CONNECTOR_HOST_DRAIN_TIMEOUT_MS` | `30000` | 1 through 300000 | Graceful shutdown deadline |\n| `AIP_CONNECTOR_HOST_HEALTH_TIMEOUT_MS` | `2000` | 1 through 30000 | Product and storage readiness-probe deadline |\n| `AIP_CONNECTOR_HOST_CONTROL_TIMEOUT_MS` | `5000` | 1 through 30000 | Lifecycle control request timeout |\n\nThe common host also fixes a 4 MiB canonical manifest limit, 512 capability\ndefinitions, and a 4 MiB native request-body limit. This binary exposes no\nenvironment setting for those three bounds.\n\n## File requirements\n\n| File | Maximum | Content and permission rule |\n|---|---:|---|\n| Endpoint descriptors | 4 MiB | Non-empty JSON; regular non-symlink; no Unix group or world write bits |\n| Endpoint API key | 16 KiB | Non-empty UTF-8 after trimming; regular non-symlink; no Unix group or world permission bits |\n| Operator policy | 512 KiB | Valid JSON object; regular non-symlink; no Unix group or world write bits |\n| PostgreSQL URL | 16 KiB | Same owner-only secret-file checks as endpoint keys |\n| Host signing seed | 256 bytes read bound | Exactly 64 hexadecimal characters encoding 32 bytes; owner-only secret-file checks |\n| Gateway or control-plane DID | 512 bytes | Non-empty DID text; owner-only secret-file checks |\n| TLS CA | 1 MiB | Regular non-symlink; no Unix group or world write bits |\n| Credential revision policy | 64 KiB | Valid bounded JSON; regular non-symlink; no Unix group or world write bits |\n\nThe reader validates metadata before and after opening a file. On Unix it also\nrejects an inode or device change during the read.\n\n## Configuration supplements\n\nThese snippets contain only Hermes additions. They are not complete host or\nproduction configurations and contain no token bytes.\n\n### One endpoint with built-in operator policy\n\n```text\nAIP_HERMES_ENDPOINTS_FILE=/etc/aip/hermes-endpoints.json\n```\n\n### Explicit operator policy\n\n```text\nAIP_HERMES_ENDPOINTS_FILE=/etc/aip/hermes-endpoints.json\nAIP_HERMES_OPERATOR_POLICY_FILE=/etc/aip/hermes-operator-policy.json\n```\n\n### Tenant and external-account alignment\n\n```text\nAIP_CONNECTOR_HOST_TENANT_ID=tenant-acme\nAIP_CONNECTOR_HOST_EXTERNAL_ACCOUNT_ID=primary-hermes\nAIP_CONNECTOR_HOST_EXTERNAL_ACCOUNT_SYSTEM=hermes_agent\n```\n\nThe endpoint file should either omit `tenant_id` or use the exact\n`tenant-acme` value in this supplement.\n\n## Startup and reload behavior\n\nStartup proceeds in this order:\n\n1. Parse Hermes-specific and common host arguments.\n2. Read and validate the endpoint descriptor array.\n3. Normalize endpoints, bind every endpoint to the host tenant, and read API\n   keys.\n4. Build the 35-operation-per-endpoint connector and default HTTP client.\n5. Read and validate the optional operator policy.\n6. Validate host identity, trust, endpoints, files, limits, and credential\n   policy.\n7. Discover and validate the source-derived manifest without provider I/O.\n8. Open PostgreSQL runtime stores and attach operator, approval, action, and\n   lifecycle state.\n9. Register, acquire a lease, become ready, and serve the common host surface.\n\n| Setting class | Reload behavior at the reviewed source |\n|---|---|\n| Credential-revision policy JSON | Re-read before provider side effects |\n| Endpoint API keys | Read once at startup |\n| Endpoint descriptor fields | Parsed once at startup |\n| Hermes operator policy | Parsed once at startup |\n| Identity, topology, delivery endpoints, TLS CA, and limits | Startup-only |\n\nReadiness includes durable storage and connector-local health across the\nconfigured endpoint set. A syntactically valid configuration can remain\nunready because admission, registration, storage, TLS, DNS, or provider health\nfails.\n\n## Configuration failures\n\n| Failure | Corrective decision |\n|---|---|\n| Endpoint array is empty, oversized, or malformed | Correct the bounded owner-controlled JSON file |\n| Descriptor has an unknown field | Remove the unsupported field; do not bypass strict parsing |\n| IDs collide after normalization | Assign distinct stable endpoint IDs and update admission |\n| Endpoint tenant differs | Place it in the matching tenant-owned instance |\n| Endpoint key file is unsafe | Correct the mount and permissions without printing the key |\n| Protected operation lacks a key | Add the correct endpoint file and replace the process |\n| Operator policy omits a required field | Supply a complete object or omit the file to use built-in defaults |\n| Operator policy contains an unknown field | Treat it as invalid even though this revision ignores the key |\n| Delegation lacks allowlists | Set both explicit lists or keep first-class delegation disabled |\n| Public or control endpoint is invalid | Restore its exact HTTPS path; use HTTP only for explicit loopback development |\n| Peer DID alternatives conflict | Keep the inline value or file, not both |\n| External-account or credential group is partial | Configure the complete group or omit it completely |\n| Credential policy denies the route revision | Correct the reviewed policy or roll forward; do not bypass authorization |\n| Heartbeat relation is invalid | Keep a nonzero heartbeat at or below half the lease TTL |\n| Host remains unready | Separate config, admission, storage, lease, TLS, endpoint, and provider evidence |\n\n## Related documentation\n\n- [Authenticate and bind Hermes endpoints](../getting-started/authentication-and-endpoints.md)\n- [Hermes Agent connector](../README.md)\n- [Shared connector-host configuration](../../../reference/connector-host-configuration.md)\n- [Rotate connector credentials](../../../guides/connector-credentials-and-rotation.md)\n- [Security model](../../../architecture/security-model.md)\n",
    "text": "Hermes Agent connector configuration\n\nThis reference describes the configuration accepted by\naip-host-hermes-agent at the reviewed source revision. A complete process\ncombines two Hermes-specific file settings with the 45 shared connector-host\nsettings.\n\nEndpoint, operator-policy, identity, topology, limit, and provider-token values\nare read at startup. Only the optional shared credential-revision policy is\nre-read before provider side effects.\n\nConfiguration identity\n\n| Property | Value |\n\n| Binary | aip-host-hermes-agent |\n| AIP workspace version | 1.0.0 |\n| Reviewed AIP source | 97be86e9efedf07ecf1783b03800f683f107fb04 |\n| Connector ID | hermes-agent |\n| Connector profile | aip.connector.hermesagent.v1 |\n| Pinned Hermes source | 7426c09beee73bdff94d916015bac71384f6bc92 |\n| Capability shape | cap:hermesagent:: |\n| Capability count | 35 per configured endpoint |\n\nEvery setting is available through the listed environment variable. The two\nHermes-specific settings also expose the listed command-line flag. Shared\nsettings use the equivalent kebab-case connector-host flag.\n\nEnvironment variables and flags contain non-secret values or paths. Endpoint\ntokens, database credentials, and signing material belong in bounded files.\n\nHermes-specific settings\n\n| Environment variable | Command-line flag | Required | Default | Meaning |\n\n| AIPHERMESENDPOINTSFILE | --endpoints-file | Yes | None | JSON array of endpoint descriptors |\n| AIPHERMESOPERATORPOLICYFILE | --operator-policy-file | No | Built-in policy | JSON operator and first-class delegation policy |\n\nThe endpoint file is required even when it contains only one endpoint. The\noperator-policy file is optional; omission uses the built-in governed operator\npolicy with first-class delegation disabled.\n\nEndpoint descriptor file\n\nThe endpoint file is a non-empty JSON array. This example contains no secret\nbytes:\n\n[\n  {\n    \"id\": \"primary\",\n    \"baseurl\": \"https://hermes-primary.example.internal:8642\",\n    \"apikeyfile\": \"/run/secrets/hermes-primary-api-key\",\n    \"displayname\": \"Primary Hermes\",\n    \"tenantid\": \"tenant-acme\"\n  }\n]\n\nDescriptor fields\n\n| Field | Required | Default | Validation and effect |\n\n| id | Yes | None | Trimmed, restricted to ASCII alphanumeric, -, or , then lowercased; becomes the capability segment |\n| baseurl | Yes | None | URL using the http or https scheme; fixed source of Hermes request URLs |\n| apikeyfile | No | None | Owner-only file containing the Bearer token for protected operations |\n| displayname | No | None | Retained in endpoint configuration; not projected into capability names, routing, or the manifest |\n| tenantid | No | Host tenant | Must exactly equal AIPCONNECTORHOSTTENANTID when supplied |\n\nEndpoint objects reject unknown fields. IDs that collide after trimming and\nlowercasing make connector construction fail. Action input cannot replace an\nendpoint ID, URL, tenant, or token.\n\nThe URL parser enforces only a valid http or https URL. It does not prove\ndestination ownership or impose the stricter credential, query, fragment, and\norigin rules used by shared host endpoints. Deployment policy should require a\ncredential-free HTTPS origin outside a controlled local network.\n\nEndpoint bounds and manifest effects\n\n| Limit | Reviewed value |\n\n| Descriptor file | 1 byte through 4 MiB |\n| Descriptor count accepted by parser | 1 through 1000 |\n| API-key file | 1 byte through 16 KiB before UTF-8 and trimming checks |\n| Generated capabilities | 35 per endpoint |\n| Common host capability ceiling | 512 |\n| Effective endpoint ceiling | 14, producing 490 capabilities |\n\nFifteen endpoints produce 525 capabilities and fail common host preparation.\nThe parser's 1000-item bound is therefore not a deployable catalog limit.\n\nChanging endpoint IDs, base URLs, tenant values, or membership changes the\ndiscovered manifest and requires a corresponding immutable version and\nadmission update. Changing only token bytes or displayname does not alter\nthe current manifest, but a new process must load those startup values.\n\nProvider authentication and client constants\n\nBasic health is the only operation that does not require an endpoint token.\nThe other 34 operations fail with\nconnector.hermesagent.missingcredential when no usable key is loaded.\nProtected requests use Authorization: Bearer .\n\nThe default Hermes client has these fixed properties:\n\n| Property | Fixed value |\n\n| Redirect policy | No redirects |\n| Connect timeout | 10 seconds |\n| Overall client timeout | 900 seconds |\n| Basic health timeout | 30 seconds |\n| Default direct-stream event limit | 4096 events |\n\nOperation-specific request and stream paths can apply narrower bounds. These\nconstants are not environment settings.\n\nOperator-policy file\n\nThe optional operator-policy file is a non-secret JSON object of at most\n512 KiB. It is parsed and validated once at startup.\n\nOmitting the file constructs the complete built-in defaults. Supplying a file\ndoes not merge it with those defaults: every field marked required below must\nbe present.\n\n| JSON field | Required in file | Built-in default | Validation or meaning |\n\n| delegationenabled | Yes | false | Enables first-class delegation routing; does not enable the direct operator capability |\n| delegationrequiresapproval | Yes | true | Requires runtime-verified durable approval for delegated work |\n| delegationapprovalexemptcapabilityprefixes | No | [] | Narrow capability prefixes that bypass only the connector-level delegation approval gate |\n| model | No | null | Optional Hermes model route selected by deployment policy |\n| systeminstructions | Yes | Built-in governed operator instructions | Non-empty, at most 131072 bytes |\n| timeoutms | Yes | 900000 | 1000 through 86400000 |\n| pollintervalms | Yes | 250 | 10 through 60000 |\n| maxevents | Yes | 4096 | 1 through 100000 |\n| maxinputbytes | Yes | 1048576 | 1024 through 16777216 |\n| maxdelegationdepth | Yes | 16 | 1 through 128 |\n| startclaimttlms | Yes | 60000 | 1000 through 300000 |\n| cancelgracems | Yes | 15000 | 1000 through 300000 |\n| allowedcapabilityprefixes | No | [] | Delegated child-capability prefixes |\n| allowedscopeprefixes | No | [] | Delegated scope prefixes |\n\nEvery prefix must be non-empty after trimming and at most 512 bytes. When\ndelegationenabled is true, both allowed-prefix lists must be non-empty.\nThe literal  explicitly opts into an unrestricted dimension; use a complete\ncapability or narrow namespace whenever possible.\n\nApproval-exempt prefixes waive only this connector's delegation approval gate.\nThey do not bypass native AIP authorization, tenant, scope, capability,\napproval, or lifecycle controls.\n\nUnlike endpoint descriptors, HermesOperatorPolicy does not deny unknown JSON\nfields at this revision. Serde ignores an unrecognized key. Treat such a key as\nan invalid deployment input during review; its presence is not evidence that a\ncontrol is active.\n\nDisabled-delegation example\n\nThis complete file preserves first-class delegation as disabled while making\nthe operator limits explicit:\n\n{\n  \"delegationenabled\": false,\n  \"delegationrequiresapproval\": true,\n  \"model\": null,\n  \"systeminstructions\": \"Operate only within the admitted AIP contract.\",\n  \"timeoutms\": 900000,\n  \"pollintervalms\": 250,\n  \"maxevents\": 4096,\n  \"maxinputbytes\": 1048576,\n  \"maxdelegationdepth\": 16,\n  \"startclaimttlms\": 60000,\n  \"cancelgracems\": 15000,\n  \"allowedcapabilityprefixes\": [],\n  \"allowedscopeprefixes\": []\n}\n\nThe built-in system instructions contain additional invariants. Replacing them\nwith this short example changes behavior; use a reviewed deployment policy, not\nthe example text, for production.\n\nShared process and peer settings\n\n| Environment variable | Required | Default | Meaning and constraint |\n\n| AIPCONNECTORHOSTBIND | No | 0.0.0.0:8081 | Local listener behind deployment ingress |\n| AIPCONNECTORHOSTPUBLICENDPOINT | Yes | None | Advertised URL ending exactly in /aip/v1/messages |\n| AIPCONNECTORHOSTCONTROLENDPOINT | Yes | None | Lifecycle URL using the exact connector-control path |\n| AIPCONNECTORHOSTCONTROLDID | Alternative | None | Inline lifecycle control-plane did:key |\n| AIPCONNECTORHOSTCONTROLDIDFILE | Alternative | None | Owner-only file containing the control-plane did:key |\n| AIPCONNECTORHOSTGATEWAYPRINCIPALID | Yes | None | Only central gateway principal accepted by the host |\n| AIPCONNECTORHOSTGATEWAYDID | Alternative | None | Inline central gateway did:key |\n| AIPCONNECTORHOSTGATEWAYDIDFILE | Alternative | None | Owner-only file containing the gateway did:key |\n| AIPCONNECTORHOSTTLSCAFILE | No | None | Optional PEM root for control-plane, callback, and event clients |\n| AIPCONNECTORHOSTALLOWLOOPBACKHTTP | No | false | Allows public and control HTTP only with loopback bind and loopback URLs |\n\nFor each peer DID, configure the inline value or file, not both. Both peers are\nrequired and must decode to usable verification keys.\n\nPublic and control endpoints require HTTPS, contain no embedded credentials,\nquery, or fragment, and use their protocol paths. The HTTP exception is valid\nonly when explicitly enabled for a loopback listener and loopback URLs.\n\nThe shared TLS CA is not passed into the default Hermes HTTP client by this\nbinary. Configure Hermes provider trust through the process or container trust\nstore, and review it independently from the control, callback, and event root.\n\nDurable storage and replica identity\n\n| Environment variable | Required | Default | Meaning and constraint |\n\n| AIPCONNECTORHOSTDATABASEURLFILE | Yes | None | Owner-only PostgreSQL URL file for all host and Hermes operator state |\n| AIPCONNECTORHOSTSIGNINGSEEDFILE | Yes | None | Owner-only file containing a 32-byte Ed25519 seed as 64 hexadecimal characters |\n| AIPCONNECTORHOSTTYPEID | Yes | None | Admitted Hermes connector type ID |\n| AIPCONNECTORHOSTVERSIONID | Yes | None | Immutable admitted connector version ID |\n| AIPCONNECTORHOSTINSTANCEID | Yes | None | Logical tenant-owned Hermes instance |\n| AIPCONNECTORHOSTREPLICAID | Yes | None | Pre-provisioned concrete process identity |\n| AIPCONNECTORHOSTARTIFACTDIGEST | Yes | None | Exact immutable OCI SHA-256 digest for the running host |\n| AIPCONNECTORHOSTCONFIGREVISION | No | 1 | Positive monotonic non-secret configuration revision |\n\nHermes operator run bindings, approvals, native actions, streams, and other\nruntime projections share this PostgreSQL boundary. Do not move one replica to\na different database while claiming the same instance and durable state.\n\nTenant and external-account settings\n\n| Environment variable | Required | Default | Meaning and constraint |\n\n| AIPCONNECTORHOSTTENANTID | Yes | None | Verified tenant owned by this instance; 1 through 512 bytes |\n| AIPCONNECTORHOSTTENANTSYSTEM | No | None | Optional source system for the tenant reference |\n| AIPCONNECTORHOSTMEMBERSHIPID | Yes | None | Stable verified membership assertion; 1 through 512 bytes |\n| AIPCONNECTORHOSTEXTERNALACCOUNTID | Pair | None | Stable Hermes deployment or endpoint-set reference; 1 through 512 bytes |\n| AIPCONNECTORHOSTEXTERNALACCOUNTSYSTEM | Pair | None | Product name for the account reference; 1 through 128 bytes |\n\nExternal-account ID and system must be configured together or omitted\ntogether. Every endpoint tenant must equal the shared host tenant. A normal\nHermes host uses hermesagent as its external-account system by deployment\nconvention; the common parser validates the pair but does not require that\nliteral.\n\nTrust, topology, and secret-provider identity\n\n| Environment variable | Required | Default | Meaning and constraint |\n\n| AIPCONNECTORHOSTTRUSTDOMAIN | Yes | None | Shared host, gateway, and lifecycle trust domain; at most 253 bytes |\n| AIPCONNECTORHOSTREGION | No | global | Topology-aware routing region |\n| AIPCONNECTORHOSTZONE | No | default | Independent failure zone |\n| AIPCONNECTORHOSTCAPACITYCLASS | No | standard | Operator-defined capacity class |\n| AIPCONNECTORHOSTSECRETPROVIDERREF | Yes | None | Non-secret secret-provider reference; at most 2048 bytes |\n\nTopology values describe the replica to the registry. They do not move a\nprocess, configure the network, or raise local concurrency.\n\nThe secret-provider reference is not a Hermes token. The binary reads actual\nendpoint tokens only from descriptor-selected files.\n\nCredential identity and revision policy\n\n| Environment variable | Required | Default | Meaning and constraint |\n\n| AIPCONNECTORHOSTCREDENTIALID | Group | None | Opaque non-secret credential handle ID |\n| AIPCONNECTORHOSTCREDENTIALISSUER | Group | None | Trusted handle issuer |\n| AIPCONNECTORHOSTCREDENTIALSCOPES | Group | Empty | Comma-delimited or repeatable non-empty verified scopes |\n| AIPCONNECTORHOSTCREDENTIALREVISION | Group | None | Opaque assignment-pinned revision, 1 through 256 bytes |\n| AIPCONNECTORHOSTCREDENTIALPOLICYFILE | No | Static current revision | Reloadable non-secret JSON authorization policy |\n\nID, issuer, at least one scope, and revision must be configured together or all\nomitted. A configured credential handle is tenant-bound. Its revision must be\nauthorized at startup and immediately before provider side effects.\n\nThe policy object has currentrevisionref,\nacceptedpreviousrevisions, and revokedrevisions. Entries cannot overlap,\nand each opaque revision is 1 through 256 bytes. A read, parse, validation, or\nauthorization failure denies provider work.\n\nThis revision policy does not load, choose, or reload an endpoint token.\n\nCallback and event-delivery settings\n\n| Environment variable | Required | Default | Meaning and constraint |\n\n| AIPCONNECTORHOSTCALLBACKENDPOINT | No | None | Fixed central result and stream callback endpoint |\n| AIPCONNECTORHOSTCALLBACKALLOWHTTP | No | false | Controlled-network HTTP exception; requires a callback endpoint |\n| AIPCONNECTORHOSTCALLBACKALLOWPRIVATE | No | false | Private-address exception; requires a callback endpoint |\n| AIPCONNECTORHOSTEVENTENDPOINT | No | None | Fixed central connector-event ingress endpoint |\n| AIPCONNECTORHOSTEVENTALLOWHTTP | No | false | Controlled-network HTTP exception; requires an event endpoint |\n| AIPCONNECTORHOSTEVENTALLOWPRIVATE | No | false | Private-address exception; requires an event endpoint |\n\nBoth dispatchers use the host signing identity and optional private TLS root.\nSetting an exception without its corresponding endpoint fails startup. These\nsettings do not configure Hermes MCP or model-provider callbacks.\n\nLifecycle and resource limits\n\n| Environment variable | Default | Valid range or relation | Effect |\n\n| AIPCONNECTORHOSTMAXINFLIGHT | 32 | Greater than zero | Concurrent action permits for one replica |\n| AIPCONNECTORHOSTLEASETTLMS | 30000 | 1000 through 300000 | Registry lease lifetime |\n| AIPCONNECTORHOSTHEARTBEATMS | 10000 | Greater than zero and at most half the lease TTL | Lease renewal interval |\n| AIPCONNECTORHOSTDRAINTIMEOUTMS | 30000 | 1 through 300000 | Graceful shutdown deadline |\n| AIPCONNECTORHOSTHEALTHTIMEOUTMS | 2000 | 1 through 30000 | Product and storage readiness-probe deadline |\n| AIPCONNECTORHOSTCONTROLTIMEOUTMS | 5000 | 1 through 30000 | Lifecycle control request timeout |\n\nThe common host also fixes a 4 MiB canonical manifest limit, 512 capability\ndefinitions, and a 4 MiB native request-body limit. This binary exposes no\nenvironment setting for those three bounds.\n\nFile requirements\n\n| File | Maximum | Content and permission rule |\n\n| Endpoint descriptors | 4 MiB | Non-empty JSON; regular non-symlink; no Unix group or world write bits |\n| Endpoint API key | 16 KiB | Non-empty UTF-8 after trimming; regular non-symlink; no Unix group or world permission bits |\n| Operator policy | 512 KiB | Valid JSON object; regular non-symlink; no Unix group or world write bits |\n| PostgreSQL URL | 16 KiB | Same owner-only secret-file checks as endpoint keys |\n| Host signing seed | 256 bytes read bound | Exactly 64 hexadecimal characters encoding 32 bytes; owner-only secret-file checks |\n| Gateway or control-plane DID | 512 bytes | Non-empty DID text; owner-only secret-file checks |\n| TLS CA | 1 MiB | Regular non-symlink; no Unix group or world write bits |\n| Credential revision policy | 64 KiB | Valid bounded JSON; regular non-symlink; no Unix group or world write bits |\n\nThe reader validates metadata before and after opening a file. On Unix it also\nrejects an inode or device change during the read.\n\nConfiguration supplements\n\nThese snippets contain only Hermes additions. They are not complete host or\nproduction configurations and contain no token bytes.\n\nOne endpoint with built-in operator policy\n\nAIPHERMESENDPOINTSFILE=/etc/aip/hermes-endpoints.json\n\nExplicit operator policy\n\nAIPHERMESENDPOINTSFILE=/etc/aip/hermes-endpoints.json\nAIPHERMESOPERATORPOLICYFILE=/etc/aip/hermes-operator-policy.json\n\nTenant and external-account alignment\n\nAIPCONNECTORHOSTTENANTID=tenant-acme\nAIPCONNECTORHOSTEXTERNALACCOUNTID=primary-hermes\nAIPCONNECTORHOSTEXTERNALACCOUNTSYSTEM=hermesagent\n\nThe endpoint file should either omit tenantid or use the exact\ntenant-acme value in this supplement.\n\nStartup and reload behavior\n\nStartup proceeds in this order:\n1. Parse Hermes-specific and common host arguments.\n2. Read and validate the endpoint descriptor array.\n3. Normalize endpoints, bind every endpoint to the host tenant, and read API\n   keys.\n4. Build the 35-operation-per-endpoint connector and default HTTP client.\n5. Read and validate the optional operator policy.\n6. Validate host identity, trust, endpoints, files, limits, and credential\n   policy.\n7. Discover and validate the source-derived manifest without provider I/O.\n8. Open PostgreSQL runtime stores and attach operator, approval, action, and\n   lifecycle state.\n9. Register, acquire a lease, become ready, and serve the common host surface.\n\n| Setting class | Reload behavior at the reviewed source |\n\n| Credential-revision policy JSON | Re-read before provider side effects |\n| Endpoint API keys | Read once at startup |\n| Endpoint descriptor fields | Parsed once at startup |\n| Hermes operator policy | Parsed once at startup |\n| Identity, topology, delivery endpoints, TLS CA, and limits | Startup-only |\n\nReadiness includes durable storage and connector-local health across the\nconfigured endpoint set. A syntactically valid configuration can remain\nunready because admission, registration, storage, TLS, DNS, or provider health\nfails.\n\nConfiguration failures\n\n| Failure | Corrective decision |\n\n| Endpoint array is empty, oversized, or malformed | Correct the bounded owner-controlled JSON file |\n| Descriptor has an unknown field | Remove the unsupported field; do not bypass strict parsing |\n| IDs collide after normalization | Assign distinct stable endpoint IDs and update admission |\n| Endpoint tenant differs | Place it in the matching tenant-owned instance |\n| Endpoint key file is unsafe | Correct the mount and permissions without printing the key |\n| Protected operation lacks a key | Add the correct endpoint file and replace the process |\n| Operator policy omits a required field | Supply a complete object or omit the file to use built-in defaults |\n| Operator policy contains an unknown field | Treat it as invalid even though this revision ignores the key |\n| Delegation lacks allowlists | Set both explicit lists or keep first-class delegation disabled |\n| Public or control endpoint is invalid | Restore its exact HTTPS path; use HTTP only for explicit loopback development |\n| Peer DID alternatives conflict | Keep the inline value or file, not both |\n| External-account or credential group is partial | Configure the complete group or omit it completely |\n| Credential policy denies the route revision | Correct the reviewed policy or roll forward; do not bypass authorization |\n| Heartbeat relation is invalid | Keep a nonzero heartbeat at or below half the lease TTL |\n| Host remains unready | Separate config, admission, storage, lease, TLS, endpoint, and provider evidence |\n\nRelated documentation\n• Authenticate and bind Hermes endpoints (../getting-started/authentication-and-endpoints.md)\n• Hermes Agent connector (../README.md)\n• Shared connector-host configuration (../../../reference/connector-host-configuration.md)\n• Rotate connector credentials (../../../guides/connector-credentials-and-rotation.md)\n• Security model (../../../architecture/security-model.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "e14353fd0b14aa88adcff25554c92a18ef474ca815beaef6de7f8f322ad8e0ed"
  }
}