{
  "schemaVersion": "1.0",
  "title": "Deploy the connector fleet",
  "description": "Use this guide to deploy one connector type, provider boundary, tenant-owned instance, and standalone host replica behind the product-neutral aipd gateway. It is for operators who control registry migration, signed admission, gateway and ho",
  "canonical": "https://getaip.org/docs/guides/deploy-connector-fleet",
  "route": "/docs/guides/deploy-connector-fleet",
  "source": "docs/guides/deploy-connector-fleet.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Deploy and Operate",
  "documentType": "Guide",
  "language": "en",
  "downloads": {
    "md": "/docs/download/guides/deploy-connector-fleet.md",
    "txt": "/docs/download/guides/deploy-connector-fleet.txt",
    "json": "/docs/download/guides/deploy-connector-fleet.json",
    "pdf": "/docs/download/guides/deploy-connector-fleet.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Deploy the connector fleet\ndescription: Admit and deploy standalone connector hosts behind tenant-scoped fleet routing\nkind: how-to\naudience: operator\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\n---\n\n# Deploy the connector fleet\n\nUse this guide to deploy one connector type, provider boundary, tenant-owned\ninstance, and standalone host replica behind the product-neutral `aipd`\ngateway. It is for operators who control registry migration, signed admission,\ngateway and host trust, provider credentials, traffic, and rollback.\n\nThe result is an admitted host with a current lifecycle lease and one bounded\ntenant capability binding. The procedure keeps the binding disabled until the\nhost is ready, verifies tenant-scoped discovery before provider work, and starts\nwith a non-mutating request.\n\nThis guide reflects source revision\n`97be86e9efedf07ecf1783b03800f683f107fb04`. It applies to standalone hosts for\nCal.diy, Hermes Agent, Chatwoot, Dify, CrewAI, and Twenty. Deploy only the\nconnector families and capabilities required by the reviewed deployment.\n\n## Use this procedure after production boundaries exist\n\nComplete [Deploy AIP in production](production-deployment.md) first. You need:\n\n- exact `aipctl`, `aipd`, connector control-plane, and host artifacts;\n- an immutable digest for the selected host artifact;\n- the manifest and implementation support map produced for that artifact;\n- seven independently signed evidence documents and a signed admission\n  package;\n- an admission trust policy with package and evidence-role roots;\n- registry admin, gateway data-plane, and lifecycle database credentials with\n  different authority;\n- core runtime and host runtime databases;\n- gateway, lifecycle, and host signing identities;\n- a tenant and provider account, workspace, application, or endpoint boundary;\n- provider credentials in owner-controlled files;\n- an external TLS path and private trust roots where applicable;\n- approved non-mutating input and a rollback window.\n\nIf the connector has no standalone host artifact, follow\n[Build a connector](build-a-connector.md). If it still runs inside a bundled\ndaemon, use [Migrate bundled connectors to the fleet](migrate-bundled-connectors.md)\nfor the traffic transition.\n\nThis procedure does not create provider credentials, decide capability\nsemantics, or qualify an external product. It deploys evidence and identities\nthat already passed their owning review.\n\n## Freeze one fleet identity set\n\nAssign stable identifiers before writing the registry:\n\n| Identity | Meaning | Change rule |\n|---|---|---|\n| Connector type | One implementation family | Stable across releases |\n| Connector version | One immutable artifact, manifest, and support map | New artifact or contract requires a new version |\n| Instance | One tenant-owned provider account or endpoint boundary | Account ownership cannot change in place |\n| Replica | One concrete host process identity and endpoint | Pre-provision before host registration |\n| Binding | One tenant, capability, and instance policy | Change through a higher policy revision |\n| Package | One signed declarative catalog stream | Advance its monotonic revision for a new operation |\n\nRecord the expected host endpoint, peer principal, DID, trust domain, topology,\ncapacity, artifact digest, tenant membership, secret-provider reference,\ncredential revision, and configuration revision. A runtime value that differs\nfrom its admitted record is a deployment failure, not a dynamic update.\n\nUse one instance for one provider account boundary. Do not put several tenants\nbehind a shared provider credential unless the connector contract and admission\npackage explicitly define that ownership model.\n\n## Prepare separate database roles\n\nProvision the connector registry with three authorities:\n\n| Role | Long-lived use | Authority |\n|---|---|---|\n| Registry administrator | None | Migrate schema, admit catalog packages, read the operator journal, and revoke packages |\n| Gateway data plane | `aipd` | Read catalog and routes; reserve and settle assignments; maintain bounded fleet status |\n| Lifecycle data plane | Connector control-plane service | Read admitted identity; register, heartbeat, drain, and mark replicas offline |\n\nKeep the administrator URL in a short-lived operator environment. Give the\ngateway and lifecycle service separate owner-controlled URL files. Reconcile\nthe complete grant policy after every schema migration so stale permission is\nremoved as well as new permission added.\n\nProvision a separate core runtime database for all `aipd` replicas in this\nlogical deployment. Provision a host-owned durable database for the selected\nconnector boundary. Do not use the registry database as either runtime store.\n\n## Install the registry schema\n\nRun migration from the exact `aipctl` artifact selected for the release:\n\n```sh\naipctl connector registry-migrate \\\n  --database-url-file /run/operator/registry-admin.url\n```\n\nExpected output is a JSON document with `status` set to `ok`, component set to\n`aip-connector-registry-postgres`, and the installed schema version. The command\nuses bounded control and verification pools, installs immutable migrations, and\nfails when the resulting version differs from the binary requirement.\n\nAfter migration:\n\n1. apply the reviewed gateway and lifecycle grants;\n2. close the migration connection;\n3. verify each long-running URL with the corresponding service startup check;\n4. confirm neither URL can perform catalog administration;\n5. retain the schema version, migration artifact, time, and operator identity.\n\nDo not let a long-running process install a missing registry schema through\nadministrator credentials. The gateway and lifecycle constructors require an\nalready installed matching schema.\n\n## Prepare signed admission\n\nThe unsigned admission package binds one immutable deployment declaration:\n\n- connector type and active version;\n- bounded manifest and canonical manifest digest;\n- artifact digest and connector SDK version requirement;\n- implementation support for every callable capability;\n- admission policy;\n- tenant-owned instance;\n- pre-provisioned offline replica;\n- tenant capability bindings with `enabled` set to `false` for the first\n  package revision;\n- OCI signature, SBOM, provenance, conformance, vulnerability-policy,\n  license-policy, and revocation-observation evidence.\n\nEach evidence statement binds the same artifact and manifest digests, its own\ndocument digest, signer, policy outcome, issue time, and expiry. The trust\npolicy supplies separate roots for the package and each evidence role.\n\nThe release authority signs the complete package after the seven signed\nevidence documents have been inserted:\n\n```sh\naipctl connector registry sign-package \\\n  --package admission-unsigned.json \\\n  --signing-seed-file /run/release/package-signing-seed.hex \\\n  --signer-identity connector-release > admission-signed.json\n```\n\nKeep evidence-role signing seeds outside this operator step. One release\nidentity must not impersonate the build, scanner, conformance, license, or\nrevocation authorities.\n\n## Plan and apply the disabled binding\n\nPlan performs cryptographic and structural verification without writing:\n\n```sh\naipctl connector registry plan \\\n  --package admission-signed.json \\\n  --trust-policy admission-trust-policy.json\n```\n\nReview the returned package ID, revision, digest, connector type, version,\nartifact digest, instance count, replica count, binding count, and evidence\ncount. Compare them with the release record, not with a mutable tag or filename.\n\nApply the exact verified bytes through short-lived administrator credentials:\n\n```sh\naipctl connector registry apply \\\n  --package admission-signed.json \\\n  --trust-policy admission-trust-policy.json \\\n  --database-url-file /run/operator/registry-admin.url\n```\n\n`apply` journals the package ID, revision, and digest. Repeating the same\noperation can resume safely. A different digest under the same package revision\nis a conflict.\n\nRead the durable operator result:\n\n```sh\naipctl connector registry status \\\n  --package-id \"$PACKAGE_ID\" \\\n  --revision \"$PACKAGE_REVISION\" \\\n  --database-url-file /run/operator/registry-admin.url\n```\n\nRequire the operation state to report a completed apply before starting the\nhost. Close and unmount administrator credentials when the operator step ends.\n\n## Start the signed lifecycle service\n\nStart one lifecycle service from its reviewed artifact. A loopback listener can\nshare a pod or host with a TLS proxy:\n\n```sh\naip-connector-control-plane \\\n  --database-url-file /run/secrets/registry-lifecycle.url \\\n  --signing-seed-file /run/secrets/control-signing-seed.hex \\\n  --bind 127.0.0.1:8090\n```\n\nIf the service binds to a non-loopback address, place it behind a trusted TLS\nproxy and pass the explicit proxy-network allowance. Do not expose its\nplaintext listener to an untrusted network.\n\nRecord the DID derived from the signing seed. Every host must pin this DID or\nload it from a regular public file. Verify:\n\n- `/health` identifies the lifecycle component;\n- `/ready` reports the installed schema version, catalog revision, and bounded\n  pool state;\n- the retained control pool count is zero;\n- `/metrics` is reachable only through the observability boundary;\n- the database role cannot mutate connector types, versions, instances, or\n  bindings.\n\nThe lifecycle service exposes only signed register, heartbeat, drain, and\noffline commands. It cannot admit an unprovisioned connector identity.\n\n## Start the product-neutral gateway\n\nStart `aipd` with core state, verified identity, and fleet data-plane access.\nThis source-backed example shows the minimum fleet ownership classes; add only\nreviewed profile and limit settings:\n\n```sh\naipd \\\n  --bind \"$AIPD_BIND\" \\\n  --public-base-url \"$AIP_PUBLIC_ORIGIN\" \\\n  --service-id \"$AIPD_PRINCIPAL_ID\" \\\n  --trust-domain \"$AIP_TRUST_DOMAIN\" \\\n  --require-signed-envelopes \\\n  --trusted-signer-file /run/config/trusted-signers.json \\\n  --trusted-identity-file /run/config/trusted-identities.json \\\n  --approval-authority-file /run/config/approval-authorities.json \\\n  --postgres-url-file /run/secrets/aipd-runtime.url \\\n  --connector-registry-url-file /run/secrets/registry-data.url \\\n  --connector-fleet-signing-seed-file /run/secrets/gateway-signing-seed.hex \\\n  --connector-fleet-trust-registry-endpoints \\\n  --connector-fleet-tls-ca-file /run/config/fleet-ca.pem\n```\n\nUse an explicit host allowlist instead of registry-endpoint trust when that is\nthe deployment policy. Plain HTTP and private-network exceptions are intended\nonly for explicitly controlled environments and do not replace endpoint\nidentity verification.\n\nRequire core `/ready` and inspect its fleet snapshot. Core readiness establishes\nstorage, worker, required NATS, and required local-module state. It does not\nestablish that this connector has a ready replica or an enabled tenant binding.\n\n## Configure one standalone host\n\nSelect the exact public host binary for the connector:\n\n| Connector | Host binary |\n|---|---|\n| Cal.diy | `aip-host-cal-diy` |\n| Hermes Agent | `aip-host-hermes-agent` |\n| Chatwoot | `aip-host-chatwoot` |\n| Dify | `aip-host-dify` |\n| CrewAI | `aip-host-crewai` |\n| Twenty | `aip-host-twenty` |\n\nAll six flatten the common host contract and add product-specific values. A\ndeployment wrapper may supply the common contract through environment\nvariables or flags. The common command shape is:\n\n```sh\n\"$HOST_BINARY\" \\\n  --bind \"$HOST_BIND\" \\\n  --public-endpoint \"$HOST_PUBLIC_ENDPOINT\" \\\n  --control-plane-endpoint \"$CONTROL_PLANE_ENDPOINT\" \\\n  --control-plane-did-file /run/config/control-plane.did \\\n  --database-url-file /run/secrets/connector-runtime.url \\\n  --signing-seed-file /run/secrets/host-signing-seed.hex \\\n  --connector-type-id \"$CONNECTOR_TYPE_ID\" \\\n  --version-id \"$CONNECTOR_VERSION_ID\" \\\n  --instance-id \"$CONNECTOR_INSTANCE_ID\" \\\n  --replica-id \"$CONNECTOR_REPLICA_ID\" \\\n  --tenant-id \"$TENANT_ID\" \\\n  --membership-id \"$MEMBERSHIP_ID\" \\\n  --gateway-principal-id \"$AIPD_PRINCIPAL_ID\" \\\n  --gateway-did-file /run/config/gateway.did \\\n  --trust-domain \"$AIP_TRUST_DOMAIN\" \\\n  --artifact-digest \"$HOST_ARTIFACT_DIGEST\" \\\n  --secret-provider-ref \"$SECRET_PROVIDER_REF\" \\\n  \"$@\"\n```\n\n`HOST_PUBLIC_ENDPOINT` must end in `/aip/v1/messages` and resolve to the\nadmitted host endpoint. `CONTROL_PLANE_ENDPOINT` must be the signed lifecycle\nroute. The remaining arguments in `\"$@\"` are the reviewed product-specific\nconfiguration and secret-file references; do not pass arbitrary user input to\nthat position.\n\nBefore start, compare every common identity with the disabled admission\npackage. The host cannot repair a wrong type, version, instance, replica,\ntenant, endpoint, DID, artifact digest, or manifest at registration time.\n\n## Require registration and readiness\n\nThe common host startup sequence is:\n\n1. validate identity, endpoints, limits, files, and trust;\n2. discover the product connector manifest;\n3. open the host PostgreSQL runtime;\n4. recover durable runtime work;\n5. register the pre-provisioned replica through the signed lifecycle service;\n6. apply its lease and start heartbeat renewal;\n7. serve process health, readiness, metrics, manifest, native AIP, and optional\n   product-owned ingress routes.\n\nDo not enable the binding when only `/health` succeeds. Require all of:\n\n- host `/ready` returns success;\n- connector and storage probes are ready;\n- the replica is not draining;\n- its lease is current;\n- the registry identity matches the intended artifact and endpoint;\n- the running manifest digest matches admission;\n- active assignments are zero before first traffic;\n- gateway fleet maintenance reports no error.\n\nIf registration fails, keep the binding disabled. Do not create a replacement\nreplica identity from the host process or weaken artifact, DID, tenant, or\nendpoint verification.\n\n## Enable one tenant binding\n\nPrepare a second signed package revision from the same package stream. Preserve\nthe immutable connector version, instance, replica, evidence, and artifact.\nChange only the intended binding to `enabled: true`, increase its policy\nrevision, and advance the package revision.\n\nPlan the second package while the host remains ready, then apply the exact\nplanned bytes with the same short-lived operator sequence. Read its durable\nstatus and close the administrator credential again.\n\nConfigure `aipctl` with the approved principal, signing seed, trust domain, and\nexpected gateway DID described in [Use native AIP](use-native-aip.md). Query the\ntenant-scoped catalog through that authenticated client:\n\n```sh\naipctl capability list \"$AIP_PUBLIC_ORIGIN\" \\\n  --capability-id \"$CAPABILITY_ID\" \\\n  --signed-native\n```\n\nThe result must contain the expected capability definition for the authenticated\ntenant. Repeat with an unauthorized tenant and require that the binding is not\nvisible. A catalog result proves tenant visibility; it does not prove provider\nexecution.\n\n## Route the first safe action\n\nChoose a capability whose reviewed contract is non-mutating and whose input\ncannot create a provider effect. Use the normal authenticated client boundary,\nnot a direct host request:\n\n```sh\naipctl action call \"$AIP_PUBLIC_ORIGIN\" \"$CAPABILITY_ID\" \\\n  --input @safe-read.json\n```\n\nRequire a terminal result consistent with the capability contract. Retain:\n\n- action and correlation IDs;\n- authenticated principal and tenant;\n- capability and manifest digest;\n- route assignment instance, replica, endpoint, peer DID, version, catalog\n  revision, binding revision, credential revision, health revision, and fence;\n- host request and provider trace identifiers;\n- result, events, receipts, and redacted audit records;\n- gateway, host, and provider timestamps.\n\nConfirm the request reached the intended provider account and that no bundled\nor second host path processed it. Only then admit a controlled mutation with a\nfresh idempotency key and the required approval or transaction context.\n\n## Scale without changing the contract\n\nAdd capacity in separate changes:\n\n1. pre-provision a new replica identity and endpoint in a signed package;\n2. plan and apply the package revision;\n3. start the exact admitted artifact;\n4. require registration, current lease, readiness, and zero assignments;\n5. observe routing at the intended region, zone, and capacity class;\n6. expand capacity or tenant binding policy only after evidence is retained.\n\nDo not reuse a replica ID across two live processes. Do not change artifact,\nmanifest, endpoint, peer identity, tenant, or topology under an existing replica\nidentity.\n\nExisting actions retain their pinned route for retry, cancellation, and\nreconciliation. New ready capacity does not authorize moving an uncertain\nprovider operation to another replica.\n\n## Resolve deployment failures\n\n| Symptom | Decision |\n|---|---|\n| Registry migration reports a checksum or version mismatch | Stop; use the reviewed migration source and inspect the retained schema record |\n| Admission plan fails | Correct signatures, evidence, time bounds, digests, SDK range, manifest, or registry relationships; do not apply |\n| Apply is interrupted | Read package status and resume the same revision and digest |\n| Lifecycle readiness fails | Inspect schema version, lifecycle grants, pool bounds, and database connectivity |\n| Gateway rejects fleet configuration | Supply the complete registry, signing, endpoint-trust, and positive-bound set |\n| Host admission fails | Compare type, version, instance, replica, tenant, membership, endpoint, DID, digest, and manifest |\n| Host health passes but readiness fails | Inspect runtime storage, connector probe, lease, heartbeat, and drain state |\n| Catalog omits the capability | Inspect authenticated tenant, enabled binding, active version, implementation support, and catalog revision |\n| No ready replica is available | Keep mutations off; inspect lease, status, capacity, topology, and circuit state |\n| First action has an unknown outcome | Reconcile it through the pinned route; do not retry through another host |\n\nPreserve admission journals, route assignments, provider operation IDs,\nidempotency records, lifecycle transitions, and audit evidence while diagnosing.\n\n## Drain and roll back\n\nPrepare a signed rollback package revision with the affected binding disabled\nand a higher binding policy revision. For a normal rollback:\n\n1. pause new mutations;\n2. plan and apply the disabled-binding package;\n3. verify tenant discovery no longer exposes that route;\n4. begin host drain through its normal shutdown path;\n5. wait for active assignments, callbacks, events, and provider jobs to settle;\n6. reconcile every unknown outcome through its pinned replica;\n7. require the lifecycle transition to `offline`;\n8. stop the host and retain its durable database;\n9. restore the previous binding or bundled path only after overlap is excluded.\n\nIf the artifact or its evidence is compromised, revoke the applied package:\n\n```sh\naipctl connector registry revoke \\\n  --package-id \"$PACKAGE_ID\" \\\n  --revision \"$PACKAGE_REVISION\" \\\n  --reason \"$REVOCATION_REASON\" \\\n  --database-url-file /run/operator/registry-admin.url\n```\n\nRevocation marks the exact connector version revoked and stops new traffic for\nit. It does not terminate provider work, undo external effects, delete audit\nstate, or revoke a provider credential. Perform those actions through their\nown reviewed boundaries.\n\n## Accept the fleet boundary\n\nAccept this deployment only when the record contains:\n\n- exact component and host artifact digests;\n- registry schema and grant revisions;\n- package ID, revision, digest, signer, seven evidence statements, and status;\n- type, version, instance, replica, binding, tenant, account, endpoint, DID,\n  topology, capacity, and credential revisions;\n- lifecycle registration, readiness, heartbeat, drain, and offline evidence;\n- authorized and unauthorized discovery results;\n- first read and controlled mutation traces where applicable;\n- recovery, restart, scale, and rollback results;\n- known exclusions, evidence expirations, and claim owner.\n\nAdmission proves that an exact catalog package satisfied the selected trust\npolicy. Registration proves that an exact host acquired a lease. Discovery\nproves tenant visibility. An action proves only its observed path. Report\nqualification and production readiness only when their broader evidence\ncampaigns also pass.\n\n## Related documentation\n\n- [Capabilities and contracts](../concepts/capabilities.md)\n- [Actions and sessions](../concepts/actions-and-sessions.md)\n- [Connector catalog](../connectors/README.md)\n",
    "text": "Deploy the connector fleet\n\nUse this guide to deploy one connector type, provider boundary, tenant-owned\ninstance, and standalone host replica behind the product-neutral aipd\ngateway. It is for operators who control registry migration, signed admission,\ngateway and host trust, provider credentials, traffic, and rollback.\n\nThe result is an admitted host with a current lifecycle lease and one bounded\ntenant capability binding. The procedure keeps the binding disabled until the\nhost is ready, verifies tenant-scoped discovery before provider work, and starts\nwith a non-mutating request.\n\nThis guide reflects source revision\n97be86e9efedf07ecf1783b03800f683f107fb04. It applies to standalone hosts for\nCal.diy, Hermes Agent, Chatwoot, Dify, CrewAI, and Twenty. Deploy only the\nconnector families and capabilities required by the reviewed deployment.\n\nUse this procedure after production boundaries exist\n\nComplete Deploy AIP in production (production-deployment.md) first. You need:\n• exact aipctl, aipd, connector control-plane, and host artifacts;\n• an immutable digest for the selected host artifact;\n• the manifest and implementation support map produced for that artifact;\n• seven independently signed evidence documents and a signed admission\n  package;\n• an admission trust policy with package and evidence-role roots;\n• registry admin, gateway data-plane, and lifecycle database credentials with\n  different authority;\n• core runtime and host runtime databases;\n• gateway, lifecycle, and host signing identities;\n• a tenant and provider account, workspace, application, or endpoint boundary;\n• provider credentials in owner-controlled files;\n• an external TLS path and private trust roots where applicable;\n• approved non-mutating input and a rollback window.\n\nIf the connector has no standalone host artifact, follow\nBuild a connector (build-a-connector.md). If it still runs inside a bundled\ndaemon, use Migrate bundled connectors to the fleet (migrate-bundled-connectors.md)\nfor the traffic transition.\n\nThis procedure does not create provider credentials, decide capability\nsemantics, or qualify an external product. It deploys evidence and identities\nthat already passed their owning review.\n\nFreeze one fleet identity set\n\nAssign stable identifiers before writing the registry:\n\n| Identity | Meaning | Change rule |\n\n| Connector type | One implementation family | Stable across releases |\n| Connector version | One immutable artifact, manifest, and support map | New artifact or contract requires a new version |\n| Instance | One tenant-owned provider account or endpoint boundary | Account ownership cannot change in place |\n| Replica | One concrete host process identity and endpoint | Pre-provision before host registration |\n| Binding | One tenant, capability, and instance policy | Change through a higher policy revision |\n| Package | One signed declarative catalog stream | Advance its monotonic revision for a new operation |\n\nRecord the expected host endpoint, peer principal, DID, trust domain, topology,\ncapacity, artifact digest, tenant membership, secret-provider reference,\ncredential revision, and configuration revision. A runtime value that differs\nfrom its admitted record is a deployment failure, not a dynamic update.\n\nUse one instance for one provider account boundary. Do not put several tenants\nbehind a shared provider credential unless the connector contract and admission\npackage explicitly define that ownership model.\n\nPrepare separate database roles\n\nProvision the connector registry with three authorities:\n\n| Role | Long-lived use | Authority |\n\n| Registry administrator | None | Migrate schema, admit catalog packages, read the operator journal, and revoke packages |\n| Gateway data plane | aipd | Read catalog and routes; reserve and settle assignments; maintain bounded fleet status |\n| Lifecycle data plane | Connector control-plane service | Read admitted identity; register, heartbeat, drain, and mark replicas offline |\n\nKeep the administrator URL in a short-lived operator environment. Give the\ngateway and lifecycle service separate owner-controlled URL files. Reconcile\nthe complete grant policy after every schema migration so stale permission is\nremoved as well as new permission added.\n\nProvision a separate core runtime database for all aipd replicas in this\nlogical deployment. Provision a host-owned durable database for the selected\nconnector boundary. Do not use the registry database as either runtime store.\n\nInstall the registry schema\n\nRun migration from the exact aipctl artifact selected for the release:\n\naipctl connector registry-migrate \\\n  --database-url-file /run/operator/registry-admin.url\n\nExpected output is a JSON document with status set to ok, component set to\naip-connector-registry-postgres, and the installed schema version. The command\nuses bounded control and verification pools, installs immutable migrations, and\nfails when the resulting version differs from the binary requirement.\n\nAfter migration:\n1. apply the reviewed gateway and lifecycle grants;\n2. close the migration connection;\n3. verify each long-running URL with the corresponding service startup check;\n4. confirm neither URL can perform catalog administration;\n5. retain the schema version, migration artifact, time, and operator identity.\n\nDo not let a long-running process install a missing registry schema through\nadministrator credentials. The gateway and lifecycle constructors require an\nalready installed matching schema.\n\nPrepare signed admission\n\nThe unsigned admission package binds one immutable deployment declaration:\n• connector type and active version;\n• bounded manifest and canonical manifest digest;\n• artifact digest and connector SDK version requirement;\n• implementation support for every callable capability;\n• admission policy;\n• tenant-owned instance;\n• pre-provisioned offline replica;\n• tenant capability bindings with enabled set to false for the first\n  package revision;\n• OCI signature, SBOM, provenance, conformance, vulnerability-policy,\n  license-policy, and revocation-observation evidence.\n\nEach evidence statement binds the same artifact and manifest digests, its own\ndocument digest, signer, policy outcome, issue time, and expiry. The trust\npolicy supplies separate roots for the package and each evidence role.\n\nThe release authority signs the complete package after the seven signed\nevidence documents have been inserted:\n\naipctl connector registry sign-package \\\n  --package admission-unsigned.json \\\n  --signing-seed-file /run/release/package-signing-seed.hex \\\n  --signer-identity connector-release > admission-signed.json\n\nKeep evidence-role signing seeds outside this operator step. One release\nidentity must not impersonate the build, scanner, conformance, license, or\nrevocation authorities.\n\nPlan and apply the disabled binding\n\nPlan performs cryptographic and structural verification without writing:\n\naipctl connector registry plan \\\n  --package admission-signed.json \\\n  --trust-policy admission-trust-policy.json\n\nReview the returned package ID, revision, digest, connector type, version,\nartifact digest, instance count, replica count, binding count, and evidence\ncount. Compare them with the release record, not with a mutable tag or filename.\n\nApply the exact verified bytes through short-lived administrator credentials:\n\naipctl connector registry apply \\\n  --package admission-signed.json \\\n  --trust-policy admission-trust-policy.json \\\n  --database-url-file /run/operator/registry-admin.url\n\napply journals the package ID, revision, and digest. Repeating the same\noperation can resume safely. A different digest under the same package revision\nis a conflict.\n\nRead the durable operator result:\n\naipctl connector registry status \\\n  --package-id \"$PACKAGEID\" \\\n  --revision \"$PACKAGEREVISION\" \\\n  --database-url-file /run/operator/registry-admin.url\n\nRequire the operation state to report a completed apply before starting the\nhost. Close and unmount administrator credentials when the operator step ends.\n\nStart the signed lifecycle service\n\nStart one lifecycle service from its reviewed artifact. A loopback listener can\nshare a pod or host with a TLS proxy:\n\naip-connector-control-plane \\\n  --database-url-file /run/secrets/registry-lifecycle.url \\\n  --signing-seed-file /run/secrets/control-signing-seed.hex \\\n  --bind 127.0.0.1:8090\n\nIf the service binds to a non-loopback address, place it behind a trusted TLS\nproxy and pass the explicit proxy-network allowance. Do not expose its\nplaintext listener to an untrusted network.\n\nRecord the DID derived from the signing seed. Every host must pin this DID or\nload it from a regular public file. Verify:\n• /health identifies the lifecycle component;\n• /ready reports the installed schema version, catalog revision, and bounded\n  pool state;\n• the retained control pool count is zero;\n• /metrics is reachable only through the observability boundary;\n• the database role cannot mutate connector types, versions, instances, or\n  bindings.\n\nThe lifecycle service exposes only signed register, heartbeat, drain, and\noffline commands. It cannot admit an unprovisioned connector identity.\n\nStart the product-neutral gateway\n\nStart aipd with core state, verified identity, and fleet data-plane access.\nThis source-backed example shows the minimum fleet ownership classes; add only\nreviewed profile and limit settings:\n\naipd \\\n  --bind \"$AIPDBIND\" \\\n  --public-base-url \"$AIPPUBLICORIGIN\" \\\n  --service-id \"$AIPDPRINCIPALID\" \\\n  --trust-domain \"$AIPTRUSTDOMAIN\" \\\n  --require-signed-envelopes \\\n  --trusted-signer-file /run/config/trusted-signers.json \\\n  --trusted-identity-file /run/config/trusted-identities.json \\\n  --approval-authority-file /run/config/approval-authorities.json \\\n  --postgres-url-file /run/secrets/aipd-runtime.url \\\n  --connector-registry-url-file /run/secrets/registry-data.url \\\n  --connector-fleet-signing-seed-file /run/secrets/gateway-signing-seed.hex \\\n  --connector-fleet-trust-registry-endpoints \\\n  --connector-fleet-tls-ca-file /run/config/fleet-ca.pem\n\nUse an explicit host allowlist instead of registry-endpoint trust when that is\nthe deployment policy. Plain HTTP and private-network exceptions are intended\nonly for explicitly controlled environments and do not replace endpoint\nidentity verification.\n\nRequire core /ready and inspect its fleet snapshot. Core readiness establishes\nstorage, worker, required NATS, and required local-module state. It does not\nestablish that this connector has a ready replica or an enabled tenant binding.\n\nConfigure one standalone host\n\nSelect the exact public host binary for the connector:\n\n| Connector | Host binary |\n\n| Cal.diy | aip-host-cal-diy |\n| Hermes Agent | aip-host-hermes-agent |\n| Chatwoot | aip-host-chatwoot |\n| Dify | aip-host-dify |\n| CrewAI | aip-host-crewai |\n| Twenty | aip-host-twenty |\n\nAll six flatten the common host contract and add product-specific values. A\ndeployment wrapper may supply the common contract through environment\nvariables or flags. The common command shape is:\n\n\"$HOSTBINARY\" \\\n  --bind \"$HOSTBIND\" \\\n  --public-endpoint \"$HOSTPUBLICENDPOINT\" \\\n  --control-plane-endpoint \"$CONTROLPLANEENDPOINT\" \\\n  --control-plane-did-file /run/config/control-plane.did \\\n  --database-url-file /run/secrets/connector-runtime.url \\\n  --signing-seed-file /run/secrets/host-signing-seed.hex \\\n  --connector-type-id \"$CONNECTORTYPEID\" \\\n  --version-id \"$CONNECTORVERSIONID\" \\\n  --instance-id \"$CONNECTORINSTANCEID\" \\\n  --replica-id \"$CONNECTORREPLICAID\" \\\n  --tenant-id \"$TENANTID\" \\\n  --membership-id \"$MEMBERSHIPID\" \\\n  --gateway-principal-id \"$AIPDPRINCIPALID\" \\\n  --gateway-did-file /run/config/gateway.did \\\n  --trust-domain \"$AIPTRUSTDOMAIN\" \\\n  --artifact-digest \"$HOSTARTIFACTDIGEST\" \\\n  --secret-provider-ref \"$SECRETPROVIDERREF\" \\\n  \"$@\"\n\nHOSTPUBLICENDPOINT must end in /aip/v1/messages and resolve to the\nadmitted host endpoint. CONTROLPLANEENDPOINT must be the signed lifecycle\nroute. The remaining arguments in \"$@\" are the reviewed product-specific\nconfiguration and secret-file references; do not pass arbitrary user input to\nthat position.\n\nBefore start, compare every common identity with the disabled admission\npackage. The host cannot repair a wrong type, version, instance, replica,\ntenant, endpoint, DID, artifact digest, or manifest at registration time.\n\nRequire registration and readiness\n\nThe common host startup sequence is:\n1. validate identity, endpoints, limits, files, and trust;\n2. discover the product connector manifest;\n3. open the host PostgreSQL runtime;\n4. recover durable runtime work;\n5. register the pre-provisioned replica through the signed lifecycle service;\n6. apply its lease and start heartbeat renewal;\n7. serve process health, readiness, metrics, manifest, native AIP, and optional\n   product-owned ingress routes.\n\nDo not enable the binding when only /health succeeds. Require all of:\n• host /ready returns success;\n• connector and storage probes are ready;\n• the replica is not draining;\n• its lease is current;\n• the registry identity matches the intended artifact and endpoint;\n• the running manifest digest matches admission;\n• active assignments are zero before first traffic;\n• gateway fleet maintenance reports no error.\n\nIf registration fails, keep the binding disabled. Do not create a replacement\nreplica identity from the host process or weaken artifact, DID, tenant, or\nendpoint verification.\n\nEnable one tenant binding\n\nPrepare a second signed package revision from the same package stream. Preserve\nthe immutable connector version, instance, replica, evidence, and artifact.\nChange only the intended binding to enabled: true, increase its policy\nrevision, and advance the package revision.\n\nPlan the second package while the host remains ready, then apply the exact\nplanned bytes with the same short-lived operator sequence. Read its durable\nstatus and close the administrator credential again.\n\nConfigure aipctl with the approved principal, signing seed, trust domain, and\nexpected gateway DID described in Use native AIP (use-native-aip.md). Query the\ntenant-scoped catalog through that authenticated client:\n\naipctl capability list \"$AIPPUBLICORIGIN\" \\\n  --capability-id \"$CAPABILITYID\" \\\n  --signed-native\n\nThe result must contain the expected capability definition for the authenticated\ntenant. Repeat with an unauthorized tenant and require that the binding is not\nvisible. A catalog result proves tenant visibility; it does not prove provider\nexecution.\n\nRoute the first safe action\n\nChoose a capability whose reviewed contract is non-mutating and whose input\ncannot create a provider effect. Use the normal authenticated client boundary,\nnot a direct host request:\n\naipctl action call \"$AIPPUBLICORIGIN\" \"$CAPABILITYID\" \\\n  --input @safe-read.json\n\nRequire a terminal result consistent with the capability contract. Retain:\n• action and correlation IDs;\n• authenticated principal and tenant;\n• capability and manifest digest;\n• route assignment instance, replica, endpoint, peer DID, version, catalog\n  revision, binding revision, credential revision, health revision, and fence;\n• host request and provider trace identifiers;\n• result, events, receipts, and redacted audit records;\n• gateway, host, and provider timestamps.\n\nConfirm the request reached the intended provider account and that no bundled\nor second host path processed it. Only then admit a controlled mutation with a\nfresh idempotency key and the required approval or transaction context.\n\nScale without changing the contract\n\nAdd capacity in separate changes:\n1. pre-provision a new replica identity and endpoint in a signed package;\n2. plan and apply the package revision;\n3. start the exact admitted artifact;\n4. require registration, current lease, readiness, and zero assignments;\n5. observe routing at the intended region, zone, and capacity class;\n6. expand capacity or tenant binding policy only after evidence is retained.\n\nDo not reuse a replica ID across two live processes. Do not change artifact,\nmanifest, endpoint, peer identity, tenant, or topology under an existing replica\nidentity.\n\nExisting actions retain their pinned route for retry, cancellation, and\nreconciliation. New ready capacity does not authorize moving an uncertain\nprovider operation to another replica.\n\nResolve deployment failures\n\n| Symptom | Decision |\n\n| Registry migration reports a checksum or version mismatch | Stop; use the reviewed migration source and inspect the retained schema record |\n| Admission plan fails | Correct signatures, evidence, time bounds, digests, SDK range, manifest, or registry relationships; do not apply |\n| Apply is interrupted | Read package status and resume the same revision and digest |\n| Lifecycle readiness fails | Inspect schema version, lifecycle grants, pool bounds, and database connectivity |\n| Gateway rejects fleet configuration | Supply the complete registry, signing, endpoint-trust, and positive-bound set |\n| Host admission fails | Compare type, version, instance, replica, tenant, membership, endpoint, DID, digest, and manifest |\n| Host health passes but readiness fails | Inspect runtime storage, connector probe, lease, heartbeat, and drain state |\n| Catalog omits the capability | Inspect authenticated tenant, enabled binding, active version, implementation support, and catalog revision |\n| No ready replica is available | Keep mutations off; inspect lease, status, capacity, topology, and circuit state |\n| First action has an unknown outcome | Reconcile it through the pinned route; do not retry through another host |\n\nPreserve admission journals, route assignments, provider operation IDs,\nidempotency records, lifecycle transitions, and audit evidence while diagnosing.\n\nDrain and roll back\n\nPrepare a signed rollback package revision with the affected binding disabled\nand a higher binding policy revision. For a normal rollback:\n1. pause new mutations;\n2. plan and apply the disabled-binding package;\n3. verify tenant discovery no longer exposes that route;\n4. begin host drain through its normal shutdown path;\n5. wait for active assignments, callbacks, events, and provider jobs to settle;\n6. reconcile every unknown outcome through its pinned replica;\n7. require the lifecycle transition to offline;\n8. stop the host and retain its durable database;\n9. restore the previous binding or bundled path only after overlap is excluded.\n\nIf the artifact or its evidence is compromised, revoke the applied package:\n\naipctl connector registry revoke \\\n  --package-id \"$PACKAGEID\" \\\n  --revision \"$PACKAGEREVISION\" \\\n  --reason \"$REVOCATIONREASON\" \\\n  --database-url-file /run/operator/registry-admin.url\n\nRevocation marks the exact connector version revoked and stops new traffic for\nit. It does not terminate provider work, undo external effects, delete audit\nstate, or revoke a provider credential. Perform those actions through their\nown reviewed boundaries.\n\nAccept the fleet boundary\n\nAccept this deployment only when the record contains:\n• exact component and host artifact digests;\n• registry schema and grant revisions;\n• package ID, revision, digest, signer, seven evidence statements, and status;\n• type, version, instance, replica, binding, tenant, account, endpoint, DID,\n  topology, capacity, and credential revisions;\n• lifecycle registration, readiness, heartbeat, drain, and offline evidence;\n• authorized and unauthorized discovery results;\n• first read and controlled mutation traces where applicable;\n• recovery, restart, scale, and rollback results;\n• known exclusions, evidence expirations, and claim owner.\n\nAdmission proves that an exact catalog package satisfied the selected trust\npolicy. Registration proves that an exact host acquired a lease. Discovery\nproves tenant visibility. An action proves only its observed path. Report\nqualification and production readiness only when their broader evidence\ncampaigns also pass.\n\nRelated documentation\n• Capabilities and contracts (../concepts/capabilities.md)\n• Actions and sessions (../concepts/actions-and-sessions.md)\n• Connector catalog (../connectors/README.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "d2f47d97c6dc7f5a1df7d42b65726132d010cd755a1c788ee4324fdb7ad933ed"
  }
}