Add Chroma hosting and client integrations by Laurianti · Pull Request #2219 · CommunityToolkit/Aspire

Laurianti · 2026-10-04T14:47:43Z

Closes #2218

Picks up #1132 by @ali-Hamza817: his commits are kept as they are.

ChromaDB.Client 1.0.0 (v1 API only, removed in Chroma 1.x) replaced by ChromaDotNet.Client 2.11.0. Image chromadb/chroma:1.5.9, health check on /api/v2/heartbeat, connection string Endpoint=http://{host}:{port}.
[AspireExport] on the hosting API, ChromaResource in Aspire.Hosting.ApplicationModel, TypeScript AppHost example and test.
The example service gets its collection clients from the ChromaClient, so the workaround that rebuilt the endpoint is gone.
The example AppHost has https and http launch profiles, so it also runs over HTTP without a trusted development certificate.
WithDataVolume and WithDataBindMount mount /data, where Chroma 1.x persists, and set PERSIST_DIRECTORY to /data, so Chroma 0.x persists there too.
The client integration creates the ChromaClient with CreateChromaClient of ChromaDotNet.Client.DependencyInjection, so each request goes through the current handler of the HttpClient named after the connection, and cancels the health check at HealthCheckTimeout. Like the other client integrations, it reads its settings from Aspire:Chroma:Client and names the health checks Chroma and Chroma_{connectionName}.
Traces and metrics of the client, a span for each operation and db.client.operation.duration, with DisableTracing and DisableMetrics, and the conformance tests of the toolkit.
Like the client integrations of Aspire, the client integration is AOT compatible and binds its settings with the configuration binding generator, so trimmed and native AOT apps read them.
Chroma Cloud: the connection string also takes the token, the tenant and the database, Endpoint=https://api.trychroma.com;Token=...;Tenant=...;Database=..., and so do the settings. The token goes in the X-Chroma-Token header.
Package READMEs and the root README table.

