{
  "schemaVersion": "1.0",
  "title": "Deploy the CrewAI connector",
  "description": "Use this procedure to deploy one CrewAI connector instance as two separately identified processes. The Rust host owns AIP identity and lifecycle. The Python sidecar owns CrewAI execution and its durable job journal.",
  "canonical": "https://getaip.org/docs/connectors/crewai/operations/deployment",
  "route": "/docs/connectors/crewai/operations/deployment",
  "source": "docs/connectors/crewai/operations/deployment.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Connectors",
  "documentType": "Connector",
  "language": "en",
  "downloads": {
    "md": "/docs/download/connectors/crewai/operations/deployment.md",
    "txt": "/docs/download/connectors/crewai/operations/deployment.txt",
    "json": "/docs/download/connectors/crewai/operations/deployment.json",
    "pdf": "/docs/download/connectors/crewai/operations/deployment.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Deploy the CrewAI connector\ndescription: >-\n  Deploy one CrewAI connector instance with separate host and sidecar artifacts,\n  private routing, durable state, and explicit replica identity\nkind: how-to\naudience: operator\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\nconnector: crewai\naliases:\n  - CrewAI connector deployment\n  - Deploy aip-host-crewai\n  - Deploy the CrewAI sidecar\n---\n\n# Deploy the CrewAI connector\n\nUse this procedure to deploy one CrewAI connector instance as two separately\nidentified processes. The Rust host owns AIP identity and lifecycle. The Python\nsidecar owns CrewAI execution and its durable job journal.\n\nThe reviewed Compose file is a qualification topology, not a production\nmanifest. Adapt its security and dependency boundaries to the target platform\nwithout copying qualification identities or placeholder digests.\n\n## Fix the deployment unit\n\nOne logical connector instance contains these components:\n\n| Component | Reviewed artifact | Listener | Durable ownership |\n|---|---|---|---|\n| Rust host | `getaip/aip-host-crewai` | Native AIP on `8081` behind ingress | PostgreSQL runtime store through an owner-controlled URL file |\n| Python sidecar | `getaip/aip-crewai-sidecar` | Private HTTP on `8090` | CrewAI home, training directory, and `runs.json` on one dedicated volume |\n| Connector registry | Admitted CrewAI type, version, instance, and replica | Control-plane boundary | Admission package, assignments, leases, and lifecycle state |\n| Private ingress | Deployment-owned TLS route | Host and sidecar service names | Trust roots and routing configuration |\n\nDo not combine the processes into one artifact identity. Their source inputs,\ndependencies, image digests, credentials, and state have different review and\nrollback boundaries.\n\n## 1. Freeze both artifacts\n\nRetain an immutable digest, provenance, software bill of materials, source\nrevision, and vulnerability decision for each image.\n\nThe reviewed generic host Dockerfile builds `aip-host-crewai` with locked Cargo\ndependencies. Its runtime image uses UID and GID `10001`, exposes `8081`, and\ncontains the common binary as `aip-connector-host`.\n\nThe default sidecar Dockerfile uses Python 3.13 and a frozen `uv` lockfile. It\nlabels the CrewAI package set as `1.15.5`, runs as UID and GID `10001`, and\nexposes `8090`.\n\nReject mutable tags as deployment identity. OCI source and revision labels are\nuseful metadata but do not prove the bytes behind a registry digest.\n\n## 2. Admit the host artifact\n\nCreate or verify the immutable connector type and version before starting the\nreplica. Bind the admitted version to the exact host artifact digest and\nrequired evidence package.\n\nProvision unique values for:\n\n- connector instance ID;\n- connector replica ID;\n- tenant and membership IDs;\n- external CrewAI account reference;\n- artifact digest and configuration revision;\n- region, zone, capacity class, and trust domain.\n\nEach replacement artifact requires a version and assignment decision. Do not\nreuse a replica ID for two simultaneously running processes.\n\n## 3. Provision owner-controlled files\n\nMount these host inputs as read-only files:\n\n| Input | Purpose |\n|---|---|\n| PostgreSQL URL | Durable AIP runtime and replay state |\n| Ed25519 signing seed | Native AIP response and lifecycle identity |\n| Sidecar Bearer token | Private host-to-sidecar authentication |\n| Crew descriptor array | Admitted crews and exact operation allowlists |\n| Credential revision policy | Reloadable fail-closed provider authority |\n| Gateway and control-plane DIDs | Verification of signed fleet traffic |\n| Private CA certificate | TLS validation for private deployment routes |\n\nUse separate credentials for PostgreSQL, AIP signing, sidecar authentication,\nand any model or tool provider. Rotation of one authority must not silently\nreplace another.\n\nThe host accepts one to 1,000 crew descriptors and a sidecar token file up to\n16 KiB. File readers enforce bounded, owner-controlled inputs; preserve those\ncontrols in secret projection and rotation workflows.\n\n## 4. Prepare the sidecar state\n\nCreate one protected writable volume for:\n\n```text\n/var/lib/aip-crewai/\n├── runs.json\n├── runs.json.lock\n├── training/\n├── crewai/\n└── home/\n```\n\nThe journal and lock file appear after startup. The default image places\nCrewAI storage and `HOME` under the same volume, preserving its local\ncredential-encryption material across restarts.\n\nGive the sidecar process ownership of the directory. Do not mount the same\nwritable state path into a second active sidecar. The nonblocking journal lock\nis a startup fence, not a shared-volume scaling mechanism.\n\n## 5. Isolate the sidecar route\n\nPlace the sidecar on a private network reachable by its paired Rust host and\nthe deployment health system. Do not publish port `8090` to tenants or the\npublic AIP edge.\n\nTerminate or route private TLS so the host can use an `https` sidecar URL. The\nRust connector rejects non-loopback HTTP and disables redirects.\n\nThe sidecar itself provides Bearer authentication, not TLS or AIP tenant\nidentity. Configure the private ingress to preserve the fixed route and avoid\nforwarding untrusted proxy identity.\n\n## 6. Start and verify the sidecar\n\nConfigure at least:\n\n- registry module reference;\n- Bearer token file;\n- state file;\n- allowed startable operations;\n- concurrency and journal bounds;\n- training directory when `train` is enabled.\n\nKeep the container filesystem read-only, drop Linux capabilities, enable\n`no-new-privileges`, and provide a bounded no-execute temporary filesystem.\n\nThe reviewed healthcheck reads the Bearer token file and calls authenticated\n`GET /health` on loopback. Require HTTP `200`, the expected crew IDs, durable\njournal status, enabled operations, and expected capacity values.\n\nHealth at this point proves sidecar startup and local configuration. It does\nnot prove model credentials, tool reachability, or successful crew execution.\n\n## 7. Start the Rust host\n\nStart the host only after:\n\n1. the connector version is admitted;\n2. PostgreSQL and the lifecycle control plane are ready;\n3. gateway and private TLS trust roots are available;\n4. the sidecar passes authenticated health;\n5. all required files and immutable identities are mounted.\n\nSet the sidecar URL, sidecar token file, and crew descriptor file together with\nthe common connector-host configuration. The reviewed host binds `0.0.0.0:8081`\nbehind ingress and publishes a distinct HTTPS AIP endpoint.\n\nThe host discovers capabilities from the descriptor array during preparation.\nConfiguration or discovery failure prevents registration and readiness.\n\n## 8. Gate traffic on host readiness\n\nProbe `/ready` for routing eligibility. Keep `/health` for process health and\ndiagnosis. The reviewed qualification topology routes only after dependencies\nand the host readiness probe pass.\n\nVerify the registered type, version, instance, replica, artifact digest,\ntenant, external account, zone, credential revision, lease, and endpoint.\nCompare discovered CrewAI capabilities with the admitted manifest.\n\nSend no tenant traffic until the registry assignment targets this exact ready\nreplica. Sidecar health alone is insufficient for fleet routing.\n\n## 9. Scale with independent instances\n\nDo not add a second sidecar replica against the first sidecar's journal.\nInstead, create another connector instance with:\n\n- its own instance and replica identities;\n- its own host runtime state and signing seed;\n- an independent sidecar state volume and token;\n- an explicit crew and provider-account assignment;\n- its own admitted route weight and lifecycle state.\n\nThis model prevents two Python processes from claiming one durable job\nnamespace. Fleet routing supplies horizontal capacity above the instance\nboundary.\n\n## 10. Replace or roll back safely\n\nDrain the host through the lifecycle control plane before removal. Stop new\nassignments, preserve runtime and sidecar state, and wait only within the\nconfigured drain deadline.\n\nReconcile every non-terminal or uncertain Action before replacing its sidecar\nstate. A new empty volume removes the old request fence and can permit duplicate\nprovider work under a newly dispatched Action.\n\nFor rollback, deploy the previously admitted immutable host and sidecar pair\nwith compatible configuration. Use a new replica identity, verify both health\nboundaries, then move assignments deliberately.\n\nRetain the retired image digests, journal, events, host checkpoints, registry\nhistory, and operator decision until the replay and incident-retention windows\nclose.\n\n## Verify the deployment\n\nAccept the deployment only when:\n\n- both running image digests match retained provenance;\n- the sidecar route is private and authenticated;\n- exactly one process owns each sidecar journal;\n- the expected crews and operation policy appear in health;\n- the Rust host reports healthy and ready separately;\n- registry identity matches the running replica and artifact;\n- the host advertises only descriptor-approved capabilities;\n- one bounded qualification Action completes with retained evidence;\n- drain and rollback procedures preserve the original Action fence.\n\n## Related documentation\n\n- [CrewAI connector overview](../README.md)\n- [CrewAI connector configuration](../reference/configuration.md)\n- [CrewAI sidecar contract and lockfile](../reference/sidecar-contract-and-lockfile.md)\n- [CrewAI idempotency, cancellation, and process fencing](../reference/idempotency-cancellation-and-process-fencing.md)\n- [Deploy the connector fleet](../../../guides/deploy-connector-fleet.md)\n",
    "text": "Deploy the CrewAI connector\n\nUse this procedure to deploy one CrewAI connector instance as two separately\nidentified processes. The Rust host owns AIP identity and lifecycle. The Python\nsidecar owns CrewAI execution and its durable job journal.\n\nThe reviewed Compose file is a qualification topology, not a production\nmanifest. Adapt its security and dependency boundaries to the target platform\nwithout copying qualification identities or placeholder digests.\n\nFix the deployment unit\n\nOne logical connector instance contains these components:\n\n| Component | Reviewed artifact | Listener | Durable ownership |\n\n| Rust host | getaip/aip-host-crewai | Native AIP on 8081 behind ingress | PostgreSQL runtime store through an owner-controlled URL file |\n| Python sidecar | getaip/aip-crewai-sidecar | Private HTTP on 8090 | CrewAI home, training directory, and runs.json on one dedicated volume |\n| Connector registry | Admitted CrewAI type, version, instance, and replica | Control-plane boundary | Admission package, assignments, leases, and lifecycle state |\n| Private ingress | Deployment-owned TLS route | Host and sidecar service names | Trust roots and routing configuration |\n\nDo not combine the processes into one artifact identity. Their source inputs,\ndependencies, image digests, credentials, and state have different review and\nrollback boundaries.\n1. Freeze both artifacts\n\nRetain an immutable digest, provenance, software bill of materials, source\nrevision, and vulnerability decision for each image.\n\nThe reviewed generic host Dockerfile builds aip-host-crewai with locked Cargo\ndependencies. Its runtime image uses UID and GID 10001, exposes 8081, and\ncontains the common binary as aip-connector-host.\n\nThe default sidecar Dockerfile uses Python 3.13 and a frozen uv lockfile. It\nlabels the CrewAI package set as 1.15.5, runs as UID and GID 10001, and\nexposes 8090.\n\nReject mutable tags as deployment identity. OCI source and revision labels are\nuseful metadata but do not prove the bytes behind a registry digest.\n2. Admit the host artifact\n\nCreate or verify the immutable connector type and version before starting the\nreplica. Bind the admitted version to the exact host artifact digest and\nrequired evidence package.\n\nProvision unique values for:\n• connector instance ID;\n• connector replica ID;\n• tenant and membership IDs;\n• external CrewAI account reference;\n• artifact digest and configuration revision;\n• region, zone, capacity class, and trust domain.\n\nEach replacement artifact requires a version and assignment decision. Do not\nreuse a replica ID for two simultaneously running processes.\n3. Provision owner-controlled files\n\nMount these host inputs as read-only files:\n\n| Input | Purpose |\n\n| PostgreSQL URL | Durable AIP runtime and replay state |\n| Ed25519 signing seed | Native AIP response and lifecycle identity |\n| Sidecar Bearer token | Private host-to-sidecar authentication |\n| Crew descriptor array | Admitted crews and exact operation allowlists |\n| Credential revision policy | Reloadable fail-closed provider authority |\n| Gateway and control-plane DIDs | Verification of signed fleet traffic |\n| Private CA certificate | TLS validation for private deployment routes |\n\nUse separate credentials for PostgreSQL, AIP signing, sidecar authentication,\nand any model or tool provider. Rotation of one authority must not silently\nreplace another.\n\nThe host accepts one to 1,000 crew descriptors and a sidecar token file up to\n16 KiB. File readers enforce bounded, owner-controlled inputs; preserve those\ncontrols in secret projection and rotation workflows.\n4. Prepare the sidecar state\n\nCreate one protected writable volume for:\n\n/var/lib/aip-crewai/\n├── runs.json\n├── runs.json.lock\n├── training/\n├── crewai/\n└── home/\n\nThe journal and lock file appear after startup. The default image places\nCrewAI storage and HOME under the same volume, preserving its local\ncredential-encryption material across restarts.\n\nGive the sidecar process ownership of the directory. Do not mount the same\nwritable state path into a second active sidecar. The nonblocking journal lock\nis a startup fence, not a shared-volume scaling mechanism.\n5. Isolate the sidecar route\n\nPlace the sidecar on a private network reachable by its paired Rust host and\nthe deployment health system. Do not publish port 8090 to tenants or the\npublic AIP edge.\n\nTerminate or route private TLS so the host can use an https sidecar URL. The\nRust connector rejects non-loopback HTTP and disables redirects.\n\nThe sidecar itself provides Bearer authentication, not TLS or AIP tenant\nidentity. Configure the private ingress to preserve the fixed route and avoid\nforwarding untrusted proxy identity.\n6. Start and verify the sidecar\n\nConfigure at least:\n• registry module reference;\n• Bearer token file;\n• state file;\n• allowed startable operations;\n• concurrency and journal bounds;\n• training directory when train is enabled.\n\nKeep the container filesystem read-only, drop Linux capabilities, enable\nno-new-privileges, and provide a bounded no-execute temporary filesystem.\n\nThe reviewed healthcheck reads the Bearer token file and calls authenticated\nGET /health on loopback. Require HTTP 200, the expected crew IDs, durable\njournal status, enabled operations, and expected capacity values.\n\nHealth at this point proves sidecar startup and local configuration. It does\nnot prove model credentials, tool reachability, or successful crew execution.\n7. Start the Rust host\n\nStart the host only after:\n1. the connector version is admitted;\n2. PostgreSQL and the lifecycle control plane are ready;\n3. gateway and private TLS trust roots are available;\n4. the sidecar passes authenticated health;\n5. all required files and immutable identities are mounted.\n\nSet the sidecar URL, sidecar token file, and crew descriptor file together with\nthe common connector-host configuration. The reviewed host binds 0.0.0.0:8081\nbehind ingress and publishes a distinct HTTPS AIP endpoint.\n\nThe host discovers capabilities from the descriptor array during preparation.\nConfiguration or discovery failure prevents registration and readiness.\n8. Gate traffic on host readiness\n\nProbe /ready for routing eligibility. Keep /health for process health and\ndiagnosis. The reviewed qualification topology routes only after dependencies\nand the host readiness probe pass.\n\nVerify the registered type, version, instance, replica, artifact digest,\ntenant, external account, zone, credential revision, lease, and endpoint.\nCompare discovered CrewAI capabilities with the admitted manifest.\n\nSend no tenant traffic until the registry assignment targets this exact ready\nreplica. Sidecar health alone is insufficient for fleet routing.\n9. Scale with independent instances\n\nDo not add a second sidecar replica against the first sidecar's journal.\nInstead, create another connector instance with:\n• its own instance and replica identities;\n• its own host runtime state and signing seed;\n• an independent sidecar state volume and token;\n• an explicit crew and provider-account assignment;\n• its own admitted route weight and lifecycle state.\n\nThis model prevents two Python processes from claiming one durable job\nnamespace. Fleet routing supplies horizontal capacity above the instance\nboundary.\n10. Replace or roll back safely\n\nDrain the host through the lifecycle control plane before removal. Stop new\nassignments, preserve runtime and sidecar state, and wait only within the\nconfigured drain deadline.\n\nReconcile every non-terminal or uncertain Action before replacing its sidecar\nstate. A new empty volume removes the old request fence and can permit duplicate\nprovider work under a newly dispatched Action.\n\nFor rollback, deploy the previously admitted immutable host and sidecar pair\nwith compatible configuration. Use a new replica identity, verify both health\nboundaries, then move assignments deliberately.\n\nRetain the retired image digests, journal, events, host checkpoints, registry\nhistory, and operator decision until the replay and incident-retention windows\nclose.\n\nVerify the deployment\n\nAccept the deployment only when:\n• both running image digests match retained provenance;\n• the sidecar route is private and authenticated;\n• exactly one process owns each sidecar journal;\n• the expected crews and operation policy appear in health;\n• the Rust host reports healthy and ready separately;\n• registry identity matches the running replica and artifact;\n• the host advertises only descriptor-approved capabilities;\n• one bounded qualification Action completes with retained evidence;\n• drain and rollback procedures preserve the original Action fence.\n\nRelated documentation\n• CrewAI connector overview (../README.md)\n• CrewAI connector configuration (../reference/configuration.md)\n• CrewAI sidecar contract and lockfile (../reference/sidecar-contract-and-lockfile.md)\n• CrewAI idempotency, cancellation, and process fencing (../reference/idempotency-cancellation-and-process-fencing.md)\n• Deploy the connector fleet (../../../guides/deploy-connector-fleet.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "648320d6150a073f5f7ab181a685a78bb64298438097476baaea8d226a63a1cf"
  }
}