Native AppHost API for running Docker containers on Remote Machines via SSH

[WhiteOlivierus]

The Motivation

As distributed applications grow, running all dependencies locally quickly consumes a developer's machine resources. While developers have access to powerful remote dev servers, securely pushing Aspire-managed containers to these machines is currently difficult.

Furthermore, there is a strong security benefit to this approach. Running untrusted or heavy third-party container resources on a remote machine acts as an effective sandbox, isolating the developer's local workstation from potential resource exhaustion, malware, or network vulnerabilities hidden within container images.

Currently, achieving this requires global environment variables like DOCKER_HOST=ssh://... or custom SSH.Net scripts. This often breaks Aspire's seamless endpoint management, resulting in broken links on the Aspire Dashboard and proxy conflicts.

The Proposed Solution

I propose introducing a new AppHost API that models a Remote Machine as a Resource. You can then pass this remote machine resource to any container resource, instructing Aspire to spin up the container remotely via SSH, while managing the tunnels, dashboards, and logs locally.

var builder = DistributedApplication.CreateBuilder(args);

// 1. Define the remote machine/sandbox as a first-class resource
var remoteDevServer = builder.AddRemoteMachine("dev-server")
                             .WithSshEndpoint("192.168.1.100", 22)
                             .WithSshUser("developer")
                             .WithIdentityFile("~/.ssh/id_rsa");

// 2. Assign a container to run securely on the remote machine
var redis = builder.AddRedis("cache")
                   .RunOnHost(remoteDevServer); // Proposed extension method

// 3. Local projects reference the remote container seamlessly
builder.AddProject<Projects.MyWebApp>("webapp")
       .WithReference(redis);

By treating the remote machine as an explicitly defined resource, the Aspire AppHost can handle the heavy lifting under the hood—such as automatically establishing transparent SSH tunnels for the container's endpoints and streaming remote docker logs directly back into the local Aspire Dashboard.

[WhiteOlivierus]

So there is no animo for this?

[danegsta]

It's an interesting idea, but we'd have to balance any API against the need to support not just Docker, but Podman as well. We'd also need to take into account how this might work in a distributed team or CI environment. This is the sort of thing that often needs to be treated as per-developer or per-machine configuration and having a specific config checked in only makes sense for a single maintainer project. That's not meant to imply that there's not value in solving problems for single maintainer projects, but we have to reconcile a potential API against all the different environments it could end up used in. We're also looking at adding support for more runtimes (wslc for Windows and Apple container for macOS in the future), neither of which have support for a remote context and several container features such as bind mounts work unexpectedly for many users in a remote environment.

It's not that there's no interest in this, but we're primarily focused on local dev scenarios and would generally encourage running the entire workload on the remote machine if possible rather than trying to split between local and remote.

[CZEMacLeod]

It sounds like an abstraction of some sort for containers is needed anyway - where you can then plug the runtime (as mentioned - docker/podman/apple/wslc etc.)
Perhaps this could be the basis in the future for off machine runtimes too.
I agree that persistence, binding, and even port mapping could be an issue, but for instances which are spun up and disposed each time, I could see a use case for this.

[danegsta]

We've designed our container support with runtime abstraction, but based on lessons from past experience supporting container tooling in VS and VSCode we've gone with an abstraction layer based on the respective runtime CLIs rather than API access. Trying to reliably manage containers via the engine APIs requires reimplementing much of the functionality provided by the API and is fairly involved when it comes to building images (we'd effectively have to recreate everything the CLIs already do). The larger issue we ran into in cases where we did try to use the APIs was that it was generally unreliable the moment you ran into custom setups. Docker or Podman don't just talk to a remote endpoint, they're dealing with various transport protocols (is the endpoint listening on an https endpoint or ssh) as well as certificate management (need to locate and provide the correct certificate material for the connection).

Using the CLIs with an abstraction layer over top that breaks actions down into abstract concepts and normalized responses makes it fairly simple to implement support for additional runtimes (especially as Docker's CLI is constantly used as a reference implementation all other runtimes have so far tried to get as close to as possible). The main thing that's slowed down our adding wslc and Apple container support is that they're both missing some features we depend on heavily in their current state.

As for this particular remote connection scenario, I'd probably be inclined to model it via the similar context/connection model that Docker and Podman both have where a remote connection is registered with the CLI and commands can be executed for a specific backend target. This is one place where the CLIs do differ quite a bit in command and argument names, but the core functionality is pretty much the same so there's probably a straightforward abstraction there.