CrewAI connector configuration

This reference describes the product settings accepted by aip-host-crewai and aip-crewai-sidecar at the reviewed source revision. A complete deployment combines them with the shared connector-host identity, PostgreSQL, routing, signing, lifecycle, and optional stream-callback settings.

All CrewAI product settings are read when their process starts. Only the shared non-secret credential-revision policy is re-read before provider side effects.

Configuration identity

The sidecar artifact also pins FastAPI, Pydantic, Uvicorn, the Python base image, the package installer, and the complete Python lockfile.

Configure the Rust host

The source rejects credentials, a query, and a fragment. HTTPS is required except for explicit loopback HTTP, and redirects are disabled.

A path prefix is accepted but discarded by absolute /health and /jobs joins. Configure an origin-only value to keep reviewed and effective routes identical.

The host reads a regular owner-only file with a 16 KiB ceiling, trims surrounding ASCII whitespace, and requires non-empty UTF-8. The connector rejects an empty value or any control character; it does not reject an interior plain space.

AIP_CREWAI_MAX_RESPONSE_BYTES accepts 1 through 268435456. The same configured value bounds one blocking sidecar response and the accumulated bytes of one event stream.

Configure admitted crew descriptors

The descriptor file is a JSON array of one to 1,000 entries and may not exceed 4 MiB.

[
  {
    "id": "support-primary",
    "name": "Support primary",
    "description": "Reviewed support workflow",
    "allowed_operations": [
      "run",
      "status",
      "events",
      "cancel"
    ]
  }
]

The 4 MiB file limit remains the combined payload ceiling. Apply a stricter deployment schema before descriptor text reaches a public manifest.

The ten accepted operation names are run, status, events, cancel, batch_run, replay, train, test, knowledge_query, and memory_reset.

Configure the sidecar listener and authentication

The bearer file must be a regular non-symlink with no group or world permission bits. The sidecar checks the inspected and opened inode and uses constant-time comparison for the complete Bearer header.

The controlled fleet places both components on a private network and uses one shared mounted token file. It still treats the host and sidecar as separate process identities.

Configure the registry and operation set

Registry values are zero-argument factories or cloneable Crew instances. The sidecar creates a new result or deep clone for every job.

The allowed sidecar set can contain:

run,batch_run,replay,train,test,knowledge_query,memory_reset

status, events, and cancel are control routes and appear in sidecar health automatically. Supplying a control operation in the environment value is invalid.

The host descriptor may be narrower than sidecar policy. Host readiness fails if any descriptor operation is absent from the authenticated sidecar health response.

Configure durable state

The journal parent must be a non-symlink directory with no group or world write bit. The sidecar holds an exclusive non-blocking lock in a regular 0600 companion file.

An existing journal must be a regular non-symlink 0600 file within the configured byte limit. Restore rejects duplicate Action IDs, excessive runs, excessive events, and oversized events.

State writes use a same-directory temporary file, file sync, atomic replace, and directory sync. A configured maximum is a retention and integrity bound, not permission to delete records inside the AIP replay window.

The default product image places CREWAI_STORAGE_DIR and HOME under the sidecar volume. Persist that volume with the journal; losing the durable home can make locally encrypted provider credentials unreadable.

The optional source-overlay Dockerfile does not set those two paths at this revision. A deployment using it must configure and persist an equivalent CrewAI home explicitly.

Configure execution and training

The training directory is created with owner access when absent. It must be a non-symlink directory and must not be group- or world-writable.

The Action’s timeout_ms accepts 1 through 3600000. Omission uses the sidecar default of 600000 milliseconds.

Telemetry defaults are set before the registry loads:

CREWAI_DISABLE_TELEMETRY=true
CREWAI_TRACING_ENABLED=false
OTEL_SDK_DISABLED=true

An explicit deployment environment can override these existing variables. Review content and destination exposure before doing so.

Apply relevant shared host settings

The global host reference owns the exhaustive common matrix. These groups are required for CrewAI behavior.

Identity and route

An optional external-account ID and system must appear together. The reviewed host does not compare that metadata automatically with a crew descriptor.

PostgreSQL, signing, and lifecycle

Shared credential ID, issuer, scopes, revision, and revision-policy settings are optional as one complete unit. They fence route authorization but do not replace sidecar or CrewAI provider credentials.

Stream callback

Configure callback behavior for the selected gateway topology. The product settings do not make a callback mandatory for blocking operations.

Use the effective limits

The effective ceiling is the smallest applicable bound. Raising the host response limit does not enlarge the input, sidecar output, event, native envelope, or journal limits.

The reviewed Rust client has no explicit total HTTP request deadline. The sidecar’s operation timeout bounds its wait for a job, but it does not replace a transport-wide client deadline.

Understand readiness

The Rust connector sends an authenticated GET /health. It reports ready only when the response has all of these properties:

• status is ready;
• durable_journal is true;
• every descriptor crew ID appears in crews;
• every descriptor operation appears in operations.

Common host readiness also requires PostgreSQL, a valid lease, correct lifecycle state, and other shared controls.

Readiness does not run a crew, model, tool, training task, evaluator, knowledge query, memory reset, cancellation race, or event recovery sequence.

Know startup and reload ownership

Change startup-owned values through a controlled replacement. Editing a mounted file does not update a running registry, descriptor set, bearer token, manifest, instance scope, or execution limit.

Diagnose configuration failures

Related documentation

• CrewAI connector overview
• Authentication and admitted crews
• Connector host configuration
• Connector host lifecycle
• Environment variables