{
  "schemaVersion": "1.0",
  "title": "Connector host configuration",
  "description": "This reference lists the common process configuration shared by every standalone connector host. Use it to configure the host identity, admitted artifact, tenant boundary, durable storage, central services, delivery routes, and lifecycle li",
  "canonical": "https://getaip.org/docs/reference/connector-host-configuration",
  "route": "/docs/reference/connector-host-configuration",
  "source": "docs/reference/connector-host-configuration.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Deploy and Operate",
  "documentType": "Reference",
  "language": "en",
  "downloads": {
    "md": "/docs/download/reference/connector-host-configuration.md",
    "txt": "/docs/download/reference/connector-host-configuration.txt",
    "json": "/docs/download/reference/connector-host-configuration.json",
    "pdf": "/docs/download/reference/connector-host-configuration.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Connector host configuration\ndescription: Look up the common identity, trust, storage, routing, and lifecycle settings for every connector host\nkind: reference\naudience: operator\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\n---\n\n# Connector host configuration\n\nThis reference lists the common process configuration shared by every\nstandalone connector host. Use it to configure the host identity, admitted\nartifact, tenant boundary, durable storage, central services, delivery routes,\nand lifecycle limits without searching each product implementation.\n\nThe contract is implemented by `ConnectorHostBootstrapArgs` at source revision\n`97be86e9efedf07ecf1783b03800f683f107fb04`. The Cal.diy, Hermes Agent,\nChatwoot, Dify, CrewAI, and Twenty host binaries all flatten this structure into\ntheir command-line interface. Each binary adds its own provider settings after\nthese common options.\n\nAll listed behaviors are implementation contracts for the reviewed revision.\nThey are not new AIP protocol requirements, and the defaults are not capacity\nrecommendations for an arbitrary production deployment.\n\n## Value sources\n\nEvery common option can be supplied as a command-line flag or through its\nlisted environment variable. Do not configure conflicting values in both\nplaces. Values shown as **Required** have no implementation default; the host\ncannot prepare without them or a required alternative.\n\nThe host does not accept database credentials or signing material as literal\ncommand-line values. It reads those secrets from bounded, owner-controlled\nfiles. Provider credentials use opaque handles and product-owned secret files;\nthey are never embedded in this common configuration.\n\n## Listener and central endpoints\n\n| CLI option | Environment variable | Default | Meaning and constraint |\n|---|---|---|---|\n| `--bind` | `AIP_CONNECTOR_HOST_BIND` | `0.0.0.0:8081` | Socket used by the host listener behind deployment ingress. |\n| `--public-endpoint` | `AIP_CONNECTOR_HOST_PUBLIC_ENDPOINT` | **Required** | Advertised native endpoint. It must be absolute and end exactly in `/aip/v1/messages`. |\n| `--control-plane-endpoint` | `AIP_CONNECTOR_HOST_CONTROL_ENDPOINT` | **Required** | Lifecycle service endpoint. It must be absolute and end exactly in `/aip/v1/connector-control`. |\n| `--callback-endpoint` | `AIP_CONNECTOR_HOST_CALLBACK_ENDPOINT` | Unset | Central stream callback endpoint. If set, its path must be exactly `/aip/v1/connector-callbacks`. |\n| `--event-endpoint` | `AIP_CONNECTOR_HOST_EVENT_ENDPOINT` | Unset | Central connector-event ingress. If set, its path must be exactly `/aip/v1/connector-events`. |\n\nEach URL requires a host and rejects embedded credentials, a query, and a\nfragment. The public and control endpoints require HTTPS. Plain HTTP is\naccepted only when `--allow-insecure-loopback-http` is enabled and both the\nlistener and the corresponding URL are loopback-scoped.\n\nCallback and event delivery have separate network exceptions. Their destination\nhost is pinned into the outbound allowlist during preparation. The common host\nuses its native signing identity for both delivery paths; a different callback\nor event signer is rejected.\n\n## Admitted connector identity\n\nThese values identify the exact registry objects that the process claims when\nit registers. They must match the admitted records; they do not create those\nrecords.\n\n| CLI option | Environment variable | Default | Meaning and constraint |\n|---|---|---|---|\n| `--connector-type-id` | `AIP_CONNECTOR_HOST_TYPE_ID` | **Required** | Stable connector implementation family. |\n| `--version-id` | `AIP_CONNECTOR_HOST_VERSION_ID` | **Required** | Immutable admitted connector version. |\n| `--instance-id` | `AIP_CONNECTOR_HOST_INSTANCE_ID` | **Required** | Tenant-owned logical provider boundary. |\n| `--replica-id` | `AIP_CONNECTOR_HOST_REPLICA_ID` | **Required** | Pre-provisioned concrete process replica. |\n| `--artifact-digest` | `AIP_CONNECTOR_HOST_ARTIFACT_DIGEST` | **Required** | Exact `sha256:` digest of the running host artifact. |\n| `--config-revision` | `AIP_CONNECTOR_HOST_CONFIG_REVISION` | `1` | Monotonic non-secret instance configuration revision; it must be greater than zero. |\n| `--secret-provider-ref` | `AIP_CONNECTOR_HOST_SECRET_PROVIDER_REF` | **Required** | Non-secret opaque secret-provider reference containing 1–2,048 bytes. |\n\n`--artifact-digest` accepts the canonical SHA-256 form: the `sha256:` prefix\nfollowed by 64 hexadecimal characters. A changed artifact, admitted version,\ninstance identity, or configuration revision must be reconciled through the\nregistry workflow rather than silently changed at process restart.\n\n## Tenant and external account boundary\n\n| CLI option | Environment variable | Default | Meaning and constraint |\n|---|---|---|---|\n| `--tenant-id` | `AIP_CONNECTOR_HOST_TENANT_ID` | **Required** | Verified tenant owned by this instance; 1–512 bytes. |\n| `--tenant-system` | `AIP_CONNECTOR_HOST_TENANT_SYSTEM` | Unset | Optional source system carried by the tenant reference. |\n| `--membership-id` | `AIP_CONNECTOR_HOST_MEMBERSHIP_ID` | **Required** | Stable membership assertion for the instance; 1–512 bytes. |\n| `--external-account-id` | `AIP_CONNECTOR_HOST_EXTERNAL_ACCOUNT_ID` | Unset | Stable provider account, workspace, application, or endpoint identifier; 1–512 bytes. |\n| `--external-account-system` | `AIP_CONNECTOR_HOST_EXTERNAL_ACCOUNT_SYSTEM` | Unset | Provider system paired with the external account; 1–128 bytes. |\n\nThe external account ID and system are one optional pair: configure both or\nneither. The host performs connector discovery with the configured tenant\nbefore it opens the listener. The resulting manifest is then bound to the\ndeployment trust domain and host signing identity.\n\n## Gateway and lifecycle trust\n\n| CLI option | Environment variable | Default | Meaning and constraint |\n|---|---|---|---|\n| `--gateway-principal-id` | `AIP_CONNECTOR_HOST_GATEWAY_PRINCIPAL_ID` | **Required** | Service principal trusted to submit signed native requests from the central gateway. |\n| `--gateway-did` | `AIP_CONNECTOR_HOST_GATEWAY_DID` | Alternative required | Inline `did:key` used to verify gateway requests. |\n| `--gateway-did-file` | `AIP_CONNECTOR_HOST_GATEWAY_DID_FILE` | Alternative required | Owner-controlled file containing the gateway `did:key`. |\n| `--control-plane-did` | `AIP_CONNECTOR_HOST_CONTROL_DID` | Alternative required | Inline `did:key` used to verify lifecycle responses. |\n| `--control-plane-did-file` | `AIP_CONNECTOR_HOST_CONTROL_DID_FILE` | Alternative required | Owner-controlled file containing the lifecycle `did:key`. |\n| `--signing-seed-file` | `AIP_CONNECTOR_HOST_SIGNING_SEED_FILE` | **Required** | Owner-controlled file containing the host Ed25519 seed as 64 hexadecimal characters. |\n| `--trust-domain` | `AIP_CONNECTOR_HOST_TRUST_DOMAIN` | **Required** | Shared gateway and host trust domain; 1–253 bytes. |\n| `--tls-ca-certificate-file` | `AIP_CONNECTOR_HOST_TLS_CA_FILE` | Unset | Additional PEM root for private-PKI outbound TLS; maximum 1 MiB. |\n\nConfigure exactly one gateway DID source and exactly one control-plane DID\nsource. Every DID value must parse as a `did:key` and contain no more than 512\nbytes. The host derives its own `did:key` from the configured signing seed; it\ndoes not accept the host DID as an independent setting.\n\nThe optional CA augments the public root set. Certificate and hostname\nverification remain enabled. The host supplies the root to lifecycle,\ncallback, and event delivery clients; it is not a switch for disabling TLS\nauthentication.\n\n## Durable storage\n\n| CLI option | Environment variable | Default | Meaning and constraint |\n|---|---|---|---|\n| `--database-url-file` | `AIP_CONNECTOR_HOST_DATABASE_URL_FILE` | **Required** | Owner-controlled UTF-8 file containing the connector runtime PostgreSQL URL; maximum 16 KiB. |\n\nPreparation reads the database URL, connects to PostgreSQL, and installs the\ndurable runtime schema before the process can serve. The common host constructs\nthe action, event, idempotency, profile, session, approval, transaction, and\nexecution stores from that backend. It does not fall back to ephemeral runtime\nstate.\n\nProduct hosts may bind their own durable projections to the same backend. The\nschema and database privileges required by a product remain part of its\nconnector-local configuration and deployment documentation.\n\n## Topology labels\n\n| CLI option | Environment variable | Default | Meaning and constraint |\n|---|---|---|---|\n| `--region` | `AIP_CONNECTOR_HOST_REGION` | `global` | Stable deployment or geographic region used for new route selection. |\n| `--zone` | `AIP_CONNECTOR_HOST_ZONE` | `default` | Independent failure zone within the region. |\n| `--capacity-class` | `AIP_CONNECTOR_HOST_CAPACITY_CLASS` | `standard` | Operator-defined class such as `standard` or `gpu`. |\n\nThe registry validates each label as at most 128 ASCII letters, digits, dots,\ndashes, or underscores. Labels are indexed routing coordinates, not\nhigh-cardinality metric dimensions. They influence creation of new route\nassignments; an existing durable assignment remains pinned to its exact\nreplica.\n\n## Opaque credential handle\n\nThe common host can bind a provider credential without receiving its secret\nvalue. The connector resolves the opaque handle inside its product boundary.\n\n| CLI option | Environment variable | Default | Meaning and constraint |\n|---|---|---|---|\n| `--credential-id` | `AIP_CONNECTOR_HOST_CREDENTIAL_ID` | Unset | Opaque provider credential handle. |\n| `--credential-issuer` | `AIP_CONNECTOR_HOST_CREDENTIAL_ISSUER` | Unset | Issuer for the handle. |\n| `--credential-scope` | `AIP_CONNECTOR_HOST_CREDENTIAL_SCOPES` | Unset | Verified scope; repeat the flag or use a comma-delimited environment value. |\n| `--credential-revision-ref` | `AIP_CONNECTOR_HOST_CREDENTIAL_REVISION` | Unset | Opaque revision pinned by route assignments; 1–256 bytes. |\n| `--credential-revision-policy-file` | `AIP_CONNECTOR_HOST_CREDENTIAL_POLICY_FILE` | Unset | Reloadable non-secret JSON authorization policy; maximum 64 KiB. |\n\nCredential ID, issuer, revision, and at least one non-empty scope form one\ntuple. Configure the complete tuple or omit all four. The common host fixes the\ncredential tenant to `--tenant-id`; a mismatched tenant is rejected.\n\nWithout a policy file, the process creates a static policy that authorizes only\nthe configured current revision. With a policy file, the host validates it at\nstartup and reloads it immediately before each provider side effect. An unreadable,\ninvalid, or non-authorizing file denies the action.\n\nThe file has this closed schema:\n\n```json\n{\n  \"current_revision_ref\": \"credential-revision-current\",\n  \"accepted_previous_revisions\": [\"credential-revision-previous\"],\n  \"revoked_revisions\": []\n}\n```\n\nUnknown fields are rejected. Each revision reference contains 1–256 bytes, and\nthe current, previous, and revoked sets cannot overlap. The complete replacement\nand emergency-revocation sequence belongs to\n[Rotate connector credentials](../guides/connector-credentials-and-rotation.md).\n\n## Callback and event network policy\n\n| CLI option | Environment variable | Default | Meaning and constraint |\n|---|---|---|---|\n| `--callback-allow-http` | `AIP_CONNECTOR_HOST_CALLBACK_ALLOW_HTTP` | `false` | Permit HTTP for the configured callback destination. |\n| `--callback-allow-private-networks` | `AIP_CONNECTOR_HOST_CALLBACK_ALLOW_PRIVATE` | `false` | Permit a private callback destination. |\n| `--event-allow-http` | `AIP_CONNECTOR_HOST_EVENT_ALLOW_HTTP` | `false` | Permit HTTP for the configured event-ingress destination. |\n| `--event-allow-private-networks` | `AIP_CONNECTOR_HOST_EVENT_ALLOW_PRIVATE` | `false` | Permit a private event-ingress destination. |\n\nA callback exception is invalid without `--callback-endpoint`; an event\nexception is invalid without `--event-endpoint`. These switches weaken only\nthe selected fixed outbound destination policy. They do not relax native\ningress, lifecycle endpoint, DID, signature, or path validation.\n\nProvider event publication also depends on host readiness. The built-in\npublisher accepts work only while the replica lease is valid, the host is not\ndraining, durable storage is ready, and the product connector reports ready.\n\n## Lifecycle and resource limits\n\n| CLI option | Environment variable | Default | Accepted value |\n|---|---|---|---|\n| `--allow-insecure-loopback-http` | `AIP_CONNECTOR_HOST_ALLOW_LOOPBACK_HTTP` | `false` | Boolean; only valid with a loopback listener. |\n| `--max-in-flight` | `AIP_CONNECTOR_HOST_MAX_IN_FLIGHT` | `32` | Integer greater than zero. |\n| `--lease-ttl-ms` | `AIP_CONNECTOR_HOST_LEASE_TTL_MS` | `30000` | 1,000–300,000 ms. |\n| `--heartbeat-interval-ms` | `AIP_CONNECTOR_HOST_HEARTBEAT_MS` | `10000` | Greater than zero and no more than half the lease TTL. |\n| `--drain-timeout-ms` | `AIP_CONNECTOR_HOST_DRAIN_TIMEOUT_MS` | `30000` | 1–300,000 ms. |\n| `--health-probe-timeout-ms` | `AIP_CONNECTOR_HOST_HEALTH_TIMEOUT_MS` | `2000` | 1–30,000 ms. |\n| `--control-timeout-ms` | `AIP_CONNECTOR_HOST_CONTROL_TIMEOUT_MS` | `5000` | 1–30,000 ms. |\n\n`max-in-flight` is the replica-local action bound. Fleet admission policies can\nimpose additional global, tenant, connector-type, instance, and binding limits.\nIncreasing the local value cannot bypass those controls.\n\nThe reviewed implementation also fixes three non-configurable host limits:\n\n| Limit | Value |\n|---|---:|\n| Maximum canonical manifest size | 4 MiB |\n| Maximum capabilities in one immutable connector version | 512 |\n| Maximum native AIP request body | 4 MiB |\n\n## File requirements\n\nEvery common file input must be a non-empty regular file, not a symbolic link,\nand must remain the same file while it is opened and read. The implementation\nenforces the configured byte limit before and during the read.\n\nOn Unix systems, secret inputs must have no group or world permission bits. A\nmode such as `0600` satisfies that check. This owner-only rule applies to the\ndatabase URL, signing seed, and current DID-file inputs.\n\nSecret text must be\nvalid UTF-8 after surrounding ASCII whitespace is removed, except for the seed,\nwhich is decoded as hexadecimal. Secret buffers are zeroized where the\nbootstrap API retains them temporarily.\n\nThe TLS CA and credential revision policy are non-secret configuration files.\nThey may be group/world readable, but they must not be group/world writable; a\nmode such as `0644` satisfies that check. Replace a reloadable policy atomically\nso a reader never observes a partial JSON document.\n\n## Coupling rules\n\nThe following relationships are validated before or during host construction:\n\n- loopback HTTP requires a loopback listener and loopback public and control\n  URL hosts;\n- gateway DID and gateway DID file are mutually exclusive alternatives;\n- control-plane DID and control-plane DID file are mutually exclusive\n  alternatives;\n- external account ID and external account system are present together;\n- credential ID, issuer, revision, and non-empty scopes are present together;\n- the credential tenant equals the instance tenant;\n- callback network exceptions require a callback endpoint;\n- event network exceptions require an event endpoint;\n- the signing principal and central gateway share the configured trust domain;\n- the heartbeat interval is no more than half the lease TTL;\n- artifact digest and configuration revision match admitted registry state.\n\nA coupling error is a configuration failure. Do not work around it by dropping\nidentity or transport validation; reconcile the deployment inputs with the\nadmitted records.\n\n## Preparation, serving, and readiness\n\nThe common bootstrap has two phases. `prepare` validates configuration and file\nmetadata, loads identities, performs tenant-scoped connector discovery, opens\ndurable PostgreSQL storage, and constructs the signed lifecycle client. It does\nnot register the replica.\n\nThe serving phase builds the host, recovers durable work, registers the exact\nreplica, renews its lease, exposes the common routes, drains on SIGTERM or\nCtrl-C, and marks the replica offline. Product binaries may add authenticated\nprovider ingress routes without changing the common native surface.\n\n| Route | Readiness meaning |\n|---|---|\n| `/health` | The process and protocol surface are responsive. |\n| `/ready` | Lease, drain state, durable storage, and product connector health allow new work. |\n| `/metrics` | Common host metrics are available. |\n| `/aip/v1/manifest` | The deployment-bound immutable manifest is available. |\n| `/aip/v1/messages` | Signed native AIP message ingress is available. |\n\nA successful process health response does not prove route eligibility. Use\n`/ready`, registry status, and tenant-scoped discovery together before enabling\na capability binding.\n\n## Error categories\n\nStartup and serving errors identify the boundary that rejected the host:\n\n| Category | Typical cause | Operator response |\n|---|---|---|\n| Bootstrap configuration | Missing coupled fields, unsafe file metadata, invalid URL, DID, digest, or limit | Correct the input; do not start traffic. |\n| Durable storage | PostgreSQL connection or schema installation failure | Restore database reachability and least-privilege schema access. |\n| Product discovery | Connector cannot publish its tenant-scoped manifest | Correct only the product-owned configuration, then repeat preparation. |\n| Host admission or control plane | Registry identity, trust, lease, or lifecycle response fails | Compare the process identity with admitted records and service trust. |\n| Listener | Socket cannot bind | Correct the address, port ownership, or deployment ingress mapping. |\n\nThe host fails closed on these errors. A restart with unchanged invalid inputs\ndoes not repair an admission, trust, credential policy, or file-permission\nfailure.\n\n## Product-specific configuration\n\nThis page intentionally ends at the common host boundary. Provider base URLs,\nAPI keys, OAuth material, webhook secrets, account identifiers, feature flags,\nand product-specific health behavior belong to the six connector-local\nconfiguration pages. Do not infer one connector's provider settings from\nanother connector or add an unreviewed connector to the public matrix.\n\nFor the complete deployment sequence, use\n[Deploy the connector fleet](../guides/deploy-connector-fleet.md). Review the\nsystem boundary in [Deploy AIP in production](../guides/production-deployment.md),\nthe signing model in [Identity and trust](../concepts/identity-and-trust.md),\nthe host implementation contract in\n[Build a connector](../guides/build-a-connector.md), and the integration model\nin [Profiles and connectors](../concepts/profiles-and-connectors.md).\n",
    "text": "Connector host configuration\n\nThis reference lists the common process configuration shared by every\nstandalone connector host. Use it to configure the host identity, admitted\nartifact, tenant boundary, durable storage, central services, delivery routes,\nand lifecycle limits without searching each product implementation.\n\nThe contract is implemented by ConnectorHostBootstrapArgs at source revision\n97be86e9efedf07ecf1783b03800f683f107fb04. The Cal.diy, Hermes Agent,\nChatwoot, Dify, CrewAI, and Twenty host binaries all flatten this structure into\ntheir command-line interface. Each binary adds its own provider settings after\nthese common options.\n\nAll listed behaviors are implementation contracts for the reviewed revision.\nThey are not new AIP protocol requirements, and the defaults are not capacity\nrecommendations for an arbitrary production deployment.\n\nValue sources\n\nEvery common option can be supplied as a command-line flag or through its\nlisted environment variable. Do not configure conflicting values in both\nplaces. Values shown as Required have no implementation default; the host\ncannot prepare without them or a required alternative.\n\nThe host does not accept database credentials or signing material as literal\ncommand-line values. It reads those secrets from bounded, owner-controlled\nfiles. Provider credentials use opaque handles and product-owned secret files;\nthey are never embedded in this common configuration.\n\nListener and central endpoints\n\n| CLI option | Environment variable | Default | Meaning and constraint |\n\n| --bind | AIPCONNECTORHOSTBIND | 0.0.0.0:8081 | Socket used by the host listener behind deployment ingress. |\n| --public-endpoint | AIPCONNECTORHOSTPUBLICENDPOINT | Required | Advertised native endpoint. It must be absolute and end exactly in /aip/v1/messages. |\n| --control-plane-endpoint | AIPCONNECTORHOSTCONTROLENDPOINT | Required | Lifecycle service endpoint. It must be absolute and end exactly in /aip/v1/connector-control. |\n| --callback-endpoint | AIPCONNECTORHOSTCALLBACKENDPOINT | Unset | Central stream callback endpoint. If set, its path must be exactly /aip/v1/connector-callbacks. |\n| --event-endpoint | AIPCONNECTORHOSTEVENTENDPOINT | Unset | Central connector-event ingress. If set, its path must be exactly /aip/v1/connector-events. |\n\nEach URL requires a host and rejects embedded credentials, a query, and a\nfragment. The public and control endpoints require HTTPS. Plain HTTP is\naccepted only when --allow-insecure-loopback-http is enabled and both the\nlistener and the corresponding URL are loopback-scoped.\n\nCallback and event delivery have separate network exceptions. Their destination\nhost is pinned into the outbound allowlist during preparation. The common host\nuses its native signing identity for both delivery paths; a different callback\nor event signer is rejected.\n\nAdmitted connector identity\n\nThese values identify the exact registry objects that the process claims when\nit registers. They must match the admitted records; they do not create those\nrecords.\n\n| CLI option | Environment variable | Default | Meaning and constraint |\n\n| --connector-type-id | AIPCONNECTORHOSTTYPEID | Required | Stable connector implementation family. |\n| --version-id | AIPCONNECTORHOSTVERSIONID | Required | Immutable admitted connector version. |\n| --instance-id | AIPCONNECTORHOSTINSTANCEID | Required | Tenant-owned logical provider boundary. |\n| --replica-id | AIPCONNECTORHOSTREPLICAID | Required | Pre-provisioned concrete process replica. |\n| --artifact-digest | AIPCONNECTORHOSTARTIFACTDIGEST | Required | Exact sha256: digest of the running host artifact. |\n| --config-revision | AIPCONNECTORHOSTCONFIGREVISION | 1 | Monotonic non-secret instance configuration revision; it must be greater than zero. |\n| --secret-provider-ref | AIPCONNECTORHOSTSECRETPROVIDERREF | Required | Non-secret opaque secret-provider reference containing 1–2,048 bytes. |\n\n--artifact-digest accepts the canonical SHA-256 form: the sha256: prefix\nfollowed by 64 hexadecimal characters. A changed artifact, admitted version,\ninstance identity, or configuration revision must be reconciled through the\nregistry workflow rather than silently changed at process restart.\n\nTenant and external account boundary\n\n| CLI option | Environment variable | Default | Meaning and constraint |\n\n| --tenant-id | AIPCONNECTORHOSTTENANTID | Required | Verified tenant owned by this instance; 1–512 bytes. |\n| --tenant-system | AIPCONNECTORHOSTTENANTSYSTEM | Unset | Optional source system carried by the tenant reference. |\n| --membership-id | AIPCONNECTORHOSTMEMBERSHIPID | Required | Stable membership assertion for the instance; 1–512 bytes. |\n| --external-account-id | AIPCONNECTORHOSTEXTERNALACCOUNTID | Unset | Stable provider account, workspace, application, or endpoint identifier; 1–512 bytes. |\n| --external-account-system | AIPCONNECTORHOSTEXTERNALACCOUNTSYSTEM | Unset | Provider system paired with the external account; 1–128 bytes. |\n\nThe external account ID and system are one optional pair: configure both or\nneither. The host performs connector discovery with the configured tenant\nbefore it opens the listener. The resulting manifest is then bound to the\ndeployment trust domain and host signing identity.\n\nGateway and lifecycle trust\n\n| CLI option | Environment variable | Default | Meaning and constraint |\n\n| --gateway-principal-id | AIPCONNECTORHOSTGATEWAYPRINCIPALID | Required | Service principal trusted to submit signed native requests from the central gateway. |\n| --gateway-did | AIPCONNECTORHOSTGATEWAYDID | Alternative required | Inline did:key used to verify gateway requests. |\n| --gateway-did-file | AIPCONNECTORHOSTGATEWAYDIDFILE | Alternative required | Owner-controlled file containing the gateway did:key. |\n| --control-plane-did | AIPCONNECTORHOSTCONTROLDID | Alternative required | Inline did:key used to verify lifecycle responses. |\n| --control-plane-did-file | AIPCONNECTORHOSTCONTROLDIDFILE | Alternative required | Owner-controlled file containing the lifecycle did:key. |\n| --signing-seed-file | AIPCONNECTORHOSTSIGNINGSEEDFILE | Required | Owner-controlled file containing the host Ed25519 seed as 64 hexadecimal characters. |\n| --trust-domain | AIPCONNECTORHOSTTRUSTDOMAIN | Required | Shared gateway and host trust domain; 1–253 bytes. |\n| --tls-ca-certificate-file | AIPCONNECTORHOSTTLSCAFILE | Unset | Additional PEM root for private-PKI outbound TLS; maximum 1 MiB. |\n\nConfigure exactly one gateway DID source and exactly one control-plane DID\nsource. Every DID value must parse as a did:key and contain no more than 512\nbytes. The host derives its own did:key from the configured signing seed; it\ndoes not accept the host DID as an independent setting.\n\nThe optional CA augments the public root set. Certificate and hostname\nverification remain enabled. The host supplies the root to lifecycle,\ncallback, and event delivery clients; it is not a switch for disabling TLS\nauthentication.\n\nDurable storage\n\n| CLI option | Environment variable | Default | Meaning and constraint |\n\n| --database-url-file | AIPCONNECTORHOSTDATABASEURLFILE | Required | Owner-controlled UTF-8 file containing the connector runtime PostgreSQL URL; maximum 16 KiB. |\n\nPreparation reads the database URL, connects to PostgreSQL, and installs the\ndurable runtime schema before the process can serve. The common host constructs\nthe action, event, idempotency, profile, session, approval, transaction, and\nexecution stores from that backend. It does not fall back to ephemeral runtime\nstate.\n\nProduct hosts may bind their own durable projections to the same backend. The\nschema and database privileges required by a product remain part of its\nconnector-local configuration and deployment documentation.\n\nTopology labels\n\n| CLI option | Environment variable | Default | Meaning and constraint |\n\n| --region | AIPCONNECTORHOSTREGION | global | Stable deployment or geographic region used for new route selection. |\n| --zone | AIPCONNECTORHOSTZONE | default | Independent failure zone within the region. |\n| --capacity-class | AIPCONNECTORHOSTCAPACITYCLASS | standard | Operator-defined class such as standard or gpu. |\n\nThe registry validates each label as at most 128 ASCII letters, digits, dots,\ndashes, or underscores. Labels are indexed routing coordinates, not\nhigh-cardinality metric dimensions. They influence creation of new route\nassignments; an existing durable assignment remains pinned to its exact\nreplica.\n\nOpaque credential handle\n\nThe common host can bind a provider credential without receiving its secret\nvalue. The connector resolves the opaque handle inside its product boundary.\n\n| CLI option | Environment variable | Default | Meaning and constraint |\n\n| --credential-id | AIPCONNECTORHOSTCREDENTIALID | Unset | Opaque provider credential handle. |\n| --credential-issuer | AIPCONNECTORHOSTCREDENTIALISSUER | Unset | Issuer for the handle. |\n| --credential-scope | AIPCONNECTORHOSTCREDENTIALSCOPES | Unset | Verified scope; repeat the flag or use a comma-delimited environment value. |\n| --credential-revision-ref | AIPCONNECTORHOSTCREDENTIALREVISION | Unset | Opaque revision pinned by route assignments; 1–256 bytes. |\n| --credential-revision-policy-file | AIPCONNECTORHOSTCREDENTIALPOLICYFILE | Unset | Reloadable non-secret JSON authorization policy; maximum 64 KiB. |\n\nCredential ID, issuer, revision, and at least one non-empty scope form one\ntuple. Configure the complete tuple or omit all four. The common host fixes the\ncredential tenant to --tenant-id; a mismatched tenant is rejected.\n\nWithout a policy file, the process creates a static policy that authorizes only\nthe configured current revision. With a policy file, the host validates it at\nstartup and reloads it immediately before each provider side effect. An unreadable,\ninvalid, or non-authorizing file denies the action.\n\nThe file has this closed schema:\n\n{\n  \"currentrevisionref\": \"credential-revision-current\",\n  \"acceptedpreviousrevisions\": [\"credential-revision-previous\"],\n  \"revokedrevisions\": []\n}\n\nUnknown fields are rejected. Each revision reference contains 1–256 bytes, and\nthe current, previous, and revoked sets cannot overlap. The complete replacement\nand emergency-revocation sequence belongs to\nRotate connector credentials (../guides/connector-credentials-and-rotation.md).\n\nCallback and event network policy\n\n| CLI option | Environment variable | Default | Meaning and constraint |\n\n| --callback-allow-http | AIPCONNECTORHOSTCALLBACKALLOWHTTP | false | Permit HTTP for the configured callback destination. |\n| --callback-allow-private-networks | AIPCONNECTORHOSTCALLBACKALLOWPRIVATE | false | Permit a private callback destination. |\n| --event-allow-http | AIPCONNECTORHOSTEVENTALLOWHTTP | false | Permit HTTP for the configured event-ingress destination. |\n| --event-allow-private-networks | AIPCONNECTORHOSTEVENTALLOWPRIVATE | false | Permit a private event-ingress destination. |\n\nA callback exception is invalid without --callback-endpoint; an event\nexception is invalid without --event-endpoint. These switches weaken only\nthe selected fixed outbound destination policy. They do not relax native\ningress, lifecycle endpoint, DID, signature, or path validation.\n\nProvider event publication also depends on host readiness. The built-in\npublisher accepts work only while the replica lease is valid, the host is not\ndraining, durable storage is ready, and the product connector reports ready.\n\nLifecycle and resource limits\n\n| CLI option | Environment variable | Default | Accepted value |\n\n| --allow-insecure-loopback-http | AIPCONNECTORHOSTALLOWLOOPBACKHTTP | false | Boolean; only valid with a loopback listener. |\n| --max-in-flight | AIPCONNECTORHOSTMAXINFLIGHT | 32 | Integer greater than zero. |\n| --lease-ttl-ms | AIPCONNECTORHOSTLEASETTLMS | 30000 | 1,000–300,000 ms. |\n| --heartbeat-interval-ms | AIPCONNECTORHOSTHEARTBEATMS | 10000 | Greater than zero and no more than half the lease TTL. |\n| --drain-timeout-ms | AIPCONNECTORHOSTDRAINTIMEOUTMS | 30000 | 1–300,000 ms. |\n| --health-probe-timeout-ms | AIPCONNECTORHOSTHEALTHTIMEOUTMS | 2000 | 1–30,000 ms. |\n| --control-timeout-ms | AIPCONNECTORHOSTCONTROLTIMEOUTMS | 5000 | 1–30,000 ms. |\n\nmax-in-flight is the replica-local action bound. Fleet admission policies can\nimpose additional global, tenant, connector-type, instance, and binding limits.\nIncreasing the local value cannot bypass those controls.\n\nThe reviewed implementation also fixes three non-configurable host limits:\n\n| Limit | Value |\n\n| Maximum canonical manifest size | 4 MiB |\n| Maximum capabilities in one immutable connector version | 512 |\n| Maximum native AIP request body | 4 MiB |\n\nFile requirements\n\nEvery common file input must be a non-empty regular file, not a symbolic link,\nand must remain the same file while it is opened and read. The implementation\nenforces the configured byte limit before and during the read.\n\nOn Unix systems, secret inputs must have no group or world permission bits. A\nmode such as 0600 satisfies that check. This owner-only rule applies to the\ndatabase URL, signing seed, and current DID-file inputs.\n\nSecret text must be\nvalid UTF-8 after surrounding ASCII whitespace is removed, except for the seed,\nwhich is decoded as hexadecimal. Secret buffers are zeroized where the\nbootstrap API retains them temporarily.\n\nThe TLS CA and credential revision policy are non-secret configuration files.\nThey may be group/world readable, but they must not be group/world writable; a\nmode such as 0644 satisfies that check. Replace a reloadable policy atomically\nso a reader never observes a partial JSON document.\n\nCoupling rules\n\nThe following relationships are validated before or during host construction:\n• loopback HTTP requires a loopback listener and loopback public and control\n  URL hosts;\n• gateway DID and gateway DID file are mutually exclusive alternatives;\n• control-plane DID and control-plane DID file are mutually exclusive\n  alternatives;\n• external account ID and external account system are present together;\n• credential ID, issuer, revision, and non-empty scopes are present together;\n• the credential tenant equals the instance tenant;\n• callback network exceptions require a callback endpoint;\n• event network exceptions require an event endpoint;\n• the signing principal and central gateway share the configured trust domain;\n• the heartbeat interval is no more than half the lease TTL;\n• artifact digest and configuration revision match admitted registry state.\n\nA coupling error is a configuration failure. Do not work around it by dropping\nidentity or transport validation; reconcile the deployment inputs with the\nadmitted records.\n\nPreparation, serving, and readiness\n\nThe common bootstrap has two phases. prepare validates configuration and file\nmetadata, loads identities, performs tenant-scoped connector discovery, opens\ndurable PostgreSQL storage, and constructs the signed lifecycle client. It does\nnot register the replica.\n\nThe serving phase builds the host, recovers durable work, registers the exact\nreplica, renews its lease, exposes the common routes, drains on SIGTERM or\nCtrl-C, and marks the replica offline. Product binaries may add authenticated\nprovider ingress routes without changing the common native surface.\n\n| Route | Readiness meaning |\n\n| /health | The process and protocol surface are responsive. |\n| /ready | Lease, drain state, durable storage, and product connector health allow new work. |\n| /metrics | Common host metrics are available. |\n| /aip/v1/manifest | The deployment-bound immutable manifest is available. |\n| /aip/v1/messages | Signed native AIP message ingress is available. |\n\nA successful process health response does not prove route eligibility. Use\n/ready, registry status, and tenant-scoped discovery together before enabling\na capability binding.\n\nError categories\n\nStartup and serving errors identify the boundary that rejected the host:\n\n| Category | Typical cause | Operator response |\n\n| Bootstrap configuration | Missing coupled fields, unsafe file metadata, invalid URL, DID, digest, or limit | Correct the input; do not start traffic. |\n| Durable storage | PostgreSQL connection or schema installation failure | Restore database reachability and least-privilege schema access. |\n| Product discovery | Connector cannot publish its tenant-scoped manifest | Correct only the product-owned configuration, then repeat preparation. |\n| Host admission or control plane | Registry identity, trust, lease, or lifecycle response fails | Compare the process identity with admitted records and service trust. |\n| Listener | Socket cannot bind | Correct the address, port ownership, or deployment ingress mapping. |\n\nThe host fails closed on these errors. A restart with unchanged invalid inputs\ndoes not repair an admission, trust, credential policy, or file-permission\nfailure.\n\nProduct-specific configuration\n\nThis page intentionally ends at the common host boundary. Provider base URLs,\nAPI keys, OAuth material, webhook secrets, account identifiers, feature flags,\nand product-specific health behavior belong to the six connector-local\nconfiguration pages. Do not infer one connector's provider settings from\nanother connector or add an unreviewed connector to the public matrix.\n\nFor the complete deployment sequence, use\nDeploy the connector fleet (../guides/deploy-connector-fleet.md). Review the\nsystem boundary in Deploy AIP in production (../guides/production-deployment.md),\nthe signing model in Identity and trust (../concepts/identity-and-trust.md),\nthe host implementation contract in\nBuild a connector (../guides/build-a-connector.md), and the integration model\nin Profiles and connectors (../concepts/profiles-and-connectors.md).\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "3c0081a02ece8905854ac866d0869ebc106cc338fda6b590488f805f77bc20e8"
  }
}