How to run Aspire in a .NET SDK container without docker client?

[paulomorgado]

I'm trying to use DistributedApplicationTestingBuilder to run tests in a mcr.microsoft.com/dotnet/sdk:8.0 container without any docker cli tools, but with Aspire I get:

 [2025-10-20 16:18:16Z] dbug: Microsoft.Extensions.Hosting.Internal.Host[1]
       Hosting starting
 [2025-10-20 16:18:47Z] warn: Aspire.Hosting.Dcp.DcpHost[0]
       Container runtime 'docker' could not be found. See https://aka.ms/dotnet/aspire/containers for more details on supported container runtimes.
 [2025-10-20 16:18:47Z] fail: Microsoft.Extensions.Hosting.Internal.Host[11]
       Hosting failed to start
 Aspire.Hosting.DistributedApplicationException: Container runtime 'docker' could not be found. See https://aka.ms/dotnet/aspire/containers for more details on supported container runtimes.
    at Aspire.Hosting.Dcp.DcpDependencyCheck.CheckDcpInfoAndLogErrors(ILogger logger, DcpOptions options, DcpInfo dcpInfo, Boolean throwIfUnhealthy) in /_/src/Aspire.Hosting/Dcp/DcpDependencyCheck.cs:line 250
    at Aspire.Hosting.Dcp.DcpHost.EnsureDcpContainerRuntimeAsync(CancellationToken cancellationToken) in /_/src/Aspire.Hosting/Dcp/DcpHost.cs:line 114
    at Aspire.Hosting.Dcp.DcpHost.StartAsync(CancellationToken cancellationToken) in /_/src/Aspire.Hosting/Dcp/DcpHost.cs:line 66
    at Aspire.Hosting.Orchestrator.OrchestratorHostService.StartAsync(CancellationToken cancellationToken) in /_/src/Aspire.Hosting/Orchestrator/OrchestratorHostService.cs:line 39
    at Microsoft.Extensions.Hosting.Internal.Host.<StartAsync>b__15_1(IHostedService service, CancellationToken token)
    at Microsoft.Extensions.Hosting.Internal.Host.ForeachService[T](IEnumerable`1 services, CancellationToken token, Boolean concurrent, Boolean abortOnFirstException, List`1 exceptions, Func`3 operation)

What am I doing wrong?

I've been able to do the same using TestContainers.

[davidfowl]

You're trying to run your tests inside of a container? Aspire depends on the docker cli.

cc @danegsta @karolz-ms

[paulomorgado]

You're trying to run your tests inside of a container?

Yes!

I have tests using TestContainers and Cake tasks that use Docker API and work just fine,

[davidfowl]

Aspire requires the CLI so you need the access to the CLI in the container (at the moment).

[danegsta]

Yeah, we made an intentional decision to depend on the CLI instead of trying to connect to a daemon API endpoint like it seems that Testcontainers does from looking at their repo. In a simple setup connecting directly to the API can work, but as soon as a user’s Docker configuration varies slightly from the norm, it becomes too easy to fail to connect to the daemon (this was a constant source of bugs for the VSCode containers extension before we switched to using the CLI).

Short version is that there are so many variables that can change to how you have to connect to the daemon that it’s much less error prone at scale to treat the CLI tooling as the API instead.