{
  "schemaVersion": "1.0",
  "title": "Migrate bundled connectors to the fleet",
  "description": "Use this guide to move one product connector from an aipd process into an admitted standalone connector host. It is for operators and connector owners who can control the gateway, registry, host, provider credentials, ingress, and rollback ",
  "canonical": "https://getaip.org/docs/guides/migrate-bundled-connectors",
  "route": "/docs/guides/migrate-bundled-connectors",
  "source": "docs/guides/migrate-bundled-connectors.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Connectors",
  "documentType": "Guide",
  "language": "en",
  "downloads": {
    "md": "/docs/download/guides/migrate-bundled-connectors.md",
    "txt": "/docs/download/guides/migrate-bundled-connectors.txt",
    "json": "/docs/download/guides/migrate-bundled-connectors.json",
    "pdf": "/docs/download/guides/migrate-bundled-connectors.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Migrate bundled connectors to the fleet\ndescription: Move a bundled connector into an admitted standalone host without duplicate mutations\nkind: how-to\naudience: operator\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\n---\n\n# Migrate bundled connectors to the fleet\n\nUse this guide to move one product connector from an `aipd` process into an\nadmitted standalone connector host. It is for operators and connector owners\nwho can control the gateway, registry, host, provider credentials, ingress, and\nrollback window.\n\nThe procedure preserves the AIP 1.0 capability contract while changing where\nthe provider operation executes. It keeps one authoritative mutation path at a\ntime, verifies the new path with non-mutating work, and switches one tenant\nbinding only after the old path has drained.\n\nThe pinned source contains a compatibility binary named\n`aipd-legacy-bundled`, a product-neutral `aipd`, and standalone hosts for the\nsix public connectors: Cal.diy, Hermes Agent, Chatwoot, Dify, CrewAI, and\nTwenty. It does not contain a generic command that imports bundled connector\nstate into a host database.\n\nThis guide reflects source revision\n`97be86e9efedf07ecf1783b03800f683f107fb04`.\n\n## Use this procedure for one execution boundary\n\nApply this migration when a connector implementation or trusted local module\nruns in the same process as the gateway and the target connector already has:\n\n- a frozen connector implementation;\n- a standalone host binary;\n- an immutable host artifact and exact digest;\n- a reviewed manifest and implementation support map;\n- the evidence required for fleet admission;\n- a tenant-owned provider account or endpoint boundary.\n\nIf the connector still uses legacy SDK traits, complete\n[Upgrade a connector to the frozen SDK](upgrade-connector-sdk.md) first. If no\nstandalone host or admission package exists, follow\n[Build a connector](build-a-connector.md).\n\nDo not combine this migration with capability renaming, schema changes,\nprovider account consolidation, credential-scope expansion, or a wire-version\nchange. Each would make it harder to distinguish a deployment failure from a\ncontract change.\n\nMigrate one connector type, tenant, and provider boundary at a time. A\ndeployment may contain fewer than the six public connectors; do not create an\nunused instance merely to make the fleet catalog look complete.\n\n## Prepare authority and a rollback window\n\nAssign an owner for each control before changing traffic:\n\n| Control | Required authority |\n|---|---|\n| Bundled process | Remove or restore the connector configuration and restart safely |\n| Product-neutral gateway | Configure registry access, signing, trust, and limits |\n| Connector registry | Plan and apply a signed admission package and change bindings |\n| Standalone host | Deploy the admitted digest, inspect readiness, drain, and stop it |\n| Provider account | Rotate credentials and change webhook or callback destinations |\n| Durable stores | Retain, inspect, and restore gateway, host, and ingress state |\n| Client traffic | Pause or bound mutations and run an approved read-only check |\n| Evidence | Record identities, revisions, timestamps, outcomes, and rollback decisions |\n\nChoose a window long enough for the connector's maximum action duration,\nprovider job duration, retry window, callback delay, and webhook replay window.\nStop before migration if active work cannot be enumerated or if the provider\ncannot distinguish completed, failed, and unknown mutations.\n\nRetain these rollback inputs outside the deployment:\n\n- the current gateway artifact and complete non-secret configuration;\n- canonical bundled manifest and capability schemas;\n- provider credential references and their revisions, without secret values;\n- provider ingress destinations and signing-secret references;\n- durable-store backup identities and restoration procedure;\n- the signed fleet admission package and trust policy;\n- the proposed tenant binding revision;\n- a list of active and recently completed action IDs.\n\nDo not put database URLs, signing seeds, provider tokens, OAuth secrets,\nwebhook secrets, or private trust roots in the migration record.\n\n## Inventory the bundled boundary\n\nCapture a baseline from the exact deployment you will migrate. The\n`aipd-legacy-bundled` source preserves the older command-line surface,\nnormalized readiness fields, default manifest, and default MCP tool catalog as\ncompatibility fixtures. That source-level compatibility is useful for a\nbaseline, but it does not prove that a particular deployment is healthy or\nthat a fleet artifact is admitted.\n\nRecord the following for the selected connector:\n\n| Boundary | Record before cutover |\n|---|---|\n| Contract | Connector ID, capability IDs, kinds, schemas, risk, side effects, and manifest digest |\n| Implementation | Source revision, artifact identity, and supported operation claims |\n| Provider scope | Tenant, account, workspace, application, or endpoint set |\n| Configuration | Non-secret values, defaults, limits, and owning process |\n| Credentials | Opaque reference, issuer, scopes, account, rotation, and expiry |\n| Runtime state | Active actions, idempotency reservations, transactions, checkpoints, and results |\n| Product state | Provider operation IDs and unresolved or asynchronous jobs |\n| Ingress state | Destination, signatures, timestamp policy, replay store, and pending deliveries |\n| Egress state | Callbacks, streams, queued events, retries, and delivery acknowledgements |\n| Routing | Clients, tenant, capability, and the current authoritative execution path |\n\nCompare the bundled manifest with the manifest generated by the standalone\nconnector under the target configuration class. Capability IDs, schemas,\nside-effect declarations, identity requirements, idempotency behavior,\napproval requirements, and transaction behavior should remain unchanged.\n\nIf the old contract overclaims behavior, handle that correction as a separate\nreviewed release. Do not hide the contract change inside a process migration.\n\n## Separate gateway and product configuration\n\nThe target gateway is product-neutral. It owns AIP edge authentication,\nverified tenant identity, runtime state, registry data-plane access, remote\ndispatch policy, scheduling limits, and central event ingress. It does not own\nprovider credentials or product-specific endpoints.\n\nThe standalone host owns the connector's bounded provider configuration. All\nsix public host binaries flatten the common `ConnectorHostBootstrapArgs` and\nthen add product-specific arguments. Move values according to ownership:\n\n| Bundled value | Target owner |\n|---|---|\n| Provider base URL or product endpoint inventory | Product host |\n| Provider token, OAuth secret, sidecar token, or webhook secret | Owner-controlled host file |\n| Tenant-to-provider account mapping | Host configuration plus admitted instance identity |\n| Webhook replay storage | Product host durable boundary |\n| Gateway edge identity and client trust | Product-neutral `aipd` |\n| Connector registry data-plane URL | Product-neutral `aipd` owner-only file |\n| Gateway fleet signing seed | Product-neutral `aipd` owner-only file |\n| Host, control-plane, and gateway DIDs | Deployment trust configuration |\n| Connector type, version, instance, replica, and binding | Signed registry admission package |\n\nDo not translate a secret file into an environment value or command-line\nliteral. Preserve the credential's scope and provider account while changing\nwhich process reads the file. Rotate the credential if the old process cannot\nbe prevented from using it after cutover.\n\nThe common host boundary also requires exact public and control-plane endpoints,\na runtime database URL file, and a signing-seed file. It also requires connector\ntype and version, instance and replica IDs, a verified tenant, central gateway\nidentity, artifact digest, and a non-secret secret-provider reference. These\nvalues must match the admitted records; they are not labels that the host may\ninvent at\nstartup.\n\n## Prepare and admit the standalone host\n\nBuild the host from the reviewed source and retain its immutable digest. Use the\nmanifest and implementation support generated for the same artifact and\nconfiguration class.\n\nPrepare a signed admission package containing:\n\n- the connector type and immutable version;\n- the exact artifact and manifest digests;\n- implementation support for each callable capability;\n- a tenant-owned connector instance;\n- a pre-provisioned offline replica;\n- an initially disabled tenant capability binding;\n- bounded admission policy;\n- valid OCI signature, SBOM, provenance, conformance, vulnerability-policy,\n  license-policy, and revocation-observation evidence.\n\nVerify the package without writing:\n\n```sh\naipctl connector registry plan \\\n  --package signed-admission.json \\\n  --trust-policy admission-trust-policy.json\n```\n\nApply that exact package only after the plan output matches the intended type,\nversion, instance, replica, tenant, capabilities, and disabled binding:\n\n```sh\naipctl connector registry apply \\\n  --package signed-admission.json \\\n  --trust-policy admission-trust-policy.json \\\n  --database-url-file registry-database-url\n```\n\nDo not give the host or gateway registry-administrator credentials. The\ngateway uses the registry data plane for catalog and route resolution. The\nstandalone control-plane service owns the narrow signed register, heartbeat,\ndrain, and offline lifecycle boundary.\n\n## Prepare the product-neutral gateway\n\nConfigure the product-neutral `aipd` with:\n\n- an owner-only connector-registry data-plane URL file;\n- an owner-only Ed25519 signing-seed file;\n- either an explicit host allowlist or trust in admitted registry endpoints;\n- TLS trust for private PKI when applicable;\n- explicit HTTP or private-network exceptions only for controlled development;\n- request timeout, response bound, retry budget, client-pool bound, topology,\n  and admission limits appropriate to the deployment;\n- a central callback URL when remote streaming is enabled;\n- bounded connector-event ingress limits.\n\nFleet configuration is atomic at startup. The pinned implementation rejects a\npartial fleet configuration, requires the registry URL and signing seed, and\nrequires either a host allowlist or registry-endpoint trust.\n\nWhen enabled, the gateway installs the registry-backed capability catalog,\nremote connector handler, fair admission scheduler, fleet status provider, and\nsigned connector-event ingress as one product-neutral composition. Product\nconnector code is not part of that composition.\n\nStart or restart the product-neutral gateway without enabling the new tenant\nbinding. Confirm its normal readiness and registry connectivity before you\nstart the product host. Do not infer host eligibility from gateway health.\n\n## Decide what happens to existing state\n\nThe standalone host opens its own durable PostgreSQL runtime. The pinned source\ndoes not expose a generic bundled-to-host state importer. Do not copy tables,\nserialized files, replay databases, or runtime directories between unrelated\nstores unless the selected connector has a separately reviewed migration tool\nand rollback procedure.\n\nUse this decision table:\n\n| State class | Migration action |\n|---|---|\n| Completed gateway action history | Keep in the existing gateway store; do not replay provider work |\n| Active synchronous action | Let it reach a known terminal state before switching |\n| Active provider job | Retain its provider operation ID and reconcile it through the old owner |\n| Unknown mutation outcome | Stop cutover until the provider state is reconciled |\n| Idempotency reservation | Keep the old path authoritative until its result is known or its policy expires |\n| Transaction or compensation state | Finish or explicitly abort under the original execution owner |\n| Pending stream or callback | Drain and verify acknowledgement before disabling the old path |\n| Webhook replay record | Keep the old ingress authoritative until the destination switch is complete |\n| New host runtime | Start empty unless a connector-specific, reviewed importer says otherwise |\n\nAn identical idempotency key in two independent stores is not a shared\nreservation. It can result in two provider calls. Pausing new mutations and\ndraining the old owner is therefore a safety control, not an optional cleanup.\n\n## Start the host without routing traffic\n\nStart one replica with the exact admitted identity and artifact digest. The\ncommon host preparation validates its configuration and trust, discovers the\nconnector manifest, and opens durable storage. Serving recovers durable work,\nregisters the replica, renews its lease, and exposes:\n\n| Route | Cutover use |\n|---|---|\n| `GET /health` | Confirms process and protocol identity |\n| `GET /ready` | Confirms valid lease, storage, connector, and non-draining state |\n| `GET /metrics` | Shows bounded host lifecycle and request signals |\n| `GET /aip/v1/manifest` | Exposes the exact running manifest for comparison |\n| `POST /aip/v1/messages` | Accepts signed, route-pinned AIP execution from the gateway |\n\nRequire `/ready`, not `/health`, before considering the replica eligible. Also\nconfirm that the registry reports the expected type, version, instance,\nreplica, artifact digest, endpoint, tenant, lease, and capacity.\n\nKeep the tenant binding disabled. Registration and readiness prove host\nlifecycle state; they do not authorize tenant traffic.\n\n## Shadow only non-mutating behavior\n\nCompare the old and new boundaries before cutover without giving both authority\nto mutate the provider.\n\nSafe comparisons include:\n\n1. canonical manifests and capability schemas;\n2. connector discovery and implementation support;\n3. `/health`, `/ready`, and bounded metrics;\n4. deterministic provider fixtures;\n5. provider reads that the capability contract classifies as non-mutating;\n6. error mapping for rejected or malformed inputs;\n7. tenant, account, credential issuer, and trust identities in retained traces.\n\nDo not shadow creates, updates, deletes, messages, bookings, long-running jobs,\nor any operation whose side effects are uncertain. A dry-run label is not\nsufficient unless the connector and provider contract both guarantee that no\nprovider effect occurs.\n\nRecord differences by contract field. Stop if the new host publishes a missing\nor extra capability, a changed schema, weaker approval or idempotency behavior,\nan unexpected provider account, or an implementation claim that the host does\nnot exercise.\n\n## Cut over one tenant binding\n\nUse one controlled sequence:\n\n1. Pause new mutations for the selected tenant and capabilities.\n2. Let bundled actions, callbacks, streams, and provider jobs reach known\n   states.\n3. Reconcile every unknown provider outcome under the bundled owner.\n4. Disable the bundled connector configuration or replace the compatibility\n   process with product-neutral `aipd` for this boundary.\n5. Restart as required and confirm the bundled capability is no longer handled\n   locally.\n6. Change provider webhook or callback delivery to the standalone host when the\n   connector uses ingress.\n7. Enable the reviewed tenant capability binding at a new policy revision.\n8. Confirm that registry discovery exposes the capability only to the intended\n   tenant and selects the expected instance.\n9. Resume one approved non-mutating request through the normal client path.\n10. Resume bounded mutations only after the read path, lease, metrics, and\n    retained trace identify the admitted replica.\n\nThe tenant capability binding is the fleet routing authorization. A route\nassignment then pins the action to an exact instance, ready replica, endpoint,\npeer identity, connector version, manifest digest, catalog revision, binding\npolicy revision, credential revision, and assignment fence.\n\nDo not leave the same capability active as both a local bundled handler and a\nfleet binding. Local and remote state do not share an idempotency reservation,\nand traffic precedence is not a migration control.\n\n## Verify the cutover\n\nVerify the result at four boundaries:\n\n| Boundary | Required observation |\n|---|---|\n| Contract | Manifest digest and capability behavior match the reviewed target |\n| Routing | Tenant binding and retained assignment identify the intended instance and replica |\n| Lifecycle | Host is ready, lease is current, and active assignments settle |\n| Provider | The intended account records one effect for one mutation and no duplicate from the old path |\n\nAlso confirm:\n\n- the bundled process no longer reads the migrated provider credential;\n- only the selected ingress destination receives new provider deliveries;\n- old callback and webhook queues are empty or explicitly retained;\n- gateway and host logs contain no secret values or unbounded provider bodies;\n- retry, cancellation, approval, and reconciliation follow the published\n  contract;\n- an action status lookup reads stored state without repeating provider work;\n- the migration record distinguishes source review, artifact admission,\n  conformance, deployment observation, and live-provider evidence.\n\nObserve for at least the longest relevant action, provider job, callback, and\nwebhook replay window before declaring the old boundary removable.\n\n## Resolve cutover failures\n\n| Symptom | Decision |\n|---|---|\n| Fleet options are rejected at gateway startup | Complete the registry, signing, and host-trust set; do not bypass validation |\n| Host health succeeds but readiness fails | Inspect storage, connector health, lease, identity, artifact, and control-plane trust |\n| No tenant binding is found | Verify the tenant, capability, instance, enabled flag, and policy revision |\n| No ready replica is available | Keep mutations paused and inspect lease, drain state, capacity, and endpoint admission |\n| Manifest differs from the baseline | Stop; determine whether configuration or contract changed |\n| First request reaches the wrong provider account | Disable the binding and rotate or correct the credential mapping |\n| A mutation times out after dispatch | Reconcile the provider operation; do not retry through the bundled path |\n| Both ingress paths receive one event | Disable one destination and reconcile replay state before resuming delivery |\n| The old process still has active work | Restore its authority only long enough to drain or reconcile that work |\n\nDo not repair a failed migration by deleting route assignments, replay records,\nidempotency state, or provider operation IDs. Those records are evidence needed\nto prevent a second effect.\n\n## Roll back without double execution\n\nRollback changes future routing; it does not erase provider effects already\ncreated by the new host.\n\n1. Pause new mutations.\n2. Disable the fleet binding so no new assignment selects the host.\n3. Begin host drain and wait for active assignments to settle.\n4. Reconcile every non-terminal or unknown provider operation through the host\n   that created it.\n5. Mark the replica offline through the lifecycle boundary and stop it.\n6. Restore the previous provider ingress destination only after the new ingress\n   queue is drained or retained.\n7. Restore the exact bundled artifact, configuration, credential revision, and\n   durable store.\n8. Confirm the local capability and provider account before resuming a\n   non-mutating request.\n9. Resume mutations only after the rollback owner confirms there is no\n   overlapping work.\n\nKeep the admitted fleet records and failed migration evidence until the review\nis complete. Revoke an artifact or credential when the failure concerns its\nintegrity or exposure; disabling a tenant binding alone does not invalidate\neither.\n\n## Repeat with a fresh boundary\n\nAccept the first connector migration before starting another. Create a new\ninventory, state decision, signed admission package, binding revision,\nverification record, and rollback decision for each connector and tenant\nboundary.\n\nThe six public connectors have separate host packages and product-specific\nconfiguration. A result for Cal.diy does not prove Hermes Agent, Chatwoot,\nDify, CrewAI, or Twenty. Carry forward only the process controls; collect new\ncontract and provider evidence for every host artifact.\n\n## Related documentation\n\n- [Profiles and connectors](../concepts/profiles-and-connectors.md)\n- [Identity and trust](../concepts/identity-and-trust.md)\n- [Connector catalog](../connectors/README.md)\n",
    "text": "Migrate bundled connectors to the fleet\n\nUse this guide to move one product connector from an aipd process into an\nadmitted standalone connector host. It is for operators and connector owners\nwho can control the gateway, registry, host, provider credentials, ingress, and\nrollback window.\n\nThe procedure preserves the AIP 1.0 capability contract while changing where\nthe provider operation executes. It keeps one authoritative mutation path at a\ntime, verifies the new path with non-mutating work, and switches one tenant\nbinding only after the old path has drained.\n\nThe pinned source contains a compatibility binary named\naipd-legacy-bundled, a product-neutral aipd, and standalone hosts for the\nsix public connectors: Cal.diy, Hermes Agent, Chatwoot, Dify, CrewAI, and\nTwenty. It does not contain a generic command that imports bundled connector\nstate into a host database.\n\nThis guide reflects source revision\n97be86e9efedf07ecf1783b03800f683f107fb04.\n\nUse this procedure for one execution boundary\n\nApply this migration when a connector implementation or trusted local module\nruns in the same process as the gateway and the target connector already has:\n• a frozen connector implementation;\n• a standalone host binary;\n• an immutable host artifact and exact digest;\n• a reviewed manifest and implementation support map;\n• the evidence required for fleet admission;\n• a tenant-owned provider account or endpoint boundary.\n\nIf the connector still uses legacy SDK traits, complete\nUpgrade a connector to the frozen SDK (upgrade-connector-sdk.md) first. If no\nstandalone host or admission package exists, follow\nBuild a connector (build-a-connector.md).\n\nDo not combine this migration with capability renaming, schema changes,\nprovider account consolidation, credential-scope expansion, or a wire-version\nchange. Each would make it harder to distinguish a deployment failure from a\ncontract change.\n\nMigrate one connector type, tenant, and provider boundary at a time. A\ndeployment may contain fewer than the six public connectors; do not create an\nunused instance merely to make the fleet catalog look complete.\n\nPrepare authority and a rollback window\n\nAssign an owner for each control before changing traffic:\n\n| Control | Required authority |\n\n| Bundled process | Remove or restore the connector configuration and restart safely |\n| Product-neutral gateway | Configure registry access, signing, trust, and limits |\n| Connector registry | Plan and apply a signed admission package and change bindings |\n| Standalone host | Deploy the admitted digest, inspect readiness, drain, and stop it |\n| Provider account | Rotate credentials and change webhook or callback destinations |\n| Durable stores | Retain, inspect, and restore gateway, host, and ingress state |\n| Client traffic | Pause or bound mutations and run an approved read-only check |\n| Evidence | Record identities, revisions, timestamps, outcomes, and rollback decisions |\n\nChoose a window long enough for the connector's maximum action duration,\nprovider job duration, retry window, callback delay, and webhook replay window.\nStop before migration if active work cannot be enumerated or if the provider\ncannot distinguish completed, failed, and unknown mutations.\n\nRetain these rollback inputs outside the deployment:\n• the current gateway artifact and complete non-secret configuration;\n• canonical bundled manifest and capability schemas;\n• provider credential references and their revisions, without secret values;\n• provider ingress destinations and signing-secret references;\n• durable-store backup identities and restoration procedure;\n• the signed fleet admission package and trust policy;\n• the proposed tenant binding revision;\n• a list of active and recently completed action IDs.\n\nDo not put database URLs, signing seeds, provider tokens, OAuth secrets,\nwebhook secrets, or private trust roots in the migration record.\n\nInventory the bundled boundary\n\nCapture a baseline from the exact deployment you will migrate. The\naipd-legacy-bundled source preserves the older command-line surface,\nnormalized readiness fields, default manifest, and default MCP tool catalog as\ncompatibility fixtures. That source-level compatibility is useful for a\nbaseline, but it does not prove that a particular deployment is healthy or\nthat a fleet artifact is admitted.\n\nRecord the following for the selected connector:\n\n| Boundary | Record before cutover |\n\n| Contract | Connector ID, capability IDs, kinds, schemas, risk, side effects, and manifest digest |\n| Implementation | Source revision, artifact identity, and supported operation claims |\n| Provider scope | Tenant, account, workspace, application, or endpoint set |\n| Configuration | Non-secret values, defaults, limits, and owning process |\n| Credentials | Opaque reference, issuer, scopes, account, rotation, and expiry |\n| Runtime state | Active actions, idempotency reservations, transactions, checkpoints, and results |\n| Product state | Provider operation IDs and unresolved or asynchronous jobs |\n| Ingress state | Destination, signatures, timestamp policy, replay store, and pending deliveries |\n| Egress state | Callbacks, streams, queued events, retries, and delivery acknowledgements |\n| Routing | Clients, tenant, capability, and the current authoritative execution path |\n\nCompare the bundled manifest with the manifest generated by the standalone\nconnector under the target configuration class. Capability IDs, schemas,\nside-effect declarations, identity requirements, idempotency behavior,\napproval requirements, and transaction behavior should remain unchanged.\n\nIf the old contract overclaims behavior, handle that correction as a separate\nreviewed release. Do not hide the contract change inside a process migration.\n\nSeparate gateway and product configuration\n\nThe target gateway is product-neutral. It owns AIP edge authentication,\nverified tenant identity, runtime state, registry data-plane access, remote\ndispatch policy, scheduling limits, and central event ingress. It does not own\nprovider credentials or product-specific endpoints.\n\nThe standalone host owns the connector's bounded provider configuration. All\nsix public host binaries flatten the common ConnectorHostBootstrapArgs and\nthen add product-specific arguments. Move values according to ownership:\n\n| Bundled value | Target owner |\n\n| Provider base URL or product endpoint inventory | Product host |\n| Provider token, OAuth secret, sidecar token, or webhook secret | Owner-controlled host file |\n| Tenant-to-provider account mapping | Host configuration plus admitted instance identity |\n| Webhook replay storage | Product host durable boundary |\n| Gateway edge identity and client trust | Product-neutral aipd |\n| Connector registry data-plane URL | Product-neutral aipd owner-only file |\n| Gateway fleet signing seed | Product-neutral aipd owner-only file |\n| Host, control-plane, and gateway DIDs | Deployment trust configuration |\n| Connector type, version, instance, replica, and binding | Signed registry admission package |\n\nDo not translate a secret file into an environment value or command-line\nliteral. Preserve the credential's scope and provider account while changing\nwhich process reads the file. Rotate the credential if the old process cannot\nbe prevented from using it after cutover.\n\nThe common host boundary also requires exact public and control-plane endpoints,\na runtime database URL file, and a signing-seed file. It also requires connector\ntype and version, instance and replica IDs, a verified tenant, central gateway\nidentity, artifact digest, and a non-secret secret-provider reference. These\nvalues must match the admitted records; they are not labels that the host may\ninvent at\nstartup.\n\nPrepare and admit the standalone host\n\nBuild the host from the reviewed source and retain its immutable digest. Use the\nmanifest and implementation support generated for the same artifact and\nconfiguration class.\n\nPrepare a signed admission package containing:\n• the connector type and immutable version;\n• the exact artifact and manifest digests;\n• implementation support for each callable capability;\n• a tenant-owned connector instance;\n• a pre-provisioned offline replica;\n• an initially disabled tenant capability binding;\n• bounded admission policy;\n• valid OCI signature, SBOM, provenance, conformance, vulnerability-policy,\n  license-policy, and revocation-observation evidence.\n\nVerify the package without writing:\n\naipctl connector registry plan \\\n  --package signed-admission.json \\\n  --trust-policy admission-trust-policy.json\n\nApply that exact package only after the plan output matches the intended type,\nversion, instance, replica, tenant, capabilities, and disabled binding:\n\naipctl connector registry apply \\\n  --package signed-admission.json \\\n  --trust-policy admission-trust-policy.json \\\n  --database-url-file registry-database-url\n\nDo not give the host or gateway registry-administrator credentials. The\ngateway uses the registry data plane for catalog and route resolution. The\nstandalone control-plane service owns the narrow signed register, heartbeat,\ndrain, and offline lifecycle boundary.\n\nPrepare the product-neutral gateway\n\nConfigure the product-neutral aipd with:\n• an owner-only connector-registry data-plane URL file;\n• an owner-only Ed25519 signing-seed file;\n• either an explicit host allowlist or trust in admitted registry endpoints;\n• TLS trust for private PKI when applicable;\n• explicit HTTP or private-network exceptions only for controlled development;\n• request timeout, response bound, retry budget, client-pool bound, topology,\n  and admission limits appropriate to the deployment;\n• a central callback URL when remote streaming is enabled;\n• bounded connector-event ingress limits.\n\nFleet configuration is atomic at startup. The pinned implementation rejects a\npartial fleet configuration, requires the registry URL and signing seed, and\nrequires either a host allowlist or registry-endpoint trust.\n\nWhen enabled, the gateway installs the registry-backed capability catalog,\nremote connector handler, fair admission scheduler, fleet status provider, and\nsigned connector-event ingress as one product-neutral composition. Product\nconnector code is not part of that composition.\n\nStart or restart the product-neutral gateway without enabling the new tenant\nbinding. Confirm its normal readiness and registry connectivity before you\nstart the product host. Do not infer host eligibility from gateway health.\n\nDecide what happens to existing state\n\nThe standalone host opens its own durable PostgreSQL runtime. The pinned source\ndoes not expose a generic bundled-to-host state importer. Do not copy tables,\nserialized files, replay databases, or runtime directories between unrelated\nstores unless the selected connector has a separately reviewed migration tool\nand rollback procedure.\n\nUse this decision table:\n\n| State class | Migration action |\n\n| Completed gateway action history | Keep in the existing gateway store; do not replay provider work |\n| Active synchronous action | Let it reach a known terminal state before switching |\n| Active provider job | Retain its provider operation ID and reconcile it through the old owner |\n| Unknown mutation outcome | Stop cutover until the provider state is reconciled |\n| Idempotency reservation | Keep the old path authoritative until its result is known or its policy expires |\n| Transaction or compensation state | Finish or explicitly abort under the original execution owner |\n| Pending stream or callback | Drain and verify acknowledgement before disabling the old path |\n| Webhook replay record | Keep the old ingress authoritative until the destination switch is complete |\n| New host runtime | Start empty unless a connector-specific, reviewed importer says otherwise |\n\nAn identical idempotency key in two independent stores is not a shared\nreservation. It can result in two provider calls. Pausing new mutations and\ndraining the old owner is therefore a safety control, not an optional cleanup.\n\nStart the host without routing traffic\n\nStart one replica with the exact admitted identity and artifact digest. The\ncommon host preparation validates its configuration and trust, discovers the\nconnector manifest, and opens durable storage. Serving recovers durable work,\nregisters the replica, renews its lease, and exposes:\n\n| Route | Cutover use |\n\n| GET /health | Confirms process and protocol identity |\n| GET /ready | Confirms valid lease, storage, connector, and non-draining state |\n| GET /metrics | Shows bounded host lifecycle and request signals |\n| GET /aip/v1/manifest | Exposes the exact running manifest for comparison |\n| POST /aip/v1/messages | Accepts signed, route-pinned AIP execution from the gateway |\n\nRequire /ready, not /health, before considering the replica eligible. Also\nconfirm that the registry reports the expected type, version, instance,\nreplica, artifact digest, endpoint, tenant, lease, and capacity.\n\nKeep the tenant binding disabled. Registration and readiness prove host\nlifecycle state; they do not authorize tenant traffic.\n\nShadow only non-mutating behavior\n\nCompare the old and new boundaries before cutover without giving both authority\nto mutate the provider.\n\nSafe comparisons include:\n1. canonical manifests and capability schemas;\n2. connector discovery and implementation support;\n3. /health, /ready, and bounded metrics;\n4. deterministic provider fixtures;\n5. provider reads that the capability contract classifies as non-mutating;\n6. error mapping for rejected or malformed inputs;\n7. tenant, account, credential issuer, and trust identities in retained traces.\n\nDo not shadow creates, updates, deletes, messages, bookings, long-running jobs,\nor any operation whose side effects are uncertain. A dry-run label is not\nsufficient unless the connector and provider contract both guarantee that no\nprovider effect occurs.\n\nRecord differences by contract field. Stop if the new host publishes a missing\nor extra capability, a changed schema, weaker approval or idempotency behavior,\nan unexpected provider account, or an implementation claim that the host does\nnot exercise.\n\nCut over one tenant binding\n\nUse one controlled sequence:\n1. Pause new mutations for the selected tenant and capabilities.\n2. Let bundled actions, callbacks, streams, and provider jobs reach known\n   states.\n3. Reconcile every unknown provider outcome under the bundled owner.\n4. Disable the bundled connector configuration or replace the compatibility\n   process with product-neutral aipd for this boundary.\n5. Restart as required and confirm the bundled capability is no longer handled\n   locally.\n6. Change provider webhook or callback delivery to the standalone host when the\n   connector uses ingress.\n7. Enable the reviewed tenant capability binding at a new policy revision.\n8. Confirm that registry discovery exposes the capability only to the intended\n   tenant and selects the expected instance.\n9. Resume one approved non-mutating request through the normal client path.\n10. Resume bounded mutations only after the read path, lease, metrics, and\n    retained trace identify the admitted replica.\n\nThe tenant capability binding is the fleet routing authorization. A route\nassignment then pins the action to an exact instance, ready replica, endpoint,\npeer identity, connector version, manifest digest, catalog revision, binding\npolicy revision, credential revision, and assignment fence.\n\nDo not leave the same capability active as both a local bundled handler and a\nfleet binding. Local and remote state do not share an idempotency reservation,\nand traffic precedence is not a migration control.\n\nVerify the cutover\n\nVerify the result at four boundaries:\n\n| Boundary | Required observation |\n\n| Contract | Manifest digest and capability behavior match the reviewed target |\n| Routing | Tenant binding and retained assignment identify the intended instance and replica |\n| Lifecycle | Host is ready, lease is current, and active assignments settle |\n| Provider | The intended account records one effect for one mutation and no duplicate from the old path |\n\nAlso confirm:\n• the bundled process no longer reads the migrated provider credential;\n• only the selected ingress destination receives new provider deliveries;\n• old callback and webhook queues are empty or explicitly retained;\n• gateway and host logs contain no secret values or unbounded provider bodies;\n• retry, cancellation, approval, and reconciliation follow the published\n  contract;\n• an action status lookup reads stored state without repeating provider work;\n• the migration record distinguishes source review, artifact admission,\n  conformance, deployment observation, and live-provider evidence.\n\nObserve for at least the longest relevant action, provider job, callback, and\nwebhook replay window before declaring the old boundary removable.\n\nResolve cutover failures\n\n| Symptom | Decision |\n\n| Fleet options are rejected at gateway startup | Complete the registry, signing, and host-trust set; do not bypass validation |\n| Host health succeeds but readiness fails | Inspect storage, connector health, lease, identity, artifact, and control-plane trust |\n| No tenant binding is found | Verify the tenant, capability, instance, enabled flag, and policy revision |\n| No ready replica is available | Keep mutations paused and inspect lease, drain state, capacity, and endpoint admission |\n| Manifest differs from the baseline | Stop; determine whether configuration or contract changed |\n| First request reaches the wrong provider account | Disable the binding and rotate or correct the credential mapping |\n| A mutation times out after dispatch | Reconcile the provider operation; do not retry through the bundled path |\n| Both ingress paths receive one event | Disable one destination and reconcile replay state before resuming delivery |\n| The old process still has active work | Restore its authority only long enough to drain or reconcile that work |\n\nDo not repair a failed migration by deleting route assignments, replay records,\nidempotency state, or provider operation IDs. Those records are evidence needed\nto prevent a second effect.\n\nRoll back without double execution\n\nRollback changes future routing; it does not erase provider effects already\ncreated by the new host.\n1. Pause new mutations.\n2. Disable the fleet binding so no new assignment selects the host.\n3. Begin host drain and wait for active assignments to settle.\n4. Reconcile every non-terminal or unknown provider operation through the host\n   that created it.\n5. Mark the replica offline through the lifecycle boundary and stop it.\n6. Restore the previous provider ingress destination only after the new ingress\n   queue is drained or retained.\n7. Restore the exact bundled artifact, configuration, credential revision, and\n   durable store.\n8. Confirm the local capability and provider account before resuming a\n   non-mutating request.\n9. Resume mutations only after the rollback owner confirms there is no\n   overlapping work.\n\nKeep the admitted fleet records and failed migration evidence until the review\nis complete. Revoke an artifact or credential when the failure concerns its\nintegrity or exposure; disabling a tenant binding alone does not invalidate\neither.\n\nRepeat with a fresh boundary\n\nAccept the first connector migration before starting another. Create a new\ninventory, state decision, signed admission package, binding revision,\nverification record, and rollback decision for each connector and tenant\nboundary.\n\nThe six public connectors have separate host packages and product-specific\nconfiguration. A result for Cal.diy does not prove Hermes Agent, Chatwoot,\nDify, CrewAI, or Twenty. Carry forward only the process controls; collect new\ncontract and provider evidence for every host artifact.\n\nRelated documentation\n• Profiles and connectors (../concepts/profiles-and-connectors.md)\n• Identity and trust (../concepts/identity-and-trust.md)\n• Connector catalog (../connectors/README.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "0f840379595d69e3c2a5dead7a73b3e28d5f77336dbdce04f715a1e26a46103d"
  }
}