The Chroma provider for Microsoft.Extensions.VectorData, accepted in the AI Community Toolkit (CommunityToolkit/AI#58), takes this ChromaClient from the container: builder.AddChromaClient("chroma"), then builder.Services.AddChromaVectorStore().

Tests: client 42, with the 2 configuration schema tests skipped as in the other integrations. Hosting 11 (unit, AppHost with a create/add/query round trip against Chroma 1.5.9, data persisted between runs on a volume and a bind mount with the default image and with Chroma 0.6.3, TypeScript AppHost). All pass locally, and a round trip through AddChromaClient on Chroma Cloud passed too.

PR Checklist

Other information

The docs page on aspire.dev follows once this is merged.

Co-authored-by: Ali 139616302+ali-Hamza817@users.noreply.github.com

Copilot

Copilot review overview

🟡 Changes recommended

Persistence targets the wrong container directory, while client registration and health-check timeout handling have runtime gaps.

Review effort: Balanced
Findings: 1 · 2

Open (3)

Register IHttpClientFactory for Chroma services · New
Honor HealthCheckTimeout during heartbeat probes · New
Mount Chroma data volume at /data · New

What changed in this PR

Adds ChromaDB hosting and client integrations, including Aspire resource modeling, dependency injection, persistence helpers, examples, and validation.

Changes:

Adds Chroma container and client packages.
Adds C# and TypeScript examples.
Adds unit, integration, and startup tests plus documentation.

File	Description
`tests/CommunityToolkit.Aspire.Hosting.Chroma.Tests/TypeScriptAppHostTests.cs`	Validates the TypeScript AppHost.
`tests/CommunityToolkit.Aspire.Hosting.Chroma.Tests/CommunityToolkit.Aspire.Hosting.Chroma.Tests.csproj`	Configures hosting tests.
`tests/CommunityToolkit.Aspire.Hosting.Chroma.Tests/AppHostTests.cs`	Tests health and collection operations.
`tests/CommunityToolkit.Aspire.Hosting.Chroma.Tests/AddChromaTests.cs`	Tests resource annotations and mounts.
`tests/CommunityToolkit.Aspire.Chroma.Tests/CommunityToolkit.Aspire.Chroma.Tests.csproj`	Configures client tests.
`tests/CommunityToolkit.Aspire.Chroma.Tests/ChromaClientExtensionsTests.cs`	Tests client and health-check registration.
`src/CommunityToolkit.Aspire.Hosting.Chroma/README.md`	Documents hosting usage and persistence.
`src/CommunityToolkit.Aspire.Hosting.Chroma/CommunityToolkit.Aspire.Hosting.Chroma.csproj`	Defines the hosting package.
`src/CommunityToolkit.Aspire.Hosting.Chroma/ChromaResource.cs`	Models the Chroma resource and connection properties.
`src/CommunityToolkit.Aspire.Hosting.Chroma/ChromaContainerImageTags.cs`	Defines container image metadata.
`src/CommunityToolkit.Aspire.Hosting.Chroma/ChromaBuilderExtensions.cs`	Adds hosting and persistence APIs.
`src/CommunityToolkit.Aspire.Chroma/README.md`	Documents client registration and configuration.
`src/CommunityToolkit.Aspire.Chroma/CommunityToolkit.Aspire.Chroma.csproj`	Defines the client package.
`src/CommunityToolkit.Aspire.Chroma/ChromaHealthCheck.cs`	Implements heartbeat health checking.
`src/CommunityToolkit.Aspire.Chroma/ChromaClientSettings.cs`	Defines and parses client settings.
`src/CommunityToolkit.Aspire.Chroma/AspireChromaExtensions.cs`	Registers keyed and unkeyed clients.
`README.md`	Lists both Chroma packages.
`examples/chromadb/CommunityToolkit.Aspire.Hosting.Chroma.ServiceDefaults/Extensions.cs`	Adds shared Aspire service defaults.
`examples/chromadb/CommunityToolkit.Aspire.Hosting.Chroma.ServiceDefaults/CommunityToolkit.Aspire.Hosting.Chroma.ServiceDefaults.csproj`	Configures service defaults.
`examples/chromadb/CommunityToolkit.Aspire.Hosting.Chroma.AppHost/Program.cs`	Orchestrates Chroma and the API example.
`examples/chromadb/CommunityToolkit.Aspire.Hosting.Chroma.AppHost/CommunityToolkit.Aspire.Hosting.Chroma.AppHost.csproj`	Configures the C# AppHost.
`examples/chromadb/CommunityToolkit.Aspire.Hosting.Chroma.AppHost.TypeScript/tsconfig.json`	Configures TypeScript compilation.
`examples/chromadb/CommunityToolkit.Aspire.Hosting.Chroma.AppHost.TypeScript/package.json`	Defines TypeScript tooling.
`examples/chromadb/CommunityToolkit.Aspire.Hosting.Chroma.AppHost.TypeScript/package-lock.json`	Locks TypeScript dependencies.
`examples/chromadb/CommunityToolkit.Aspire.Hosting.Chroma.AppHost.TypeScript/eslint.config.mjs`	Configures TypeScript linting.
`examples/chromadb/CommunityToolkit.Aspire.Hosting.Chroma.AppHost.TypeScript/aspire.config.json`	Maps the hosting package into Aspire.
`examples/chromadb/CommunityToolkit.Aspire.Hosting.Chroma.AppHost.TypeScript/apphost.mts`	Exercises exported hosting APIs.
`examples/chromadb/CommunityToolkit.Aspire.Hosting.Chroma.ApiService/Properties/launchSettings.json`	Defines local launch profiles.
`examples/chromadb/CommunityToolkit.Aspire.Hosting.Chroma.ApiService/Program.cs`	Demonstrates create and query operations.
`examples/chromadb/CommunityToolkit.Aspire.Hosting.Chroma.ApiService/CommunityToolkit.Aspire.Hosting.Chroma.ApiService.csproj`	Configures the example API.
`Directory.Packages.props`	Pins `ChromaDotNet.Client`.
`CommunityToolkit.Aspire.slnx`	Adds source and test projects.

Files not reviewed (1)

examples/chromadb/CommunityToolkit.Aspire.Hosting.Chroma.AppHost.TypeScript/package-lock.json: Generated file

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Directory.Packages.props and the README of ChromaDotNet.Aspire.Client are ours, so the sync does not change them: they follow CommunityToolkit/Aspire#2219.

This contribution adds support for ChromaDB as a .NET Aspire resource, including: - Hosting integration for containerized ChromaDB - Client integration with health checks and keyed service support - Persistence support via volumes and bind mounts - Comprehensive unit tests and documentation

- Removed auto-generated api files. - Refactored ChromaResource to use a primary constructor. - Corrected style for null checks (is null). - Added example app with CRUD operations in examples/chromadb. - Added integration tests for health and CRUD verification. - Updated tests.yml workflow to include new tests.

…Settings.json for ApiService

…lity

- ChromaDotNet.Client 2.11.0 in place of ChromaDB.Client 1.0.0, whose v1 API Chroma 1.x removed: image chromadb/chroma:1.5.9, health check on /api/v2/heartbeat, connection string Endpoint=http://{host}:{port}. - [AspireExport] on the hosting API, ChromaResource in Aspire.Hosting.ApplicationModel, TypeScript AppHost example and test. - The example service gets its collection clients from the ChromaClient. - The example AppHost has https and http launch profiles. - WithDataVolume and WithDataBindMount mount /data, where Chroma 1.x persists, and set PERSIST_DIRECTORY to /data for Chroma 0.x. - The client integration creates the ChromaClient with CreateChromaClient, cancels the health check at HealthCheckTimeout, reads its settings from Aspire:Chroma:Client and names the health checks Chroma and Chroma_{connectionName}. - Traces and metrics of the client, with DisableTracing and DisableMetrics, and the conformance tests of the toolkit. - AOT compatible, with the configuration binding generator. - Chroma Cloud: Token, Tenant and Database in the connection string and in the settings. - Package READMEs and the root README table. Co-authored-by: Ali <139616302+ali-Hamza817@users.noreply.github.com>

github-actions · 2026-10-09T01:22:50Z

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/CommunityToolkit/Aspire/main/eng/scripts/dogfood-pr.sh | bash -s -- 2219

Or

Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/CommunityToolkit/Aspire/main/eng/scripts/dogfood-pr.ps1) } 2219"

