{
  "schemaVersion": "1.0",
  "title": "Deploy AIP in production",
  "description": "Use this guide to design and stage a production AIP deployment. It is for operators who own the authenticated edge, product-neutral getaip-server replicas, durable state, connector registry, lifecycle control plane, standalone connector hos",
  "canonical": "https://getaip.org/docs/guides/production-deployment",
  "route": "/docs/guides/production-deployment",
  "source": "docs/guides/production-deployment.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Deploy and Operate",
  "documentType": "Guide",
  "language": "en",
  "revision": {
    "lastReviewedRevision": "d7cce13d1d555644d04a4d73c66c95b113737635",
    "documentationSourceRevision": "9192fef3695ad294994f2712f6d156241e5e92fb",
    "basis": "frontmatter"
  },
  "downloads": {
    "md": "/docs/download/guides/production-deployment.md",
    "txt": "/docs/download/guides/production-deployment.txt",
    "json": "/docs/download/guides/production-deployment.json",
    "pdf": "/docs/download/guides/production-deployment.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Deploy AIP in production\ndescription: Stage a production AIP topology with explicit trust state and rollback boundaries\nkind: how-to\naudience: operator\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"d7cce13d1d555644d04a4d73c66c95b113737635\"\n---\n\n# Deploy AIP in production\n\nUse this guide to design and stage a production AIP deployment. It is for\noperators who own the authenticated edge, product-neutral `getaip-server` replicas,\ndurable state, connector registry, lifecycle control plane, standalone\nconnector hosts, and release evidence.\n\nThe result is a bounded deployment candidate with explicit ownership, trust,\ntraffic gates, recovery, and rollback. Production readiness remains a claim\nabout an exact artifact set, configuration, topology, provider boundary, time,\nand retained evidence. A source revision, successful build, health response,\nor admission package does not establish that claim by itself.\n\nThis guide reflects source revision\n`d7cce13d1d555644d04a4d73c66c95b113737635`. It does not prescribe a cloud,\norchestrator, ingress controller, PostgreSQL service, NATS service, or secret\nmanager.\n\n## Use this procedure for a complete deployment boundary\n\nApply this procedure after the selected AIP artifacts and connector contracts\nhave been reviewed. Complete [Install AIP](../getting-started/installation.md)\nbefore planning the production environment.\n\nYou need authority to:\n\n- approve exact gateway, control-plane, host, and migration artifacts;\n- provision networks, identities, databases, keys, and secret references;\n- apply registry migrations, grants, admission packages, and tenant bindings;\n- change external routes, provider ingress, and client traffic;\n- take and restore backups;\n- pause mutations, drain workloads, and execute rollback;\n- retain qualification and deployment evidence.\n\nStop before deployment if the team cannot name one owner for identity,\ndatabase recovery, connector admission, provider credentials, ingress,\nincident response, and rollback. Shared infrastructure does not remove these\nownership boundaries.\n\n## Use the product-neutral topology\n\nThe production boundary separates client-facing protocol handling from product\nexecution. `getaip-server` authenticates requests, owns AIP lifecycle state, discovers\ntenant-visible capabilities, and routes connector work. Standalone connector\nhosts own provider configuration, credentials, product calls, and authenticated\nproduct ingress.\n\n```mermaid\nflowchart LR\n    Clients[\"Native AIP, MCP, and A2A clients\"] --> Edge[\"TLS and authenticated edge\"]\n    Edge --> Core[\"Product-neutral getaip-server replicas\"]\n    Core --> RuntimeDB[(\"Shared AIP runtime PostgreSQL\")]\n    Core -. optional .-> NATS[\"Authenticated NATS fabric\"]\n    Core --> Registry[(\"Connector registry data plane\")]\n    Identity[\"Identity and approval authorities\"] --> Core\n\n    Release[\"Release and admission operator\"] --> RegistryAdmin[\"Registry migration and admission\"]\n    RegistryAdmin --> Registry\n    Control[\"Signed connector lifecycle control plane\"] --> Registry\n\n    Core --> Hosts[\"Admitted standalone connector hosts\"]\n    Hosts --> Control\n    Hosts --> HostDB[(\"Host-owned durable state\")]\n    Hosts --> Products[\"Product APIs\"]\n    Products --> Ingress[\"Authenticated product ingress\"]\n    Ingress --> Hosts\n    Hosts --> Events[\"Signed central event and callback ingress\"]\n    Events --> Core\n```\n\nKeep these roles distinct even when one managed PostgreSQL cluster or one\norchestrator runs several components. Do not embed product connector code or\nprovider credentials into the product-neutral `getaip-server` artifact.\n\nThe repository contains a connector-fleet Compose topology for controlled\ndevelopment and qualification. Its presence is evidence of a reference path,\nnot a production deployment template or a claim about any external provider.\n\n## Define the release unit and claim\n\nFreeze one deployment release record before provisioning. Include:\n\n| Release element | Identity to retain |\n|---|---|\n| AIP source | Full commit and source-tree digest |\n| Gateway | Immutable artifact digest and AIP schema set |\n| Registry migration | Exact binary or migration source and required schema version |\n| Lifecycle control plane | Immutable artifact digest and signer DID |\n| Connector host | Product, source revision, immutable digest, and manifest digest |\n| Admission | Signed package ID, revision, digest, trust policy, and evidence expirations |\n| Configuration | Redacted revision and deployment-owned defaults |\n| Trust | Principal IDs, DIDs, trust domain, issuer, audience, and authority revisions |\n| Storage | Database identities, schema revisions, backup IDs, and restore procedure |\n| Provider | Account, workspace, application, endpoint set, and upstream revision |\n| Qualification | Exact topology, procedure, result, time, and retained artifacts |\n\nThe release unit may contain only the connector families the deployment needs.\nThe public source provides standalone hosts for Cal.diy, Hermes Agent,\nChatwoot, Dify, CrewAI, and Twenty, but evidence for one does not qualify the\nothers.\n\nDefine the intended production claim in one sentence. Name the tenants,\nprofiles, capabilities, connector versions, provider accounts, topology, and\nevidence window. Anything outside that sentence remains unsupported by this\ndeployment record.\n\n## Segment networks and authority\n\nCreate separate network and credential boundaries for:\n\n| Zone | Permitted communication |\n|---|---|\n| Public edge | Client TLS to the published AIP, MCP, or A2A origin |\n| Core service | Edge to `getaip-server`; `getaip-server` to runtime storage, registry data plane, and admitted hosts |\n| Registry administration | Short-lived migration and admission jobs to registry control credentials |\n| Lifecycle | Connector hosts to the signed lifecycle endpoint and lifecycle database role |\n| Connector host | Gateway and lifecycle traffic, host database, approved product endpoints, and central ingress |\n| Product ingress | Provider delivery to the product-specific authenticated host route |\n| Observability | Read-only collection of bounded health, readiness, metrics, logs, and traces |\n\nThe connector registry source supports independently permissioned control and\ndata pools. Production gateway and lifecycle processes connect through the\ndata-plane constructor, which verifies an already installed schema and retains\nno registry control pool. The reference grant policy limits gateway routing\nauthority and lifecycle replica authority to different table operations.\n\nKeep catalog migration and admission credentials in short-lived operator jobs.\nDo not mount them into `getaip-server`, the lifecycle service, or connector hosts.\n\nTerminate external TLS before the core listener and keep the listener on a\nprotected service network. A non-loopback `getaip-server` listener requires an external\nHTTPS origin. That origin must contain no credentials, path, query, or fragment.\nPlain HTTP is accepted only for explicit loopback development.\n\n## Provision durable state by owner\n\nTreat runtime, registry, and connector-host state as separate recovery domains:\n\n| State owner | Durable content | Access pattern |\n|---|---|---|\n| Core runtime | Actions, results, sessions, events, approvals, transactions, callbacks, receipts, replay, and idempotency | Shared by all replicas in one logical `getaip-server` deployment |\n| Connector registry | Types, versions, manifests, instances, replicas, bindings, assignments, admission counters, and journal | Admin job writes catalog; gateway routes; lifecycle service updates replica state |\n| Connector host | Provider-facing runtime, checkpoints, replay, outbox, and product-specific durable state | Owned by the admitted host boundary |\n\nUse PostgreSQL for a clustered core deployment. `PostgresRuntimeStore` installs\nand verifies immutable schema migrations at connection time, then supplies the\ncomplete runtime store set. A file-backed `storage_dir` is a single-host\nboundary and is not a clustered scheduler or shared failover store.\n\nInstall connector-registry migrations with administrative credentials before\nstarting data-plane services. The data-plane connection refuses a schema whose\nversion differs from the required version. Reconcile least-privilege grants\nafter migration so removed permissions do not survive from an older release.\n\nGive each logical state owner a separately restorable database and credential\nscope. One PostgreSQL service may host them, but do not point a connector host\nat the core runtime or registry database as an undocumented shortcut.\n\nBefore rollout:\n\n1. take named, time-stamped backups;\n2. record the database and schema revision represented by each backup;\n3. verify restoration in an isolated environment;\n4. measure recovery point and recovery time against the deployment objective;\n5. confirm that restoration preserves leases, fences, idempotency,\n   transactions, replay, assignments, and provider operation references.\n\nA database connection check is not a recovery test. Use controlled in-flight\nand unknown-outcome cases without affecting production provider data.\n\n## Establish identities and secrets\n\nFollow [Identity and trust](../concepts/identity-and-trust.md) to assign one\nstable identity to every security boundary. At minimum, record:\n\n- external client issuer, subject, audience, scopes, and tenant mapping;\n- `getaip-server` service principal, trust domain, signing DID, and trusted client DIDs;\n- MCP protected-resource identifier, authorization server, introspection\n  identity, audience, required scopes, and browser origins when MCP is public;\n- connector control-plane principal and signing DID;\n- each host principal, signing DID, tenant, membership, and provider account;\n- release-package and seven evidence-role trust roots;\n- approval authority and trusted identity directory revisions.\n\nThe pinned daemon defaults to deny-all identity and approval resolvers when no\ndeployment-owned directory is installed. Do not replace that behavior with\ncaller-supplied identity in action input or metadata.\n\nStore database URLs, bearer tokens, OAuth client secrets, signing seeds,\nprovider credentials, NATS passwords, and private keys in owner-controlled,\nbounded files or an equivalent mounted secret boundary. Keep only opaque secret\nprovider and credential revision references in registry and configuration\nrecords.\n\nSeparate these signing roles:\n\n- external client request identity;\n- gateway response, callback, and fleet dispatch identity;\n- lifecycle control-plane response identity;\n- connector-host request and event identity;\n- admission-package release authority;\n- each independent supply-chain evidence authority.\n\nDo not reuse one seed merely because the components share a trust domain.\n\n## Configure the published profiles\n\nExpose only the profiles that the deployment claim includes. The\n[profiles, transports, and connectors](../concepts/profiles-and-connectors.md)\npage defines their protocol roles.\n\nFor native HTTP:\n\n- require signed envelopes, or configure a server-owned bearer identity at the\n  trusted edge;\n- bind tenant and scopes after authentication;\n- publish an HTTPS origin;\n- bound request bodies, responses, streams, queues, and callbacks.\n\nFor MCP over HTTP:\n\n- publish protected-resource metadata;\n- advertise the accepted authorization server and resource identifier;\n- verify token issuer, audience, activity, and required scopes through the\n  configured verifier;\n- allow only exact browser origins when browser access is required;\n- keep stdio as a local process boundary rather than a public network edge.\n\nFor A2A:\n\n- publish the agent card from the external HTTPS origin;\n- protect task operations through the same trusted AIP identity boundary;\n- encrypt stored push credentials and restrict callback destinations.\n\nFor NATS, when selected:\n\n- configure the server URL, trust domain, service, version, and queue group;\n- supply username and owner-controlled password file together;\n- enforce account, subject, and TLS policy outside `getaip-server`;\n- include the NATS listener in the readiness and failure plan.\n\nDo not expose every profile merely because the binary implements it. Fewer\npublished surfaces reduce authentication, compatibility, and incident scope.\n\n## Install registry and lifecycle services\n\nUse this order:\n\n1. Install and verify the registry schema under the short-lived admin role.\n2. Reconcile gateway data-plane and lifecycle grants.\n3. Verify that data-plane credentials can read the schema version and only the\n   records their role requires.\n4. Start the connector lifecycle service behind its TLS boundary.\n5. Record its signer DID and distribute that public identity to admitted hosts.\n6. Verify lifecycle `/health`, `/ready`, and bounded `/metrics` separately.\n7. Plan each signed connector admission package without writing.\n8. Apply only the exact reviewed package revision and digest.\n\nThe lifecycle service exposes one signed control route for register, heartbeat,\ndrain, and offline commands. It deliberately retains no catalog-administration\npool. A host must already have a pre-provisioned replica identity; registration\ndoes not create an arbitrary connector or tenant binding.\n\nKeep tenant capability bindings disabled until the matching host artifact is\nrunning, ready, and verified.\n\n## Start the core before product traffic\n\nStart one `getaip-server` replica with:\n\n- the exact gateway artifact and HTTPS public origin;\n- shared PostgreSQL runtime credentials;\n- trusted signer, identity, approval, and profile policy revisions;\n- connector-registry data-plane credentials;\n- a fleet signing seed and host trust policy;\n- bounded callback, reconciliation, remote-admission, event-ingress, and\n  transport limits;\n- optional authenticated NATS configuration;\n- no bundled product connector code.\n\nAt startup, fleet configuration is all-or-none. The source requires a registry\nURL, an owner-only signing seed, and either explicit allowed hosts or trust in\nadmitted registry endpoints. Partial fleet configuration fails rather than\nstarting an ambiguous gateway.\n\nDo not add a second core replica until the first has completed runtime schema\nsetup, established its worker, and passed the deployment checks. Then add\nreplicas against the same logical runtime database, identity and policy\nrevision, registry, public origin, and NATS queue group where applicable.\n\n## Start admitted connector hosts\n\nFor each required connector boundary:\n\n1. Confirm the registry contains the intended active type and version,\n   tenant-owned instance, offline replica, disabled binding, artifact digest,\n   manifest digest, endpoint, DID, topology, and capacity.\n2. Mount the host database URL, signing seed, gateway and control-plane trust,\n   product configuration, provider credential files, and revision policy.\n3. Start one replica from the exact admitted artifact.\n4. Require host `/ready`, a current registry lease, and the expected manifest.\n5. Exercise deterministic and non-mutating provider checks.\n6. Enable one reviewed tenant capability binding at a new policy revision.\n7. Route one approved low-risk request through the public client path.\n8. Expand tenants, capabilities, replicas, or capacity only after the first\n   binding meets its observation window.\n\nThe common host exposes process health, readiness, metrics, manifest, and\nsigned native AIP execution. Host readiness includes a valid lease, durable\nstorage, connector health, and a non-draining state. It does not prove that the\nprovider will accept every operation or that the connector is qualified.\n\nWhen replacing a bundled connector, follow\n[Migrate bundled connectors to the fleet](migrate-bundled-connectors.md) so the\nold and new paths do not execute the same mutation.\n\n## Define readiness and traffic gates\n\nUse separate gates rather than one aggregate health check:\n\n| Gate | What it establishes | What it does not establish |\n|---|---|---|\n| Process health | Listener and process identity respond | Storage, workers, fleet capacity, or provider access |\n| Core readiness | Storage probe, runtime worker, required NATS listener, and required local modules are ready | A ready replica for every fleet capability |\n| Fleet summary | Registry maintenance state, leases, capacity, assignments, and pool signals are observable | Provider correctness or tenant authorization |\n| Host readiness | Lease, storage, connector probe, and drain state permit work | Live capability qualification |\n| Tenant discovery | Enabled binding exposes an admitted capability to one tenant | Successful provider execution |\n| Controlled action | Exact route and provider behavior succeed for one case | General availability or every capability |\n\nThe current `getaip-server` `/ready` response includes a fleet snapshot when fleet\nservices are installed, but fleet summary contents do not change the core\nreadiness Boolean. Gate connector traffic on tenant-visible bindings and ready\nreplica capacity in addition to core readiness.\n\nUse `/metrics` for bounded operational signals and `/ready` for traffic\nadmission. Do not make `/health` a load-balancer readiness check.\n\n## Roll out and verify the release\n\nUse a bounded canary sequence:\n\n1. Keep the previous artifact set and database backups available.\n2. Start one core canary with no new connector binding.\n3. Verify authentication rejection and acceptance paths for each published\n   profile.\n4. Read existing action, session, approval, transaction, receipt, and event\n   state without repeating provider work.\n5. Admit and start one connector host, then enable one low-risk tenant binding.\n6. Run an approved read and one controlled mutation with a unique idempotency\n   key where the contract requires it.\n7. Verify the route assignment, provider operation, stored result, event or\n   callback, receipt, and audit correlation.\n8. Exercise cancellation, timeout, retry, reconciliation, approval, and\n   compensation only where the manifest claims support.\n9. Restart one canary component and verify durable recovery without duplicate\n   provider effects.\n10. Expand replicas and traffic in measured stages.\n\nMonitor at least:\n\n- core and host readiness transitions;\n- runtime worker and optional NATS listener state;\n- registry maintenance failures, ready replicas, active assignments, and pool\n  pressure;\n- remote admission active, queued, byte, tenant, and rejection signals;\n- connector lease, heartbeat, drain, and offline transitions;\n- action queue age, retries, dead letters, callbacks, transactions, and\n  reconciliation;\n- provider rate limits, latency, errors, unknown outcomes, and webhook replay;\n- authentication, authorization, signature, and credential-revision failures.\n\nDefine alert thresholds from measured deployment objectives. Source defaults\nare safety bounds, not production capacity recommendations.\n\n## Stop on unsafe evidence\n\n| Observation | Immediate decision |\n|---|---|\n| Artifact, manifest, schema, or package digest differs | Stop rollout and identify the unreviewed input |\n| Database schema or migration checksum differs | Keep traffic off and restore the reviewed migration path |\n| Core ready but no eligible connector route exists | Keep that binding disabled and inspect registry and host state |\n| Host health passes but readiness fails | Inspect lease, storage, trust, connector health, and drain state |\n| A request reaches the wrong tenant or provider account | Disable the binding and rotate or correct credentials |\n| Provider mutation outcome is unknown | Reconcile by provider operation ID; do not retry through another path |\n| Duplicate provider effect appears | Pause mutations and preserve idempotency, assignment, and audit evidence |\n| Identity or authority directory is stale, expired, or revoked | Keep the affected edge closed and install a reviewed revision |\n| Backup restoration cannot meet the objective | Do not expand production traffic |\n\nDo not repair uncertainty by deleting assignments, idempotency records, replay\nclaims, transaction state, or provider operation IDs. These are the controls\nneeded to decide whether another side effect is permitted.\n\n## Roll back by ownership boundary\n\nRollback future traffic in the reverse order of admission:\n\n1. Pause new mutations for affected tenants and capabilities.\n2. Disable new or changed tenant bindings.\n3. Drain connector hosts and reconcile every active or unknown provider\n   operation under the replica that created it.\n4. Restore provider ingress only after pending host events and callbacks are\n   drained or retained.\n5. Mark connector replicas offline and stop the new host artifacts.\n6. Remove the canary core replica from traffic.\n7. Restore the previous core artifact and configuration against a compatible\n   runtime schema.\n8. Restore a database only when the rollback plan accounts for provider effects\n   and records created after the backup.\n9. Verify identity, state reads, routing, and one non-mutating operation before\n   resuming mutations.\n\nA binary rollback does not reverse a booking, message, update, provider job, or\nother external effect. Use the capability's governed compensation or business\nrecovery procedure when one exists.\n\nRetain the failed release unit, logs, traces, assignments, provider identifiers,\ndatabase revisions, and operator decisions for review. Revoke an artifact,\nsigning identity, or provider credential when the incident affects its\nintegrity; traffic removal alone does not invalidate it.\n\n## Record the accepted production boundary\n\nAccept the deployment only when the retained record identifies:\n\n- exact source, artifact, manifest, schema, configuration, trust, and provider\n  revisions;\n- topology, tenant, capability, connector, and account scope;\n- admission, conformance, security, recovery, restart, load, and live-provider\n  evidence that actually applies;\n- known exclusions and expired or missing evidence;\n- observed canary and rollout times;\n- recovery and rollback results;\n- the owner and expiry date of the production claim.\n\nDescribe each evidence level accurately. Implementation source, conformance,\nartifact qualification, deployment observation, and live-provider verification\nanswer different questions and cannot substitute for one another.\n\n## Related documentation\n\n- [Examples and reference deployments](examples-and-reference-deployments.md)\n- [Actions and sessions](../concepts/actions-and-sessions.md)\n- [Approvals and policy](../concepts/approvals-and-policy.md)\n- [Connector catalog](../connectors/README.md)\n",
    "text": "Deploy AIP in production\n\nUse this guide to design and stage a production AIP deployment. It is for\noperators who own the authenticated edge, product-neutral getaip-server replicas,\ndurable state, connector registry, lifecycle control plane, standalone\nconnector hosts, and release evidence.\n\nThe result is a bounded deployment candidate with explicit ownership, trust,\ntraffic gates, recovery, and rollback. Production readiness remains a claim\nabout an exact artifact set, configuration, topology, provider boundary, time,\nand retained evidence. A source revision, successful build, health response,\nor admission package does not establish that claim by itself.\n\nThis guide reflects source revision\nd7cce13d1d555644d04a4d73c66c95b113737635. It does not prescribe a cloud,\norchestrator, ingress controller, PostgreSQL service, NATS service, or secret\nmanager.\n\nUse this procedure for a complete deployment boundary\n\nApply this procedure after the selected AIP artifacts and connector contracts\nhave been reviewed. Complete Install AIP (../getting-started/installation.md)\nbefore planning the production environment.\n\nYou need authority to:\n• approve exact gateway, control-plane, host, and migration artifacts;\n• provision networks, identities, databases, keys, and secret references;\n• apply registry migrations, grants, admission packages, and tenant bindings;\n• change external routes, provider ingress, and client traffic;\n• take and restore backups;\n• pause mutations, drain workloads, and execute rollback;\n• retain qualification and deployment evidence.\n\nStop before deployment if the team cannot name one owner for identity,\ndatabase recovery, connector admission, provider credentials, ingress,\nincident response, and rollback. Shared infrastructure does not remove these\nownership boundaries.\n\nUse the product-neutral topology\n\nThe production boundary separates client-facing protocol handling from product\nexecution. getaip-server authenticates requests, owns AIP lifecycle state, discovers\ntenant-visible capabilities, and routes connector work. Standalone connector\nhosts own provider configuration, credentials, product calls, and authenticated\nproduct ingress.\n\nflowchart LR\n    Clients[\"Native AIP, MCP, and A2A clients\"] --> Edge[\"TLS and authenticated edge\"]\n    Edge --> Core[\"Product-neutral getaip-server replicas\"]\n    Core --> RuntimeDB[(\"Shared AIP runtime PostgreSQL\")]\n    Core -. optional .-> NATS[\"Authenticated NATS fabric\"]\n    Core --> Registry[(\"Connector registry data plane\")]\n    Identity[\"Identity and approval authorities\"] --> Core\n\n    Release[\"Release and admission operator\"] --> RegistryAdmin[\"Registry migration and admission\"]\n    RegistryAdmin --> Registry\n    Control[\"Signed connector lifecycle control plane\"] --> Registry\n\n    Core --> Hosts[\"Admitted standalone connector hosts\"]\n    Hosts --> Control\n    Hosts --> HostDB[(\"Host-owned durable state\")]\n    Hosts --> Products[\"Product APIs\"]\n    Products --> Ingress[\"Authenticated product ingress\"]\n    Ingress --> Hosts\n    Hosts --> Events[\"Signed central event and callback ingress\"]\n    Events --> Core\n\nKeep these roles distinct even when one managed PostgreSQL cluster or one\norchestrator runs several components. Do not embed product connector code or\nprovider credentials into the product-neutral getaip-server artifact.\n\nThe repository contains a connector-fleet Compose topology for controlled\ndevelopment and qualification. Its presence is evidence of a reference path,\nnot a production deployment template or a claim about any external provider.\n\nDefine the release unit and claim\n\nFreeze one deployment release record before provisioning. Include:\n\n| Release element | Identity to retain |\n\n| AIP source | Full commit and source-tree digest |\n| Gateway | Immutable artifact digest and AIP schema set |\n| Registry migration | Exact binary or migration source and required schema version |\n| Lifecycle control plane | Immutable artifact digest and signer DID |\n| Connector host | Product, source revision, immutable digest, and manifest digest |\n| Admission | Signed package ID, revision, digest, trust policy, and evidence expirations |\n| Configuration | Redacted revision and deployment-owned defaults |\n| Trust | Principal IDs, DIDs, trust domain, issuer, audience, and authority revisions |\n| Storage | Database identities, schema revisions, backup IDs, and restore procedure |\n| Provider | Account, workspace, application, endpoint set, and upstream revision |\n| Qualification | Exact topology, procedure, result, time, and retained artifacts |\n\nThe release unit may contain only the connector families the deployment needs.\nThe public source provides standalone hosts for Cal.diy, Hermes Agent,\nChatwoot, Dify, CrewAI, and Twenty, but evidence for one does not qualify the\nothers.\n\nDefine the intended production claim in one sentence. Name the tenants,\nprofiles, capabilities, connector versions, provider accounts, topology, and\nevidence window. Anything outside that sentence remains unsupported by this\ndeployment record.\n\nSegment networks and authority\n\nCreate separate network and credential boundaries for:\n\n| Zone | Permitted communication |\n\n| Public edge | Client TLS to the published AIP, MCP, or A2A origin |\n| Core service | Edge to getaip-server; getaip-server to runtime storage, registry data plane, and admitted hosts |\n| Registry administration | Short-lived migration and admission jobs to registry control credentials |\n| Lifecycle | Connector hosts to the signed lifecycle endpoint and lifecycle database role |\n| Connector host | Gateway and lifecycle traffic, host database, approved product endpoints, and central ingress |\n| Product ingress | Provider delivery to the product-specific authenticated host route |\n| Observability | Read-only collection of bounded health, readiness, metrics, logs, and traces |\n\nThe connector registry source supports independently permissioned control and\ndata pools. Production gateway and lifecycle processes connect through the\ndata-plane constructor, which verifies an already installed schema and retains\nno registry control pool. The reference grant policy limits gateway routing\nauthority and lifecycle replica authority to different table operations.\n\nKeep catalog migration and admission credentials in short-lived operator jobs.\nDo not mount them into getaip-server, the lifecycle service, or connector hosts.\n\nTerminate external TLS before the core listener and keep the listener on a\nprotected service network. A non-loopback getaip-server listener requires an external\nHTTPS origin. That origin must contain no credentials, path, query, or fragment.\nPlain HTTP is accepted only for explicit loopback development.\n\nProvision durable state by owner\n\nTreat runtime, registry, and connector-host state as separate recovery domains:\n\n| State owner | Durable content | Access pattern |\n\n| Core runtime | Actions, results, sessions, events, approvals, transactions, callbacks, receipts, replay, and idempotency | Shared by all replicas in one logical getaip-server deployment |\n| Connector registry | Types, versions, manifests, instances, replicas, bindings, assignments, admission counters, and journal | Admin job writes catalog; gateway routes; lifecycle service updates replica state |\n| Connector host | Provider-facing runtime, checkpoints, replay, outbox, and product-specific durable state | Owned by the admitted host boundary |\n\nUse PostgreSQL for a clustered core deployment. PostgresRuntimeStore installs\nand verifies immutable schema migrations at connection time, then supplies the\ncomplete runtime store set. A file-backed storagedir is a single-host\nboundary and is not a clustered scheduler or shared failover store.\n\nInstall connector-registry migrations with administrative credentials before\nstarting data-plane services. The data-plane connection refuses a schema whose\nversion differs from the required version. Reconcile least-privilege grants\nafter migration so removed permissions do not survive from an older release.\n\nGive each logical state owner a separately restorable database and credential\nscope. One PostgreSQL service may host them, but do not point a connector host\nat the core runtime or registry database as an undocumented shortcut.\n\nBefore rollout:\n1. take named, time-stamped backups;\n2. record the database and schema revision represented by each backup;\n3. verify restoration in an isolated environment;\n4. measure recovery point and recovery time against the deployment objective;\n5. confirm that restoration preserves leases, fences, idempotency,\n   transactions, replay, assignments, and provider operation references.\n\nA database connection check is not a recovery test. Use controlled in-flight\nand unknown-outcome cases without affecting production provider data.\n\nEstablish identities and secrets\n\nFollow Identity and trust (../concepts/identity-and-trust.md) to assign one\nstable identity to every security boundary. At minimum, record:\n• external client issuer, subject, audience, scopes, and tenant mapping;\n• getaip-server service principal, trust domain, signing DID, and trusted client DIDs;\n• MCP protected-resource identifier, authorization server, introspection\n  identity, audience, required scopes, and browser origins when MCP is public;\n• connector control-plane principal and signing DID;\n• each host principal, signing DID, tenant, membership, and provider account;\n• release-package and seven evidence-role trust roots;\n• approval authority and trusted identity directory revisions.\n\nThe pinned daemon defaults to deny-all identity and approval resolvers when no\ndeployment-owned directory is installed. Do not replace that behavior with\ncaller-supplied identity in action input or metadata.\n\nStore database URLs, bearer tokens, OAuth client secrets, signing seeds,\nprovider credentials, NATS passwords, and private keys in owner-controlled,\nbounded files or an equivalent mounted secret boundary. Keep only opaque secret\nprovider and credential revision references in registry and configuration\nrecords.\n\nSeparate these signing roles:\n• external client request identity;\n• gateway response, callback, and fleet dispatch identity;\n• lifecycle control-plane response identity;\n• connector-host request and event identity;\n• admission-package release authority;\n• each independent supply-chain evidence authority.\n\nDo not reuse one seed merely because the components share a trust domain.\n\nConfigure the published profiles\n\nExpose only the profiles that the deployment claim includes. The\nprofiles, transports, and connectors (../concepts/profiles-and-connectors.md)\npage defines their protocol roles.\n\nFor native HTTP:\n• require signed envelopes, or configure a server-owned bearer identity at the\n  trusted edge;\n• bind tenant and scopes after authentication;\n• publish an HTTPS origin;\n• bound request bodies, responses, streams, queues, and callbacks.\n\nFor MCP over HTTP:\n• publish protected-resource metadata;\n• advertise the accepted authorization server and resource identifier;\n• verify token issuer, audience, activity, and required scopes through the\n  configured verifier;\n• allow only exact browser origins when browser access is required;\n• keep stdio as a local process boundary rather than a public network edge.\n\nFor A2A:\n• publish the agent card from the external HTTPS origin;\n• protect task operations through the same trusted AIP identity boundary;\n• encrypt stored push credentials and restrict callback destinations.\n\nFor NATS, when selected:\n• configure the server URL, trust domain, service, version, and queue group;\n• supply username and owner-controlled password file together;\n• enforce account, subject, and TLS policy outside getaip-server;\n• include the NATS listener in the readiness and failure plan.\n\nDo not expose every profile merely because the binary implements it. Fewer\npublished surfaces reduce authentication, compatibility, and incident scope.\n\nInstall registry and lifecycle services\n\nUse this order:\n1. Install and verify the registry schema under the short-lived admin role.\n2. Reconcile gateway data-plane and lifecycle grants.\n3. Verify that data-plane credentials can read the schema version and only the\n   records their role requires.\n4. Start the connector lifecycle service behind its TLS boundary.\n5. Record its signer DID and distribute that public identity to admitted hosts.\n6. Verify lifecycle /health, /ready, and bounded /metrics separately.\n7. Plan each signed connector admission package without writing.\n8. Apply only the exact reviewed package revision and digest.\n\nThe lifecycle service exposes one signed control route for register, heartbeat,\ndrain, and offline commands. It deliberately retains no catalog-administration\npool. A host must already have a pre-provisioned replica identity; registration\ndoes not create an arbitrary connector or tenant binding.\n\nKeep tenant capability bindings disabled until the matching host artifact is\nrunning, ready, and verified.\n\nStart the core before product traffic\n\nStart one getaip-server replica with:\n• the exact gateway artifact and HTTPS public origin;\n• shared PostgreSQL runtime credentials;\n• trusted signer, identity, approval, and profile policy revisions;\n• connector-registry data-plane credentials;\n• a fleet signing seed and host trust policy;\n• bounded callback, reconciliation, remote-admission, event-ingress, and\n  transport limits;\n• optional authenticated NATS configuration;\n• no bundled product connector code.\n\nAt startup, fleet configuration is all-or-none. The source requires a registry\nURL, an owner-only signing seed, and either explicit allowed hosts or trust in\nadmitted registry endpoints. Partial fleet configuration fails rather than\nstarting an ambiguous gateway.\n\nDo not add a second core replica until the first has completed runtime schema\nsetup, established its worker, and passed the deployment checks. Then add\nreplicas against the same logical runtime database, identity and policy\nrevision, registry, public origin, and NATS queue group where applicable.\n\nStart admitted connector hosts\n\nFor each required connector boundary:\n1. Confirm the registry contains the intended active type and version,\n   tenant-owned instance, offline replica, disabled binding, artifact digest,\n   manifest digest, endpoint, DID, topology, and capacity.\n2. Mount the host database URL, signing seed, gateway and control-plane trust,\n   product configuration, provider credential files, and revision policy.\n3. Start one replica from the exact admitted artifact.\n4. Require host /ready, a current registry lease, and the expected manifest.\n5. Exercise deterministic and non-mutating provider checks.\n6. Enable one reviewed tenant capability binding at a new policy revision.\n7. Route one approved low-risk request through the public client path.\n8. Expand tenants, capabilities, replicas, or capacity only after the first\n   binding meets its observation window.\n\nThe common host exposes process health, readiness, metrics, manifest, and\nsigned native AIP execution. Host readiness includes a valid lease, durable\nstorage, connector health, and a non-draining state. It does not prove that the\nprovider will accept every operation or that the connector is qualified.\n\nWhen replacing a bundled connector, follow\nMigrate bundled connectors to the fleet (migrate-bundled-connectors.md) so the\nold and new paths do not execute the same mutation.\n\nDefine readiness and traffic gates\n\nUse separate gates rather than one aggregate health check:\n\n| Gate | What it establishes | What it does not establish |\n\n| Process health | Listener and process identity respond | Storage, workers, fleet capacity, or provider access |\n| Core readiness | Storage probe, runtime worker, required NATS listener, and required local modules are ready | A ready replica for every fleet capability |\n| Fleet summary | Registry maintenance state, leases, capacity, assignments, and pool signals are observable | Provider correctness or tenant authorization |\n| Host readiness | Lease, storage, connector probe, and drain state permit work | Live capability qualification |\n| Tenant discovery | Enabled binding exposes an admitted capability to one tenant | Successful provider execution |\n| Controlled action | Exact route and provider behavior succeed for one case | General availability or every capability |\n\nThe current getaip-server /ready response includes a fleet snapshot when fleet\nservices are installed, but fleet summary contents do not change the core\nreadiness Boolean. Gate connector traffic on tenant-visible bindings and ready\nreplica capacity in addition to core readiness.\n\nUse /metrics for bounded operational signals and /ready for traffic\nadmission. Do not make /health a load-balancer readiness check.\n\nRoll out and verify the release\n\nUse a bounded canary sequence:\n1. Keep the previous artifact set and database backups available.\n2. Start one core canary with no new connector binding.\n3. Verify authentication rejection and acceptance paths for each published\n   profile.\n4. Read existing action, session, approval, transaction, receipt, and event\n   state without repeating provider work.\n5. Admit and start one connector host, then enable one low-risk tenant binding.\n6. Run an approved read and one controlled mutation with a unique idempotency\n   key where the contract requires it.\n7. Verify the route assignment, provider operation, stored result, event or\n   callback, receipt, and audit correlation.\n8. Exercise cancellation, timeout, retry, reconciliation, approval, and\n   compensation only where the manifest claims support.\n9. Restart one canary component and verify durable recovery without duplicate\n   provider effects.\n10. Expand replicas and traffic in measured stages.\n\nMonitor at least:\n• core and host readiness transitions;\n• runtime worker and optional NATS listener state;\n• registry maintenance failures, ready replicas, active assignments, and pool\n  pressure;\n• remote admission active, queued, byte, tenant, and rejection signals;\n• connector lease, heartbeat, drain, and offline transitions;\n• action queue age, retries, dead letters, callbacks, transactions, and\n  reconciliation;\n• provider rate limits, latency, errors, unknown outcomes, and webhook replay;\n• authentication, authorization, signature, and credential-revision failures.\n\nDefine alert thresholds from measured deployment objectives. Source defaults\nare safety bounds, not production capacity recommendations.\n\nStop on unsafe evidence\n\n| Observation | Immediate decision |\n\n| Artifact, manifest, schema, or package digest differs | Stop rollout and identify the unreviewed input |\n| Database schema or migration checksum differs | Keep traffic off and restore the reviewed migration path |\n| Core ready but no eligible connector route exists | Keep that binding disabled and inspect registry and host state |\n| Host health passes but readiness fails | Inspect lease, storage, trust, connector health, and drain state |\n| A request reaches the wrong tenant or provider account | Disable the binding and rotate or correct credentials |\n| Provider mutation outcome is unknown | Reconcile by provider operation ID; do not retry through another path |\n| Duplicate provider effect appears | Pause mutations and preserve idempotency, assignment, and audit evidence |\n| Identity or authority directory is stale, expired, or revoked | Keep the affected edge closed and install a reviewed revision |\n| Backup restoration cannot meet the objective | Do not expand production traffic |\n\nDo not repair uncertainty by deleting assignments, idempotency records, replay\nclaims, transaction state, or provider operation IDs. These are the controls\nneeded to decide whether another side effect is permitted.\n\nRoll back by ownership boundary\n\nRollback future traffic in the reverse order of admission:\n1. Pause new mutations for affected tenants and capabilities.\n2. Disable new or changed tenant bindings.\n3. Drain connector hosts and reconcile every active or unknown provider\n   operation under the replica that created it.\n4. Restore provider ingress only after pending host events and callbacks are\n   drained or retained.\n5. Mark connector replicas offline and stop the new host artifacts.\n6. Remove the canary core replica from traffic.\n7. Restore the previous core artifact and configuration against a compatible\n   runtime schema.\n8. Restore a database only when the rollback plan accounts for provider effects\n   and records created after the backup.\n9. Verify identity, state reads, routing, and one non-mutating operation before\n   resuming mutations.\n\nA binary rollback does not reverse a booking, message, update, provider job, or\nother external effect. Use the capability's governed compensation or business\nrecovery procedure when one exists.\n\nRetain the failed release unit, logs, traces, assignments, provider identifiers,\ndatabase revisions, and operator decisions for review. Revoke an artifact,\nsigning identity, or provider credential when the incident affects its\nintegrity; traffic removal alone does not invalidate it.\n\nRecord the accepted production boundary\n\nAccept the deployment only when the retained record identifies:\n• exact source, artifact, manifest, schema, configuration, trust, and provider\n  revisions;\n• topology, tenant, capability, connector, and account scope;\n• admission, conformance, security, recovery, restart, load, and live-provider\n  evidence that actually applies;\n• known exclusions and expired or missing evidence;\n• observed canary and rollout times;\n• recovery and rollback results;\n• the owner and expiry date of the production claim.\n\nDescribe each evidence level accurately. Implementation source, conformance,\nartifact qualification, deployment observation, and live-provider verification\nanswer different questions and cannot substitute for one another.\n\nRelated documentation\n• Examples and reference deployments (examples-and-reference-deployments.md)\n• Actions and sessions (../concepts/actions-and-sessions.md)\n• Approvals and policy (../concepts/approvals-and-policy.md)\n• Connector catalog (../connectors/README.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "c8a4f1fc8260d3b3894f47d1b1b02f940f1af96b97645ad1079f086b7075d1d8"
  }
}