HenrikJensen.RemoteContainers.Aspire 1.0.0-beta1

Aspire Remote Containers

Use Aspire with a remote Docker or Podman engine via automatic SSH port forwarding.

The Problem

When Aspire runs container resources, its orchestrator (DCP) allocates ports on the Docker host. If Docker runs on a remote machine (pointed to by DOCKER_HOST=tcp://…), those ports are only reachable on the remote host - not on localhost where your Aspire AppHost is running. This means the Aspire dashboard, service discovery, and any local tooling cannot reach the containers.

How It Works

This extension detects that DOCKER_HOST points to a remote tcp:// address and automatically creates SSH tunnels for every container resource:

1. You call builder.AddSshTunneling() in your AppHost.
2. When Aspire allocates endpoints for a container resource, the extension queries the Docker REST API on the remote host to discover the published port mappings.
3. For each discovered port, an SSH port forward (localhost:port → remote:port) is created through an SSH connection to the Docker host.
4. When the AppHost shuts down, all tunnels and the SSH connection are cleaned up automatically.

Getting Started

Install the NuGet Package

dotnet add package HenrikJensen.RemoteContainers.Aspire

Usage

Add a single line to your Aspire AppHost:

using Hj.RemoteContainers.Aspire;

var builder = DistributedApplication.CreateBuilder(args);

builder.AddSshTunneling();

// ...

await builder.Build().RunAsync();

No changes are needed to your container resource definitions - the tunneling is fully transparent once enabled.

Configuration

Required Environment Variables

Add this in your Aspire AppHost launchSettings.json:

Optional Environment Variables (TLS)

Set these if your remote Docker endpoint requires TLS:

Example launchSettings.json with TLS enabled:

{
  "profiles": {
    "https": {
      "commandName": "Project",
      "environmentVariables": {
        "DOCKER_HOST": "tcp://my-server:2376",
        "DOCKER_TLS_VERIFY": "1",
        "DOCKER_CERT_PATH": "/path/to/certs/client"
      }
    }
  }
}

Optional Settings

These can be set via any .NET configuration source (environment variables, appsettings.json, etc.):

SSH Key Authentication

The extension automatically loads private keys from ~/.ssh/ and tries the following files in order:

• id_rsa
• id_ed25519
• id_ecdsa

At least one unencrypted key must be present and authorized on the remote host.

Only key-based authentication (authorized_keys) is supported!

When Tunneling Is Inactive

If DOCKER_HOST is not set or does not start with tcp://, the extension does nothing - AddSshTunneling() is safe to call unconditionally and will silently no-op when Docker is local.

Prerequisites

• .NET 10 SDK (LTS)
• Aspire
• A remote Docker or Podman engine exposed over TCP with TLS
• SSH access to the remote host with key-based authentication