aaronpowell · 2026-10-09T01:23:27Z

Looking good, just need to bump the baseline version in the repo so that it's not shipping in a bad version number.

Laurianti · 2026-10-12T07:06:38Z

/codeowner-accept

github-actions · 2026-10-12T07:06:58Z

Thanks @Laurianti — I have recorded that you want to own this integration and opened or updated #2245 to add you to CODEOWNERS for examples/chromadb/.

@CommunityToolkit/aspire-owners please add @Laurianti to the organization so the CODEOWNERS entry can be used.

Laurianti · 2026-10-12T07:10:16Z

Thanks a lot, @aaronpowell! And thanks to @ali-Hamza817 for the original work this builds on.

Copilot AI balanced review requested due to automatic review settings October 4, 2026 14:47

Copilot started reviewing on behalf of Laurianti October 4, 2026 14:48 View session

Laurianti force-pushed the chroma-integration branch from b972db7 to 6feb898 Compare October 4, 2026 14:50

Copilot AI reviewed Oct 4, 2026

View reviewed changes

Comment thread src/CommunityToolkit.Aspire.Chroma/AspireChromaExtensions.cs

Comment thread src/CommunityToolkit.Aspire.Chroma/ChromaHealthCheck.cs Outdated

Comment thread src/CommunityToolkit.Aspire.Hosting.Chroma/ChromaBuilderExtensions.cs Outdated

Laurianti mentioned this pull request Oct 4, 2026

Create Aspire component ssone95/ChromaDB.Client#49

Open

Laurianti force-pushed the chroma-integration branch from 6feb898 to 2629eec Compare October 4, 2026 15:00

ali-Hamza817 added 7 commits October 7, 2026 02:02

Address Copilot feedback: fix grammar and rename test class

bbe8caf

Fix CI test failures: use relative path for bind mount and add launch…

f8086d8

…Settings.json for ApiService

fix(chroma): resolve health check 404 and address review feedback

3296bf6

fix(chroma): resolve health check 404 and address review feedback

d9d865e

feat(chroma): fix health check and base URL construction for CI stabi…

69f7e5a

…lity

Laurianti force-pushed the chroma-integration branch from 348a721 to c4eef24 Compare October 7, 2026 00:07

Laurianti force-pushed the chroma-integration branch from c4eef24 to fe680b9 Compare October 7, 2026 14:03

aaronpowell approved these changes Oct 9, 2026

View reviewed changes

aaronpowell merged commit d11b8d6 into CommunityToolkit:main Oct 12, 2026
18 checks passed

github-actions Bot mentioned this pull request Oct 12, 2026

Add CODEOWNERS entry for integration PR #2219 #2245

Open

This was referenced Oct 12, 2026

Say that the toolkit accepted the Chroma integration ChromaDotNet/ChromaDB.Aspire#9

Merged

Use the Aspire SDK 13.6.1 in the Chroma TypeScript AppHost #2246

Open

Navigation Menu

Repository navigation

Add Chroma hosting and client integrations - #2219

Add Chroma hosting and client integrations#2219
aaronpowell merged 8 commits into
CommunityToolkit:mainfrom
Laurianti:chroma-integration

Laurianti commented Oct 4, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Oct 9, 2026

Uh oh!

aaronpowell commented Oct 9, 2026

Uh oh!

Uh oh!

Laurianti commented Oct 12, 2026

Uh oh!

github-actions Bot commented Oct 12, 2026

Uh oh!

Laurianti commented Oct 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

Laurianti commented Oct 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Checklist

Other information

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Oct 9, 2026

Uh oh!

aaronpowell commented Oct 9, 2026

Uh oh!

Uh oh!

Laurianti commented Oct 12, 2026

Uh oh!

github-actions Bot commented Oct 12, 2026

Uh oh!

Laurianti commented Oct 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Laurianti commented Oct 4, 2026 •

edited

Loading