Connector host configuration

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 limits without searching each product implementation.

The contract is implemented by ConnectorHostBootstrapArgs at source revision 97be86e9efedf07ecf1783b03800f683f107fb04. The Cal.diy, Hermes Agent, Chatwoot, Dify, CrewAI, and Twenty host binaries all flatten this structure into their command-line interface. Each binary adds its own provider settings after these common options.

All listed behaviors are implementation contracts for the reviewed revision. They are not new AIP protocol requirements, and the defaults are not capacity recommendations for an arbitrary production deployment.

Value sources

Every common option can be supplied as a command-line flag or through its listed environment variable. Do not configure conflicting values in both places. Values shown as Required have no implementation default; the host cannot prepare without them or a required alternative.

The host does not accept database credentials or signing material as literal command-line values. It reads those secrets from bounded, owner-controlled files. Provider credentials use opaque handles and product-owned secret files; they are never embedded in this common configuration.

Listener and central endpoints

Each URL requires a host and rejects embedded credentials, a query, and a fragment. The public and control endpoints require HTTPS. Plain HTTP is accepted only when --allow-insecure-loopback-http is enabled and both the listener and the corresponding URL are loopback-scoped.

Callback and event delivery have separate network exceptions. Their destination host is pinned into the outbound allowlist during preparation. The common host uses its native signing identity for both delivery paths; a different callback or event signer is rejected.

Admitted connector identity

These values identify the exact registry objects that the process claims when it registers. They must match the admitted records; they do not create those records.

--artifact-digest accepts the canonical SHA-256 form: the sha256: prefix followed by 64 hexadecimal characters. A changed artifact, admitted version, instance identity, or configuration revision must be reconciled through the registry workflow rather than silently changed at process restart.

Tenant and external account boundary

The external account ID and system are one optional pair: configure both or neither. The host performs connector discovery with the configured tenant before it opens the listener. The resulting manifest is then bound to the deployment trust domain and host signing identity.

Gateway and lifecycle trust

Configure exactly one gateway DID source and exactly one control-plane DID source. Every DID value must parse as a did:key and contain no more than 512 bytes. The host derives its own did:key from the configured signing seed; it does not accept the host DID as an independent setting.

The optional CA augments the public root set. Certificate and hostname verification remain enabled. The host supplies the root to lifecycle, callback, and event delivery clients; it is not a switch for disabling TLS authentication.

Durable storage

Preparation reads the database URL, connects to PostgreSQL, and installs the durable runtime schema before the process can serve. The common host constructs the action, event, idempotency, profile, session, approval, transaction, and execution stores from that backend. It does not fall back to ephemeral runtime state.

Product hosts may bind their own durable projections to the same backend. The schema and database privileges required by a product remain part of its connector-local configuration and deployment documentation.

Topology labels

The registry validates each label as at most 128 ASCII letters, digits, dots, dashes, or underscores. Labels are indexed routing coordinates, not high-cardinality metric dimensions. They influence creation of new route assignments; an existing durable assignment remains pinned to its exact replica.

Opaque credential handle

The common host can bind a provider credential without receiving its secret value. The connector resolves the opaque handle inside its product boundary.

Credential ID, issuer, revision, and at least one non-empty scope form one tuple. Configure the complete tuple or omit all four. The common host fixes the credential tenant to --tenant-id; a mismatched tenant is rejected.

Without a policy file, the process creates a static policy that authorizes only the configured current revision. With a policy file, the host validates it at startup and reloads it immediately before each provider side effect. An unreadable, invalid, or non-authorizing file denies the action.

The file has this closed schema:

{
  "current_revision_ref": "credential-revision-current",
  "accepted_previous_revisions": ["credential-revision-previous"],
  "revoked_revisions": []
}

Unknown fields are rejected. Each revision reference contains 1–256 bytes, and the current, previous, and revoked sets cannot overlap. The complete replacement and emergency-revocation sequence belongs to Rotate connector credentials.

Callback and event network policy

A callback exception is invalid without --callback-endpoint; an event exception is invalid without --event-endpoint. These switches weaken only the selected fixed outbound destination policy. They do not relax native ingress, lifecycle endpoint, DID, signature, or path validation.

Provider event publication also depends on host readiness. The built-in publisher accepts work only while the replica lease is valid, the host is not draining, durable storage is ready, and the product connector reports ready.

Lifecycle and resource limits

max-in-flight is the replica-local action bound. Fleet admission policies can impose additional global, tenant, connector-type, instance, and binding limits. Increasing the local value cannot bypass those controls.

The reviewed implementation also fixes three non-configurable host limits:

File requirements

Every common file input must be a non-empty regular file, not a symbolic link, and must remain the same file while it is opened and read. The implementation enforces the configured byte limit before and during the read.

On Unix systems, secret inputs must have no group or world permission bits. A mode such as 0600 satisfies that check. This owner-only rule applies to the database URL, signing seed, and current DID-file inputs.

Secret text must be valid UTF-8 after surrounding ASCII whitespace is removed, except for the seed, which is decoded as hexadecimal. Secret buffers are zeroized where the bootstrap API retains them temporarily.

The TLS CA and credential revision policy are non-secret configuration files. They may be group/world readable, but they must not be group/world writable; a mode such as 0644 satisfies that check. Replace a reloadable policy atomically so a reader never observes a partial JSON document.

Coupling rules

The following relationships are validated before or during host construction:

• loopback HTTP requires a loopback listener and loopback public and control URL hosts;
• gateway DID and gateway DID file are mutually exclusive alternatives;
• control-plane DID and control-plane DID file are mutually exclusive alternatives;
• external account ID and external account system are present together;
• credential ID, issuer, revision, and non-empty scopes are present together;
• the credential tenant equals the instance tenant;
• callback network exceptions require a callback endpoint;
• event network exceptions require an event endpoint;
• the signing principal and central gateway share the configured trust domain;
• the heartbeat interval is no more than half the lease TTL;
• artifact digest and configuration revision match admitted registry state.

A coupling error is a configuration failure. Do not work around it by dropping identity or transport validation; reconcile the deployment inputs with the admitted records.

Preparation, serving, and readiness

The common bootstrap has two phases. prepare validates configuration and file metadata, loads identities, performs tenant-scoped connector discovery, opens durable PostgreSQL storage, and constructs the signed lifecycle client. It does not register the replica.

The serving phase builds the host, recovers durable work, registers the exact replica, renews its lease, exposes the common routes, drains on SIGTERM or Ctrl-C, and marks the replica offline. Product binaries may add authenticated provider ingress routes without changing the common native surface.

A successful process health response does not prove route eligibility. Use /ready, registry status, and tenant-scoped discovery together before enabling a capability binding.

Error categories

Startup and serving errors identify the boundary that rejected the host:

The host fails closed on these errors. A restart with unchanged invalid inputs does not repair an admission, trust, credential policy, or file-permission failure.

Product-specific configuration

This page intentionally ends at the common host boundary. Provider base URLs, API keys, OAuth material, webhook secrets, account identifiers, feature flags, and product-specific health behavior belong to the six connector-local configuration pages. Do not infer one connector’s provider settings from another connector or add an unreviewed connector to the public matrix.

For the complete deployment sequence, use Deploy the connector fleet. Review the system boundary in Deploy AIP in production, the signing model in Identity and trust, the host implementation contract in Build a connector, and the integration model in Profiles and connectors.