From e497d7b9cd1dea0c3ebf130aaa1772031038dab7 Mon Sep 17 00:00:00 2001
From: Henrik Jensen <1175002+henrikhimself@users.noreply.github.com>
Date: Tue, 3 Mar 2026 08:56:46 +0100
Subject: [PATCH 01/25] Add extension for remote containers

---
 .aspire/settings.json                         |   3 +
 .editorconfig                                 | 527 ++++++++++++++++++
 .github/skills/aspire/SKILL.md                | 231 ++++++++
 .../skills/aspire/references/architecture.md  | 341 ++++++++++++
 .../skills/aspire/references/cli-reference.md | 307 ++++++++++
 .github/skills/aspire/references/dashboard.md | 226 ++++++++
 .../skills/aspire/references/deployment.md    | 237 ++++++++
 .../aspire/references/integrations-catalog.md |  68 +++
 .../skills/aspire/references/mcp-server.md    | 195 +++++++
 .../skills/aspire/references/polyglot-apis.md | 296 ++++++++++
 .github/skills/aspire/references/testing.md   | 281 ++++++++++
 .../aspire/references/troubleshooting.md      | 194 +++++++
 .gitignore                                    | 491 ++++++++++++++++
 .vscode/extensions.json                       |   6 +
 .vscode/launch.json                           |  21 +
 .vscode/mcp.json                              |  12 +
 .vscode/settings.json                         |  19 +
 AGENTS.md                                     |  74 +++
 Directory.Build.props                         |  23 +
 Directory.Build.targets                       |  15 +
 Directory.Packages.props                      |  16 +
 LICENSE                                       | 222 +++++++-
 NuGet.config                                  |  12 +
 README.md                                     | 106 +++-
 RemoteContainers.slnx                         |   6 +
 examples/.editorconfig                        |   5 +
 examples/Aspire.AppHost/Aspire.AppHost.csproj |  13 +
 .../Properties/launchSettings.json            |  37 ++
 examples/Aspire.AppHost/apphost.cs            |  10 +
 examples/Aspire.AppHost/appsettings.json      |  11 +
 global.json                                   |   7 +
 src/.editorconfig                             |   9 +
 .../DockerApiClient.cs                        | 280 ++++++++++
 .../Models/ContainerPorts.cs                  |  24 +
 .../RemoteContainers.Aspire.csproj            |  34 ++
 .../SshTunnelExtensions.cs                    |  58 ++
 .../SshTunnelLifecycleHook.cs                 |  51 ++
 .../SshTunnelManager.cs                       | 225 ++++++++
 stylecop.json                                 |   8 +
 39 files changed, 4678 insertions(+), 23 deletions(-)
 create mode 100644 .aspire/settings.json
 create mode 100644 .editorconfig
 create mode 100644 .github/skills/aspire/SKILL.md
 create mode 100644 .github/skills/aspire/references/architecture.md
 create mode 100644 .github/skills/aspire/references/cli-reference.md
 create mode 100644 .github/skills/aspire/references/dashboard.md
 create mode 100644 .github/skills/aspire/references/deployment.md
 create mode 100644 .github/skills/aspire/references/integrations-catalog.md
 create mode 100644 .github/skills/aspire/references/mcp-server.md
 create mode 100644 .github/skills/aspire/references/polyglot-apis.md
 create mode 100644 .github/skills/aspire/references/testing.md
 create mode 100644 .github/skills/aspire/references/troubleshooting.md
 create mode 100644 .gitignore
 create mode 100644 .vscode/extensions.json
 create mode 100644 .vscode/launch.json
 create mode 100644 .vscode/mcp.json
 create mode 100644 .vscode/settings.json
 create mode 100644 AGENTS.md
 create mode 100644 Directory.Build.props
 create mode 100644 Directory.Build.targets
 create mode 100644 Directory.Packages.props
 create mode 100644 NuGet.config
 create mode 100644 RemoteContainers.slnx
 create mode 100644 examples/.editorconfig
 create mode 100644 examples/Aspire.AppHost/Aspire.AppHost.csproj
 create mode 100644 examples/Aspire.AppHost/Properties/launchSettings.json
 create mode 100644 examples/Aspire.AppHost/apphost.cs
 create mode 100644 examples/Aspire.AppHost/appsettings.json
 create mode 100644 global.json
 create mode 100644 src/.editorconfig
 create mode 100644 src/RemoteContainers.Aspire/DockerApiClient.cs
 create mode 100644 src/RemoteContainers.Aspire/Models/ContainerPorts.cs
 create mode 100644 src/RemoteContainers.Aspire/RemoteContainers.Aspire.csproj
 create mode 100644 src/RemoteContainers.Aspire/SshTunnelExtensions.cs
 create mode 100644 src/RemoteContainers.Aspire/SshTunnelLifecycleHook.cs
 create mode 100644 src/RemoteContainers.Aspire/SshTunnelManager.cs
 create mode 100644 stylecop.json

diff --git a/.aspire/settings.json b/.aspire/settings.json
new file mode 100644
index 0000000..cac15a7
--- /dev/null
+++ b/.aspire/settings.json
@@ -0,0 +1,3 @@
+{
+  "appHostPath": "../examples/Aspire.AppHost/Aspire.AppHost.csproj"
+}
\ No newline at end of file
diff --git a/.editorconfig b/.editorconfig
new file mode 100644
index 0000000..7d8983c
--- /dev/null
+++ b/.editorconfig
@@ -0,0 +1,527 @@
+# 20260214
+root = true
+
+[*]
+indent_style = space
+charset = utf-8
+end_of_line = lf
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+# Makefiles should use tabs for indentation and not have trailing whitespace
+[Makefile]
+indent_style = tab
+
+# XML project files
+[*.{csproj}]
+indent_size = 2
+
+# XML config files
+[*.{props,targets,ruleset,config,nuspec}]
+indent_size = 2
+
+[*.{json,jsonc}]
+indent_size = 2
+
+[*.{sh,bash,ps1,,psm1}]
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{razor,cshtml}]
+charset = utf-8-bom
+insert_final_newline = true
+
+[*.cs]
+indent_size = 2
+insert_final_newline = true
+
+# Sort using and Import directives with System.* appearing first
+dotnet_sort_system_directives_first = true
+dotnet_separate_import_directive_groups = false
+
+# Avoid "this." and "Me." if not necessary
+dotnet_style_qualification_for_field = false:refactoring
+dotnet_style_qualification_for_property = false:refactoring
+dotnet_style_qualification_for_method = false:refactoring
+dotnet_style_qualification_for_event = false:refactoring
+
+# Use language keywords instead of framework type names for type references
+dotnet_style_predefined_type_for_locals_parameters_members = true:suggestion
+dotnet_style_predefined_type_for_member_access = true:suggestion
+
+# Require var all the time.
+csharp_style_var_for_built_in_types = true:suggestion
+csharp_style_var_when_type_is_apparent = true:suggestion
+csharp_style_var_elsewhere = true:suggestion
+
+# Suggest more modern language features when available
+dotnet_style_object_initializer = true:suggestion
+dotnet_style_collection_initializer = true:suggestion
+dotnet_style_coalesce_expression = true:suggestion
+dotnet_style_null_propagation = true:suggestion
+dotnet_style_explicit_tuple_names = true:suggestion
+csharp_style_pattern_matching_over_is_with_cast_check = true:suggestion
+csharp_style_pattern_matching_over_as_with_null_check = true:suggestion
+csharp_style_inlined_variable_declaration = true:suggestion
+csharp_style_throw_expression = true:suggestion
+csharp_style_conditional_delegate_call = true:suggestion
+csharp_style_prefer_extended_property_pattern = true:suggestion
+
+# Non-private static fields are PascalCase
+dotnet_naming_rule.non_private_static_fields_should_be_pascal_case.severity = warning
+dotnet_naming_rule.non_private_static_fields_should_be_pascal_case.symbols = non_private_static_fields
+dotnet_naming_rule.non_private_static_fields_should_be_pascal_case.style = non_private_static_field_style
+
+dotnet_naming_symbols.non_private_static_fields.applicable_kinds = field
+dotnet_naming_symbols.non_private_static_fields.applicable_accessibilities = public, protected, internal, protected_internal, private_protected
+dotnet_naming_symbols.non_private_static_fields.required_modifiers = static
+
+dotnet_naming_style.non_private_static_field_style.capitalization = pascal_case
+
+# Non-private readonly fields are PascalCase
+dotnet_naming_rule.non_private_readonly_fields_should_be_pascal_case.severity = warning
+dotnet_naming_rule.non_private_readonly_fields_should_be_pascal_case.symbols = non_private_readonly_fields
+dotnet_naming_rule.non_private_readonly_fields_should_be_pascal_case.style = non_private_readonly_field_style
+
+dotnet_naming_symbols.non_private_readonly_fields.applicable_kinds = field
+dotnet_naming_symbols.non_private_readonly_fields.applicable_accessibilities = public, protected, internal, protected_internal, private_protected
+dotnet_naming_symbols.non_private_readonly_fields.required_modifiers = readonly
+
+dotnet_naming_style.non_private_readonly_field_style.capitalization = pascal_case
+
+# Constants are PascalCase
+dotnet_naming_rule.constants_should_be_pascal_case.severity = warning
+dotnet_naming_rule.constants_should_be_pascal_case.symbols = constants
+dotnet_naming_rule.constants_should_be_pascal_case.style = constant_style
+
+dotnet_naming_symbols.constants.applicable_kinds = field, local
+dotnet_naming_symbols.constants.required_modifiers = const
+
+dotnet_naming_style.constant_style.capitalization = pascal_case
+
+# Static fields are camelCase and start with _
+dotnet_naming_rule.static_fields_should_be_camel_case.severity = warning
+dotnet_naming_rule.static_fields_should_be_camel_case.symbols = static_fields
+dotnet_naming_rule.static_fields_should_be_camel_case.style = static_field_style
+
+dotnet_naming_symbols.static_fields.applicable_kinds = field
+dotnet_naming_symbols.static_fields.required_modifiers = static
+
+dotnet_naming_style.static_field_style.capitalization = camel_case
+dotnet_naming_style.static_field_style.required_prefix = _
+
+# Instance fields are camelCase and start with _
+dotnet_naming_rule.instance_fields_should_be_camel_case.severity = warning
+dotnet_naming_rule.instance_fields_should_be_camel_case.symbols = instance_fields
+dotnet_naming_rule.instance_fields_should_be_camel_case.style = instance_field_style
+
+dotnet_naming_symbols.instance_fields.applicable_kinds = field
+
+dotnet_naming_style.instance_field_style.capitalization = camel_case
+dotnet_naming_style.instance_field_style.required_prefix = _
+
+# Async methods should have "Async" suffix
+dotnet_naming_rule.async_methods_end_in_async.symbols = any_async_methods
+dotnet_naming_rule.async_methods_end_in_async.style = end_in_async
+dotnet_naming_rule.async_methods_end_in_async.severity = warning
+
+dotnet_naming_symbols.any_async_methods.applicable_kinds = method
+dotnet_naming_symbols.any_async_methods.applicable_accessibilities = *
+dotnet_naming_symbols.any_async_methods.required_modifiers = async
+
+dotnet_naming_style.end_in_async.required_prefix =
+dotnet_naming_style.end_in_async.required_suffix = Async
+dotnet_naming_style.end_in_async.capitalization = pascal_case
+dotnet_naming_style.end_in_async.word_separator =
+
+# Locals and parameters are camelCase
+dotnet_naming_rule.locals_should_be_camel_case.severity = warning
+dotnet_naming_rule.locals_should_be_camel_case.symbols = locals_and_parameters
+dotnet_naming_rule.locals_should_be_camel_case.style = camel_case_style
+
+dotnet_naming_symbols.locals_and_parameters.applicable_kinds = parameter, local
+
+dotnet_naming_style.camel_case_style.capitalization = camel_case
+
+# Local functions are PascalCase
+dotnet_naming_rule.local_functions_should_be_pascal_case.severity = warning
+dotnet_naming_rule.local_functions_should_be_pascal_case.symbols = local_functions
+dotnet_naming_rule.local_functions_should_be_pascal_case.style = local_function_style
+
+dotnet_naming_symbols.local_functions.applicable_kinds = local_function
+
+dotnet_naming_style.local_function_style.capitalization = pascal_case
+
+# By default, name items with PascalCase
+dotnet_naming_rule.members_should_be_pascal_case.severity = warning
+dotnet_naming_rule.members_should_be_pascal_case.symbols = all_members
+dotnet_naming_rule.members_should_be_pascal_case.style = pascal_case_style
+
+dotnet_naming_symbols.all_members.applicable_kinds = *
+
+dotnet_naming_style.pascal_case_style.capitalization = pascal_case
+
+# Newline settings
+csharp_new_line_before_open_brace = all
+csharp_new_line_before_else = true
+csharp_new_line_before_catch = true
+csharp_new_line_before_finally = true
+csharp_new_line_before_members_in_object_initializers = true
+csharp_new_line_before_members_in_anonymous_types = true
+csharp_new_line_between_query_expression_clauses = true
+
+# Indentation preferences
+csharp_indent_block_contents = true
+csharp_indent_braces = false
+csharp_indent_case_contents = true
+csharp_indent_case_contents_when_block = true
+csharp_indent_switch_labels = true
+csharp_indent_labels = flush_left
+
+# Whitespace options
+csharp_style_allow_embedded_statements_on_same_line_experimental = false
+csharp_style_allow_blank_lines_between_consecutive_braces_experimental = false
+csharp_style_allow_blank_line_after_colon_in_constructor_initializer_experimental = false
+csharp_style_allow_blank_line_after_token_in_conditional_expression_experimental = false
+csharp_style_allow_blank_line_after_token_in_arrow_expression_clause_experimental = false
+
+# Prefer method-like constructs to have a block body
+csharp_style_expression_bodied_methods = false:none
+csharp_style_expression_bodied_constructors = false:none
+csharp_style_expression_bodied_operators = false:none
+
+# Prefer property-like constructs to have an expression-body
+csharp_style_expression_bodied_properties = true:none
+csharp_style_expression_bodied_indexers = true:none
+csharp_style_expression_bodied_accessors = true:none
+
+# Space preferences
+csharp_space_after_cast = false
+csharp_space_after_colon_in_inheritance_clause = true
+csharp_space_after_comma = true
+csharp_space_after_dot = false
+csharp_space_after_keywords_in_control_flow_statements = true
+csharp_space_after_semicolon_in_for_statement = true
+csharp_space_around_binary_operators = before_and_after
+csharp_space_around_declaration_statements = do_not_ignore
+csharp_space_before_colon_in_inheritance_clause = true
+csharp_space_before_comma = false
+csharp_space_before_dot = false
+csharp_space_before_open_square_brackets = false
+csharp_space_before_semicolon_in_for_statement = false
+csharp_space_between_empty_square_brackets = false
+csharp_space_between_method_call_empty_parameter_list_parentheses = false
+csharp_space_between_method_call_name_and_opening_parenthesis = false
+csharp_space_between_method_call_parameter_list_parentheses = false
+csharp_space_between_method_declaration_empty_parameter_list_parentheses = false
+csharp_space_between_method_declaration_name_and_open_parenthesis = false
+csharp_space_between_method_declaration_parameter_list_parentheses = false
+csharp_space_between_parentheses = false
+csharp_space_between_square_brackets = false
+
+# Namespace settings
+csharp_style_namespace_declarations = file_scoped
+
+# Brace settings
+csharp_prefer_braces = true
+
+# SYSLIB1054: Use 'LibraryImportAttribute' instead of 'DllImportAttribute' to generate P/Invoke marshalling code at compile time
+dotnet_diagnostic.SYSLIB1054.severity = warning
+
+# CA1515: Consider making public types internal
+dotnet_diagnostic.CA1515.severity = suggestion
+
+# CA1018: Mark attributes with AttributeUsageAttribute
+dotnet_diagnostic.CA1018.severity = warning
+
+# CA1034: Nested types should not be visible
+dotnet_diagnostic.CA1034.severity = silent
+
+# CA1047: Do not declare protected member in sealed type
+dotnet_diagnostic.CA1047.severity = warning
+
+# CA1305: Specify IFormatProvider
+dotnet_diagnostic.CA1305.severity = warning
+
+# CA1307: Specify StringComparison for clarity
+dotnet_diagnostic.CA1307.severity = warning
+
+# CA1507: Use nameof to express symbol names
+dotnet_diagnostic.CA1507.severity = warning
+
+# CA1508: CA1508: Avoid dead conditional code
+dotnet_diagnostic.CA1508.severity = error
+
+# CA1510: Use ArgumentNullException throw helper
+dotnet_diagnostic.CA1510.severity = warning
+
+# CA1511: Use ArgumentException throw helper
+dotnet_diagnostic.CA1511.severity = warning
+
+# CA1512: Use ArgumentOutOfRangeException throw helper
+dotnet_diagnostic.CA1512.severity = warning
+
+# CA1513: Use ObjectDisposedException throw helper
+dotnet_diagnostic.CA1513.severity = warning
+
+# CA1725: Parameter names should match base declaration
+dotnet_diagnostic.CA1725.severity = suggestion
+
+# CA1802: Use literals where appropriate
+dotnet_diagnostic.CA1802.severity = warning
+
+# CA1805: Do not initialize unnecessarily
+dotnet_diagnostic.CA1805.severity = warning
+
+# CA1810: Do not initialize unnecessarily
+dotnet_diagnostic.CA1810.severity = warning
+
+# CA1821: Remove empty Finalizers
+dotnet_diagnostic.CA1821.severity = warning
+
+# CA1822: Make member static
+dotnet_diagnostic.CA1822.severity = warning
+dotnet_code_quality.CA1822.api_surface = private, internal
+
+# CA1823: Avoid unused private fields
+dotnet_diagnostic.CA1823.severity = warning
+
+# CA1825: Avoid zero-length array allocations
+dotnet_diagnostic.CA1825.severity = warning
+
+# CA1826: Do not use Enumerable methods on indexable collections. Instead use the collection directly
+dotnet_diagnostic.CA1826.severity = warning
+
+# CA1827: Do not use Count() or LongCount() when Any() can be used
+dotnet_diagnostic.CA1827.severity = warning
+
+# CA1828: Do not use CountAsync() or LongCountAsync() when AnyAsync() can be used
+dotnet_diagnostic.CA1828.severity = warning
+
+# CA1829: Use Length/Count property instead of Count() when available
+dotnet_diagnostic.CA1829.severity = warning
+
+# CA1830: Prefer strongly-typed Append and Insert method overloads on StringBuilder
+dotnet_diagnostic.CA1830.severity = warning
+
+# CA1831: Use AsSpan or AsMemory instead of Range-based indexers when appropriate
+dotnet_diagnostic.CA1831.severity = warning
+
+# CA1832: Use AsSpan or AsMemory instead of Range-based indexers when appropriate
+dotnet_diagnostic.CA1832.severity = warning
+
+# CA1833: Use AsSpan or AsMemory instead of Range-based indexers when appropriate
+dotnet_diagnostic.CA1833.severity = warning
+
+# CA1834: Consider using 'StringBuilder.Append(char)' when applicable
+dotnet_diagnostic.CA1834.severity = warning
+
+# CA1835: Prefer the 'Memory'-based overloads for 'ReadAsync' and 'WriteAsync'
+dotnet_diagnostic.CA1835.severity = warning
+
+# CA1836: Prefer IsEmpty over Count
+dotnet_diagnostic.CA1836.severity = warning
+
+# CA1837: Use 'Environment.ProcessId'
+dotnet_diagnostic.CA1837.severity = warning
+
+# CA1838: Avoid 'StringBuilder' parameters for P/Invokes
+dotnet_diagnostic.CA1838.severity = warning
+
+# CA1839: Use 'Environment.ProcessPath'
+dotnet_diagnostic.CA1839.severity = warning
+
+# CA1840: Use 'Environment.CurrentManagedThreadId'
+dotnet_diagnostic.CA1840.severity = warning
+
+# CA1841: Prefer Dictionary.Contains methods
+dotnet_diagnostic.CA1841.severity = warning
+
+# CA1842: Do not use 'WhenAll' with a single task
+dotnet_diagnostic.CA1842.severity = warning
+
+# CA1843: Do not use 'WaitAll' with a single task
+dotnet_diagnostic.CA1843.severity = warning
+
+# CA1844: Provide memory-based overrides of async methods when subclassing 'Stream'
+dotnet_diagnostic.CA1844.severity = warning
+
+# CA1845: Use span-based 'string.Concat'
+dotnet_diagnostic.CA1845.severity = warning
+
+# CA1846: Prefer AsSpan over Substring
+dotnet_diagnostic.CA1846.severity = warning
+
+# CA1847: Use string.Contains(char) instead of string.Contains(string) with single characters
+dotnet_diagnostic.CA1847.severity = warning
+
+# CA1848: Use the LoggerMessage delegates
+dotnet_diagnostic.CA1848.severity = none
+
+# CA1852: Seal internal types
+dotnet_diagnostic.CA1852.severity = warning
+
+# CA1854: Prefer the IDictionary.TryGetValue(TKey, out TValue) method
+dotnet_diagnostic.CA1854.severity = warning
+
+# CA1855: Prefer 'Clear' over 'Fill'
+dotnet_diagnostic.CA1855.severity = warning
+
+# CA1856: Incorrect usage of ConstantExpected attribute
+dotnet_diagnostic.CA1856.severity = error
+
+# CA1857: A constant is expected for the parameter
+dotnet_diagnostic.CA1857.severity = warning
+
+# CA1858: Use 'StartsWith' instead of 'IndexOf'
+dotnet_diagnostic.CA1858.severity = warning
+
+# CA2000: Dispose objects before losing scope
+dotnet_diagnostic.CA2000.severity = error
+
+# CA2007: Consider calling ConfigureAwait on the awaited task
+# It is generally appropriate to suppress this warning entirely for projects that represent application code rather than library code
+dotnet_diagnostic.CA2007.severity = none
+
+# CA2008: Do not create tasks without passing a TaskScheduler
+dotnet_diagnostic.CA2008.severity = warning
+
+# CA2009: Do not call ToImmutableCollection on an ImmutableCollection value
+dotnet_diagnostic.CA2009.severity = warning
+
+# CA2011: Avoid infinite recursion
+dotnet_diagnostic.CA2011.severity = warning
+
+# CA2012: Use ValueTask correctly
+dotnet_diagnostic.CA2012.severity = warning
+
+# CA2013: Do not use ReferenceEquals with value types
+dotnet_diagnostic.CA2013.severity = warning
+
+# CA2014: Do not use stackalloc in loops.
+dotnet_diagnostic.CA2014.severity = warning
+
+# CA2016: Forward the 'CancellationToken' parameter to methods that take one
+dotnet_diagnostic.CA2016.severity = warning
+
+# CA2200: Rethrow to preserve stack details
+dotnet_diagnostic.CA2200.severity = warning
+
+# CA2201: Do not raise reserved exception types
+dotnet_diagnostic.CA2201.severity = warning
+
+# CA2208: Instantiate argument exceptions correctly
+dotnet_diagnostic.CA2208.severity = warning
+
+# CA2245: Do not assign a property to itself
+dotnet_diagnostic.CA2245.severity = warning
+
+# CA2246: Assigning symbol and its member in the same statement
+dotnet_diagnostic.CA2246.severity = warning
+
+# CA2249: Use string.Contains instead of string.IndexOf to improve readability.
+dotnet_diagnostic.CA2249.severity = warning
+
+# CS1591: Missing XML comment for publicly visible type or member 'Type_or_Member'
+dotnet_diagnostic.CS1591.severity = none
+
+# IDE0005: Remove unnecessary usings
+dotnet_diagnostic.IDE0005.severity = warning
+
+# IDE0011: Curly braces to surround blocks of code
+dotnet_diagnostic.IDE0011.severity = warning
+
+# IDE0029: Use coalesce expression (non-nullable types)
+dotnet_diagnostic.IDE0029.severity = warning
+
+# IDE0030: Use coalesce expression (nullable types)
+dotnet_diagnostic.IDE0030.severity = warning
+
+# IDE0031: Use null propagation
+dotnet_diagnostic.IDE0031.severity = warning
+
+# IDE0035: Remove unreachable code
+dotnet_diagnostic.IDE0035.severity = warning
+
+# IDE0036: Order modifiers
+csharp_preferred_modifier_order = public,private,protected,internal,static,extern,new,virtual,abstract,sealed,override,readonly,unsafe,volatile,async:suggestion
+dotnet_diagnostic.IDE0036.severity = warning
+
+# IDE0038: Use pattern matching to avoid is check followed by a cast (without variable) - also see IDE0020
+dotnet_diagnostic.IDE0038.severity = warning
+
+# IDE0043: Format string contains invalid placeholder
+dotnet_diagnostic.IDE0043.severity = warning
+
+# IDE0044: Make field readonly
+dotnet_diagnostic.IDE0044.severity = warning
+
+# IDE0051: Remove unused private members
+dotnet_diagnostic.IDE0051.severity = warning
+
+# IDE0055: All formatting rules
+dotnet_diagnostic.IDE0055.severity = suggestion
+
+# IDE0059: Unnecessary assignment to a value
+dotnet_diagnostic.IDE0059.severity = warning
+
+# IDE0060: Remove unused parameter
+dotnet_code_quality_unused_parameters = non_public
+dotnet_diagnostic.IDE0060.severity = warning
+
+# IDE0062: Make local function static
+dotnet_diagnostic.IDE0062.severity = warning
+
+# IDE0073: File header
+dotnet_diagnostic.IDE0073.severity = suggestion
+
+# IDE0161: Convert to file-scoped namespace
+dotnet_diagnostic.IDE0161.severity = warning
+
+# IDE0200: Lambda expression can be removed
+dotnet_diagnostic.IDE0200.severity = warning
+
+# IDE0290: Use primary constructor
+dotnet_diagnostic.IDE0290.severity = none
+
+# IDE2000: Disallow multiple blank lines
+dotnet_style_allow_multiple_blank_lines_experimental = false
+dotnet_diagnostic.IDE2000.severity = warning
+
+# The spacing around a C# keyword is incorrect
+dotnet_diagnostic.SA1000.severity = none
+
+# A closing parenthesis within a C# statement is not spaced correctly
+dotnet_diagnostic.SA1009.severity = none
+
+# An opening square bracket within a C# statement is not spaced correctly
+dotnet_diagnostic.SA1010.severity = none
+
+# A closing square bracket within a C# statement is not spaced correctly.
+dotnet_diagnostic.SA1011.severity = none
+
+# SA1101: A call to an instance member of the local class or a base class is not prefixed with 'this.', within a C# code file
+dotnet_diagnostic.SA1101.severity = none
+
+# SA1200: A C# using directive is placed outside of a namespace element
+dotnet_diagnostic.SA1200.severity = none
+
+# SA1206: The keywords within the declaration of an element do not follow a standard ordering scheme
+dotnet_diagnostic.SA1206.severity = none
+
+# SA1309: A field name in C# begins with an underscore
+dotnet_diagnostic.SA1309.severity = none
+
+# SA1515: A single-line comment within C# code is not preceded by a blank line
+dotnet_diagnostic.SA1515.severity = none
+
+# SA1600: A C# code element is missing a documentation header
+dotnet_diagnostic.SA1600.severity = none
+
+# SA1601: A C# partial element is missing a documentation header
+dotnet_diagnostic.SA1601.severity = none
+
+# SA1633: A C# code file is missing a standard file header
+dotnet_diagnostic.SA1633.severity = none
diff --git a/.github/skills/aspire/SKILL.md b/.github/skills/aspire/SKILL.md
new file mode 100644
index 0000000..937dffa
--- /dev/null
+++ b/.github/skills/aspire/SKILL.md
@@ -0,0 +1,231 @@
+---
+name: aspire
+description: 'Aspire skill covering the Aspire CLI, AppHost orchestration, service discovery, integrations, MCP server, VS Code extension, Dev Containers, GitHub Codespaces, templates, dashboard, and deployment. Use when the user asks to create, run, debug, configure, deploy, or troubleshoot an Aspire distributed application.'
+---
+
+# Aspire — Polyglot Distributed-App Orchestration
+
+Aspire is a **code-first, polyglot toolchain** for building observable, production-ready distributed applications. It orchestrates containers, executables, and cloud resources from a single AppHost project — regardless of whether the workloads are C#, Python, JavaScript/TypeScript, Go, Java, Rust, Bun, Deno, or PowerShell.
+
+> **Mental model:** The AppHost is a *conductor* — it doesn't play the instruments, it tells every service when to start, how to find each other, and watches for problems.
+
+Detailed reference material lives in the `references/` folder — load on demand.
+
+---
+
+## References
+
+| Reference | When to load |
+|---|---|
+| [CLI Reference](references/cli-reference.md) | Command flags, options, or detailed usage |
+| [MCP Server](references/mcp-server.md) | Setting up MCP for AI assistants, available tools |
+| [Integrations Catalog](references/integrations-catalog.md) | Discovering integrations via MCP tools, wiring patterns |
+| [Polyglot APIs](references/polyglot-apis.md) | Method signatures, chaining options, language-specific patterns |
+| [Architecture](references/architecture.md) | DCP internals, resource model, service discovery, networking, telemetry |
+| [Dashboard](references/dashboard.md) | Dashboard features, standalone mode, GenAI Visualizer |
+| [Deployment](references/deployment.md) | Docker, Kubernetes, Azure Container Apps, App Service |
+| [Testing](references/testing.md) | Integration tests against the AppHost |
+| [Troubleshooting](references/troubleshooting.md) | Diagnostic codes, common errors, and fixes |
+
+---
+
+## 1. Researching Aspire Documentation
+
+The Aspire team ships an **MCP server** that provides documentation tools directly inside your AI assistant. See [MCP Server](references/mcp-server.md) for setup details.
+
+### Aspire CLI 13.2+ (recommended — has built-in docs search)
+
+If running Aspire CLI **13.2 or later** (`aspire --version`), the MCP server includes docs search tools:
+
+| Tool | Description |
+|---|---|
+| `list_docs` | Lists all available documentation from aspire.dev |
+| `search_docs` | Performs weighted lexical search across indexed documentation |
+| `get_doc` | Retrieves a specific document by its slug |
+
+These tools were added in [PR #14028](https://github.com/dotnet/aspire/pull/14028). To update: `aspire update --self --channel daily`.
+
+For more on this approach, see David Pine's post: https://davidpine.dev/posts/aspire-docs-mcp-tools/
+
+### Aspire CLI 13.1 (integration tools only)
+
+On 13.1, the MCP server provides integration lookup but **not** docs search:
+
+| Tool | Description |
+|---|---|
+| `list_integrations` | Lists available Aspire hosting integrations |
+| `get_integration_docs` | Gets documentation for a specific integration package |
+
+For general docs queries on 13.1, use **Context7** as your primary source (see below).
+
+### Fallback: Context7
+
+Use **Context7** (`mcp_context7`) when the Aspire MCP docs tools are unavailable (13.1) or the MCP server isn't running:
+
+**Step 1 — Resolve the library ID** (one-time per session):
+
+Call `mcp_context7_resolve-library-id` with `libraryName: ".NET Aspire"`.
+
+| Rank | Library ID | Use when |
+|---|---|---|
+| 1 | `/microsoft/aspire.dev` | Primary source. Guides, integrations, CLI reference, deployment. |
+| 2 | `/dotnet/aspire` | API internals, source-level implementation details. |
+| 3 | `/communitytoolkit/aspire` | Non-Microsoft polyglot integrations (Go, Java, Node.js, Ollama). |
+
+**Step 2 — Query docs:**
+
+```
+libraryId: "/microsoft/aspire.dev", query: "Python integration AddPythonApp service discovery"
+libraryId: "/communitytoolkit/aspire", query: "Golang Java Node.js community integrations"
+```
+
+### Fallback: GitHub search (when Context7 is also unavailable)
+
+Search the official docs repo on GitHub:
+- **Docs repo:** `microsoft/aspire.dev` — path: `src/frontend/src/content/docs/`
+- **Source repo:** `dotnet/aspire`
+- **Samples repo:** `dotnet/aspire-samples`
+- **Community integrations:** `CommunityToolkit/Aspire`
+
+---
+
+## 2. Prerequisites & Install
+
+| Requirement | Details |
+|---|---|
+| **.NET SDK** | 10.0+ (required even for non-.NET workloads — the AppHost is .NET) |
+| **Container runtime** | Docker Desktop, Podman, or Rancher Desktop |
+| **IDE (optional)** | VS Code + C# Dev Kit, Visual Studio 2022, JetBrains Rider |
+
+```bash
+# Linux / macOS
+curl -sSL https://aspire.dev/install.sh | bash
+
+# Windows PowerShell
+irm https://aspire.dev/install.ps1 | iex
+
+# Verify
+aspire --version
+
+# Install templates
+dotnet new install Aspire.ProjectTemplates
+```
+
+---
+
+## 3. Project Templates
+
+| Template | Command | Description |
+|---|---|---|
+| **aspire-starter** | `aspire new aspire-starter` | ASP.NET Core/Blazor starter + AppHost + tests |
+| **aspire-ts-cs-starter** | `aspire new aspire-ts-cs-starter` | ASP.NET Core/React starter + AppHost |
+| **aspire-py-starter** | `aspire new aspire-py-starter` | FastAPI/React starter + AppHost |
+| **aspire-apphost-singlefile** | `aspire new aspire-apphost-singlefile` | Empty single-file AppHost |
+
+---
+
+## 4. AppHost Quick Start (Polyglot)
+
+The AppHost orchestrates all services. Non-.NET workloads run as containers or executables.
+
+```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
+// Infrastructure
+var redis = builder.AddRedis("cache");
+var postgres = builder.AddPostgres("pg").AddDatabase("catalog");
+
+// .NET API
+var api = builder.AddProject<Projects.CatalogApi>("api")
+    .WithReference(postgres).WithReference(redis);
+
+// Python ML service
+var ml = builder.AddPythonApp("ml-service", "../ml-service", "main.py")
+    .WithHttpEndpoint(targetPort: 8000).WithReference(redis);
+
+// React frontend (Vite)
+var web = builder.AddViteApp("web", "../frontend")
+    .WithHttpEndpoint(targetPort: 5173).WithReference(api);
+
+// Go worker
+var worker = builder.AddGolangApp("worker", "../go-worker")
+    .WithReference(redis);
+
+builder.Build().Run();
+```
+
+For complete API signatures, see [Polyglot APIs](references/polyglot-apis.md).
+
+---
+
+## 5. Core Concepts (Summary)
+
+| Concept | Key point |
+|---|---|
+| **Run vs Publish** | `aspire run` = local dev (DCP engine). `aspire publish` = generate deployment manifests. |
+| **Service discovery** | Automatic via env vars: `ConnectionStrings__<name>`, `services__<name>__http__0` |
+| **Resource lifecycle** | DAG ordering — dependencies start first. `.WaitFor()` gates on health checks. |
+| **Resource types** | `ProjectResource`, `ContainerResource`, `ExecutableResource`, `ParameterResource` |
+| **Integrations** | 144+ across 13 categories. Hosting package (AppHost) + Client package (service). |
+| **Dashboard** | Real-time logs, traces, metrics, GenAI visualizer. Runs automatically with `aspire run`. |
+| **MCP Server** | AI assistants can query running apps and search docs via CLI (STDIO). |
+| **Testing** | `Aspire.Hosting.Testing` — spin up full AppHost in xUnit/MSTest/NUnit. |
+| **Deployment** | Docker, Kubernetes, Azure Container Apps, Azure App Service. |
+
+---
+
+## 6. CLI Quick Reference
+
+Valid commands in Aspire CLI 13.1:
+
+| Command | Description | Status |
+|---|---|---|
+| `aspire new <template>` | Create from template | Stable |
+| `aspire init` | Initialize in existing project | Stable |
+| `aspire run` | Start all resources locally | Stable |
+| `aspire add <integration>` | Add an integration | Stable |
+| `aspire publish` | Generate deployment manifests | Preview |
+| `aspire config` | Manage configuration settings | Stable |
+| `aspire cache` | Manage disk cache | Stable |
+| `aspire deploy` | Deploy to defined targets | Preview |
+| `aspire do <step>` | Execute a pipeline step | Preview |
+| `aspire update` | Update integrations (or `--self` for CLI) | Preview |
+| `aspire mcp init` | Configure MCP for AI assistants | Stable |
+| `aspire mcp start` | Start the MCP server | Stable |
+
+Full command reference with flags: [CLI Reference](references/cli-reference.md).
+
+---
+
+## 7. Common Patterns
+
+### Adding a new service
+
+1. Create your service directory (any language)
+2. Add to AppHost: `Add*App()` or `AddProject<T>()`
+3. Wire dependencies: `.WithReference()`
+4. Gate on health: `.WaitFor()` if needed
+5. Run: `aspire run`
+
+### Migrating from Docker Compose
+
+1. `aspire new aspire-apphost-singlefile` (empty AppHost)
+2. Replace each `docker-compose` service with an Aspire resource
+3. `depends_on` → `.WithReference()` + `.WaitFor()`
+4. `ports` → `.WithHttpEndpoint()`
+5. `environment` → `.WithEnvironment()` or `.WithReference()`
+
+---
+
+## 8. Key URLs
+
+| Resource | URL |
+|---|---|
+| **Documentation** | https://aspire.dev |
+| **Runtime repo** | https://github.com/dotnet/aspire |
+| **Docs repo** | https://github.com/microsoft/aspire.dev |
+| **Samples** | https://github.com/dotnet/aspire-samples |
+| **Community Toolkit** | https://github.com/CommunityToolkit/Aspire |
+| **Dashboard image** | `mcr.microsoft.com/dotnet/aspire-dashboard` |
+| **Discord** | https://aka.ms/aspire/discord |
+| **Reddit** | https://www.reddit.com/r/aspiredotdev/ |
diff --git a/.github/skills/aspire/references/architecture.md b/.github/skills/aspire/references/architecture.md
new file mode 100644
index 0000000..15ebbb5
--- /dev/null
+++ b/.github/skills/aspire/references/architecture.md
@@ -0,0 +1,341 @@
+# Architecture — Deep Dive
+
+This reference covers Aspire's internal architecture: the DCP engine, resource model, service discovery, networking, telemetry, and the eventing system.
+
+---
+
+## Developer Control Plane (DCP)
+
+The DCP is the **runtime engine** that Aspire uses in `aspire run` mode. Key facts:
+
+- Written in **Go** (not .NET)
+- Exposes a **Kubernetes-compatible API server** (local only, not a real K8s cluster)
+- Manages resource lifecycle: create, start, health-check, stop, restart
+- Runs containers via the local container runtime (Docker, Podman, Rancher)
+- Runs executables as native OS processes
+- Handles networking via a proxy layer with automatic port assignment
+- Provides the foundation for the Aspire Dashboard's real-time data
+
+### DCP vs Kubernetes
+
+| Aspect | DCP (local dev) | Kubernetes (production) |
+|---|---|---|
+| API | Kubernetes-compatible | Full Kubernetes API |
+| Scope | Single machine | Cluster |
+| Networking | Local proxy, auto ports | Service mesh, ingress |
+| Storage | Local volumes | PVCs, cloud storage |
+| Purpose | Developer inner loop | Production deployment |
+
+The Kubernetes-compatible API means Aspire understands the same resource abstractions, but DCP is **not** a Kubernetes distribution — it's a lightweight local runtime.
+
+---
+
+## Resource Model
+
+Everything in Aspire is a **resource**. The resource model is hierarchical:
+
+### Type hierarchy
+
+```
+IResource (interface)
+└── Resource (abstract base)
+    ├── ProjectResource          — .NET project reference
+    ├── ContainerResource        — Docker/OCI container
+    ├── ExecutableResource       — Native process (polyglot apps)
+    ├── ParameterResource        — Config value or secret
+    └── Infrastructure resources
+        ├── RedisResource
+        ├── PostgresServerResource
+        ├── MongoDBServerResource
+        ├── SqlServerResource
+        ├── RabbitMQServerResource
+        ├── KafkaServerResource
+        └── ... (one per integration)
+```
+
+### Resource properties
+
+Every resource has:
+- **Name** — unique identifier within the AppHost
+- **State** — lifecycle state (Starting, Running, FailedToStart, Stopping, Stopped, etc.)
+- **Annotations** — metadata attached to the resource
+- **Endpoints** — network endpoints exposed by the resource
+- **Environment variables** — injected into the process/container
+
+### Annotations
+
+Annotations are metadata bags attached to resources. Common built-in annotations:
+
+| Annotation | Purpose |
+|---|---|
+| `EndpointAnnotation` | Defines an HTTP/HTTPS/TCP endpoint |
+| `EnvironmentCallbackAnnotation` | Deferred env var resolution |
+| `HealthCheckAnnotation` | Health check configuration |
+| `ContainerImageAnnotation` | Docker image details |
+| `VolumeAnnotation` | Volume mount configuration |
+| `CommandLineArgsCallbackAnnotation` | Dynamic CLI arguments |
+| `ManifestPublishingCallbackAnnotation` | Custom publish behavior |
+
+### Resource lifecycle states
+
+```
+NotStarted → Starting → Running → Stopping → Stopped
+                 ↓                     ↓
+          FailedToStart           RuntimeUnhealthy
+                                       ↓
+                                  Restarting → Running
+```
+
+### DAG (Directed Acyclic Graph)
+
+Resources form a dependency graph. Aspire starts resources in topological order:
+
+```
+PostgreSQL ──→ API ──→ Frontend
+Redis ────────↗
+RabbitMQ ──→ Worker
+```
+
+1. PostgreSQL, Redis, and RabbitMQ start first (no dependencies)
+2. API starts after PostgreSQL and Redis are healthy
+3. Frontend starts after API is healthy
+4. Worker starts after RabbitMQ is healthy
+
+`.WaitFor()` adds a health-check gate to the dependency edge. Without it, the dependency starts but the downstream doesn't wait for health.
+
+---
+
+## Service Discovery
+
+Aspire injects environment variables into each resource so services can find each other. No service registry or DNS is needed — it's pure environment variable injection.
+
+### Connection strings
+
+For databases, caches, and message brokers:
+
+```
+ConnectionStrings__<resource-name>=<connection-string>
+```
+
+Examples:
+```
+ConnectionStrings__cache=localhost:6379
+ConnectionStrings__catalog=Host=localhost;Port=5432;Database=catalog;Username=postgres;Password=...
+ConnectionStrings__messaging=amqp://guest:guest@localhost:5672
+```
+
+### Service endpoints
+
+For HTTP/HTTPS services:
+
+```
+services__<resource-name>__<scheme>__0=<url>
+```
+
+Examples:
+```
+services__api__http__0=http://localhost:5234
+services__api__https__0=https://localhost:7234
+services__ml__http__0=http://localhost:8000
+```
+
+### How .WithReference() works
+
+```csharp
+var redis = builder.AddRedis("cache");
+var api = builder.AddProject<Projects.Api>("api")
+    .WithReference(redis);
+```
+
+This does:
+1. Adds `ConnectionStrings__cache=localhost:<auto-port>` to the API's environment
+2. Creates a dependency edge in the DAG (API depends on Redis)
+3. In the API service, `builder.Configuration.GetConnectionString("cache")` returns the connection string
+
+### Cross-language service discovery
+
+All languages use the same env var pattern:
+
+| Language | How to read |
+|---|---|
+| C# | `builder.Configuration.GetConnectionString("cache")` |
+| Python | `os.environ["ConnectionStrings__cache"]` |
+| JavaScript | `process.env.ConnectionStrings__cache` |
+| Go | `os.Getenv("ConnectionStrings__cache")` |
+| Java | `System.getenv("ConnectionStrings__cache")` |
+| Rust | `std::env::var("ConnectionStrings__cache")` |
+
+---
+
+## Networking
+
+### Proxy architecture
+
+In `aspire run` mode, DCP runs a reverse proxy for each exposed endpoint:
+
+```
+Browser → Proxy (auto-assigned port) → Actual Service (target port)
+```
+
+- **port** (the external port) — auto-assigned by DCP unless overridden
+- **targetPort** — the port your service actually listens on
+- All inter-service traffic goes through the proxy for observability
+
+```csharp
+// Let DCP auto-assign the external port, service listens on 8000
+builder.AddPythonApp("ml", "../ml", "main.py")
+    .WithHttpEndpoint(targetPort: 8000);
+
+// Fix the external port to 3000
+builder.AddViteApp("web", "../frontend")
+    .WithHttpEndpoint(port: 3000, targetPort: 5173);
+```
+
+### Endpoint types
+
+```csharp
+// HTTP endpoint
+.WithHttpEndpoint(port?, targetPort?, name?)
+
+// HTTPS endpoint
+.WithHttpsEndpoint(port?, targetPort?, name?)
+
+// Generic endpoint (TCP, custom schemes)
+.WithEndpoint(port?, targetPort?, scheme?, name?, isExternal?)
+
+// Mark endpoints as externally accessible (for deployment)
+.WithExternalHttpEndpoints()
+```
+
+---
+
+## Telemetry (OpenTelemetry)
+
+Aspire configures OpenTelemetry automatically for .NET services. For non-.NET services, you configure OpenTelemetry manually, pointing at the DCP collector.
+
+### What's auto-configured (.NET services)
+
+- **Distributed tracing** — HTTP client/server spans, database spans, messaging spans
+- **Metrics** — Runtime metrics, HTTP metrics, custom metrics
+- **Structured logging** — Logs correlated with trace context
+- **Exporter** — OTLP exporter pointing at the Aspire Dashboard
+
+### Configuring non-.NET services
+
+The DCP exposes an OTLP endpoint. Set these env vars in your non-.NET service:
+
+```
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
+OTEL_SERVICE_NAME=<your-service-name>
+```
+
+Aspire auto-injects `OTEL_EXPORTER_OTLP_ENDPOINT` via `.WithReference()` for the dashboard collector.
+
+### ServiceDefaults pattern
+
+The `ServiceDefaults` project is a shared configuration library that standardizes:
+- OpenTelemetry setup (tracing, metrics, logging)
+- Health check endpoints (`/health`, `/alive`)
+- Resilience policies (retries, circuit breakers via Polly)
+
+```csharp
+// In each .NET service's Program.cs
+builder.AddServiceDefaults();   // adds OTel, health checks, resilience
+// ... other service config ...
+app.MapDefaultEndpoints();      // maps /health and /alive
+```
+
+---
+
+## Health Checks
+
+### Built-in health checks
+
+Every integration adds health checks automatically on the client side:
+- Redis: `PING` command
+- PostgreSQL: `SELECT 1`
+- MongoDB: `ping` command
+- RabbitMQ: Connection check
+- etc.
+
+### WaitFor vs WithReference
+
+```csharp
+// WithReference: wires connection string + creates dependency edge
+// (downstream may start before dependency is healthy)
+.WithReference(db)
+
+// WaitFor: gates on health check — downstream won't start until healthy
+.WaitFor(db)
+
+// Typical pattern: both
+.WithReference(db).WaitFor(db)
+```
+
+### Custom health checks
+
+```csharp
+var api = builder.AddProject<Projects.Api>("api")
+    .WithHealthCheck("ready", "/health/ready")
+    .WithHealthCheck("live", "/health/live");
+```
+
+---
+
+## Eventing System
+
+The AppHost supports lifecycle events for reacting to resource state changes:
+
+```csharp
+builder.Eventing.Subscribe<ResourceReadyEvent>("api", (evt, ct) =>
+{
+    // Fires when "api" resource becomes healthy
+    Console.WriteLine($"API is ready at {evt.Resource.Name}");
+    return Task.CompletedTask;
+});
+
+builder.Eventing.Subscribe<BeforeResourceStartedEvent>("db", async (evt, ct) =>
+{
+    // Run database migrations before the DB resource is marked as started
+    await RunMigrations();
+});
+```
+
+### Available events
+
+| Event | When |
+|---|---|
+| `BeforeResourceStartedEvent` | Before a resource starts |
+| `ResourceReadyEvent` | Resource is healthy and ready |
+| `ResourceStateChangedEvent` | Any state transition |
+| `BeforeStartEvent` | Before the entire application starts |
+| `AfterEndpointsAllocatedEvent` | After all ports are assigned |
+
+---
+
+## Configuration
+
+### Parameters
+
+```csharp
+// Plain parameter
+var apiKey = builder.AddParameter("api-key");
+
+// Secret parameter (prompted at run, not logged)
+var dbPassword = builder.AddParameter("db-password", secret: true);
+
+// Use in resources
+var api = builder.AddProject<Projects.Api>("api")
+    .WithEnvironment("API_KEY", apiKey);
+
+var db = builder.AddPostgres("db", password: dbPassword);
+```
+
+### Configuration sources
+
+Parameters are resolved from (in priority order):
+1. Command-line arguments
+2. Environment variables
+3. User secrets (`dotnet user-secrets`)
+4. `appsettings.json` / `appsettings.{Environment}.json`
+5. Interactive prompt (for secrets during `aspire run`)
diff --git a/.github/skills/aspire/references/cli-reference.md b/.github/skills/aspire/references/cli-reference.md
new file mode 100644
index 0000000..29f7003
--- /dev/null
+++ b/.github/skills/aspire/references/cli-reference.md
@@ -0,0 +1,307 @@
+# CLI Reference — Complete Command Reference
+
+The Aspire CLI (`aspire`) is the primary interface for creating, running, and publishing distributed applications. It is cross-platform and installed standalone (not coupled to the .NET CLI, though `dotnet` commands also work).
+
+**Tested against:** Aspire CLI 13.1.0
+
+---
+
+## Installation
+
+```bash
+# Linux / macOS
+curl -sSL https://aspire.dev/install.sh | bash
+
+# Windows PowerShell
+irm https://aspire.dev/install.ps1 | iex
+
+# Verify
+aspire --version
+
+# Update the CLI itself
+aspire update --self
+```
+
+---
+
+## Global Options
+
+All commands support these options:
+
+| Option                | Description                                    |
+| --------------------- | ---------------------------------------------- |
+| `-d, --debug`         | Enable debug logging to the console            |
+| `--non-interactive`   | Disable all interactive prompts and spinners   |
+| `--wait-for-debugger` | Wait for a debugger to attach before executing |
+| `-?, -h, --help`      | Show help and usage information                |
+| `--version`           | Show version information                       |
+
+---
+
+## Command Reference
+
+### `aspire new`
+
+Create a new project from a template.
+
+```bash
+aspire new [<template>] [options]
+
+# Options:
+#   -n, --name <name>        Project name
+#   -o, --output <dir>       Output directory
+#   -s, --source <source>    NuGet source for templates
+#   -v, --version <version>  Version of templates to use
+#   --channel <channel>      Channel (stable, daily)
+
+# Examples:
+aspire new aspire-starter
+aspire new aspire-starter -n MyApp -o ./my-app
+aspire new aspire-ts-cs-starter
+aspire new aspire-py-starter
+aspire new aspire-apphost-singlefile
+```
+
+Available templates:
+
+- `aspire-starter` — ASP.NET Core/Blazor starter + AppHost + tests
+- `aspire-ts-cs-starter` — ASP.NET Core/React + AppHost
+- `aspire-py-starter` — FastAPI/React + AppHost
+- `aspire-apphost-singlefile` — Empty single-file AppHost
+
+### `aspire init`
+
+Initialize Aspire in an existing project or solution.
+
+```bash
+aspire init [options]
+
+# Options:
+#   -s, --source <source>    NuGet source for templates
+#   -v, --version <version>  Version of templates to use
+#   --channel <channel>      Channel (stable, daily)
+
+# Example:
+cd my-existing-solution
+aspire init
+```
+
+Adds AppHost and ServiceDefaults projects to an existing solution. Interactive prompts guide you through selecting which projects to orchestrate.
+
+### `aspire run`
+
+Start all resources locally using the DCP (Developer Control Plane).
+
+```bash
+aspire run [options] [-- <additional arguments>]
+
+# Options:
+#   --project <path>       Path to AppHost project file
+
+# Examples:
+aspire run
+aspire run --project ./src/MyApp.AppHost
+```
+
+Behavior:
+
+1. Builds the AppHost project
+2. Starts the DCP engine
+3. Creates resources in dependency order (DAG)
+4. Waits for health checks on gated resources
+5. Opens the dashboard in the default browser
+6. Streams logs to the terminal
+
+Press `Ctrl+C` to gracefully stop all resources.
+
+### `aspire add`
+
+Add a hosting integration to the AppHost.
+
+```bash
+aspire add [<integration>] [options]
+
+# Options:
+#   --project <path>         Target project file
+#   -v, --version <version>  Version of integration to add
+#   -s, --source <source>    NuGet source for integration
+
+# Examples:
+aspire add redis
+aspire add postgresql
+aspire add mongodb
+```
+
+### `aspire publish` (Preview)
+
+Generate deployment manifests from the AppHost resource model.
+
+```bash
+aspire publish [options] [-- <additional arguments>]
+
+# Options:
+#   --project <path>                   Path to AppHost project file
+#   -o, --output-path <path>           Output directory (default: ./aspire-output)
+#   --log-level <level>                Log level (trace, debug, information, warning, error, critical)
+#   -e, --environment <env>            Environment (default: Production)
+#   --include-exception-details        Include stack traces in pipeline logs
+
+# Examples:
+aspire publish
+aspire publish --output-path ./deploy
+aspire publish -e Staging
+```
+
+### `aspire config`
+
+Manage Aspire configuration settings.
+
+```bash
+aspire config <subcommand>
+
+# Subcommands:
+#   get <key>              Get a configuration value
+#   set <key> <value>      Set a configuration value
+#   list                   List all configuration values
+#   delete <key>           Delete a configuration value
+
+# Examples:
+aspire config list
+aspire config set telemetry.enabled false
+aspire config get telemetry.enabled
+aspire config delete telemetry.enabled
+```
+
+### `aspire cache`
+
+Manage disk cache for CLI operations.
+
+```bash
+aspire cache <subcommand>
+
+# Subcommands:
+#   clear                  Clear all cache entries
+
+# Example:
+aspire cache clear
+```
+
+### `aspire deploy` (Preview)
+
+Deploy the contents of an Aspire apphost to its defined deployment targets.
+
+```bash
+aspire deploy [options] [-- <additional arguments>]
+
+# Options:
+#   --project <path>                   Path to AppHost project file
+#   -o, --output-path <path>           Output path for deployment artifacts
+#   --log-level <level>                Log level (trace, debug, information, warning, error, critical)
+#   -e, --environment <env>            Environment (default: Production)
+#   --include-exception-details        Include stack traces in pipeline logs
+#   --clear-cache                      Clear deployment cache for current environment
+
+# Example:
+aspire deploy --project ./src/MyApp.AppHost
+```
+
+### `aspire do` (Preview)
+
+Execute a specific pipeline step and its dependencies.
+
+```bash
+aspire do <step> [options] [-- <additional arguments>]
+
+# Options:
+#   --project <path>                   Path to AppHost project file
+#   -o, --output-path <path>           Output path for artifacts
+#   --log-level <level>                Log level (trace, debug, information, warning, error, critical)
+#   -e, --environment <env>            Environment (default: Production)
+#   --include-exception-details        Include stack traces in pipeline logs
+
+# Example:
+aspire do build-images --project ./src/MyApp.AppHost
+```
+
+### `aspire update` (Preview)
+
+Update integrations in the Aspire project, or update the CLI itself.
+
+```bash
+aspire update [options]
+
+# Options:
+#   --project <path>       Path to AppHost project file
+#   --self                 Update the Aspire CLI itself to the latest version
+#   --channel <channel>    Channel to update to (stable, daily)
+
+# Examples:
+aspire update                          # Update project integrations
+aspire update --self                   # Update the CLI itself
+aspire update --self --channel daily   # Update CLI to daily build
+```
+
+### `aspire mcp`
+
+Manage the MCP (Model Context Protocol) server.
+
+```bash
+aspire mcp <subcommand>
+
+# Subcommands:
+#   init    Initialize MCP server configuration for detected agent environments
+#   start   Start the MCP server
+```
+
+#### `aspire mcp init`
+
+```bash
+aspire mcp init
+
+# Interactive — detects your AI environment and creates config files.
+# Supported environments:
+# - VS Code (GitHub Copilot)
+# - Copilot CLI
+# - Claude Code
+# - OpenCode
+```
+
+Generates the appropriate configuration file for your detected AI tool.
+See [MCP Server](mcp-server.md) for details.
+
+#### `aspire mcp start`
+
+```bash
+aspire mcp start
+
+# Starts the MCP server using STDIO transport.
+# This is typically invoked by your AI tool, not run manually.
+```
+
+---
+
+## Commands That Do NOT Exist
+
+The following commands are **not valid** in Aspire CLI 13.1. Use alternatives:
+
+| Invalid Command | Alternative                                                          |
+| --------------- | -------------------------------------------------------------------- |
+| `aspire build`  | Use `dotnet build ./AppHost`                                         |
+| `aspire test`   | Use `dotnet test ./Tests`                                            |
+| `aspire dev`    | Use `aspire run` (includes file watching)                            |
+| `aspire list`   | Use `aspire new --help` for templates, `aspire add` for integrations |
+
+---
+
+## .NET CLI equivalents
+
+The `dotnet` CLI can perform some Aspire tasks:
+
+| Aspire CLI                  | .NET CLI Equivalent              |
+| --------------------------- | -------------------------------- |
+| `aspire new aspire-starter` | `dotnet new aspire-starter`      |
+| `aspire run`                | `dotnet run --project ./AppHost` |
+| N/A                         | `dotnet build ./AppHost`         |
+| N/A                         | `dotnet test ./Tests`            |
+
+The Aspire CLI adds value with `publish`, `deploy`, `add`, `mcp`, `config`, `cache`, `do`, and `update` — commands that have no direct `dotnet` equivalent.
diff --git a/.github/skills/aspire/references/dashboard.md b/.github/skills/aspire/references/dashboard.md
new file mode 100644
index 0000000..6cc55b1
--- /dev/null
+++ b/.github/skills/aspire/references/dashboard.md
@@ -0,0 +1,226 @@
+# Dashboard — Complete Reference
+
+The Aspire Dashboard provides real-time observability for all resources in your distributed application. It launches automatically with `aspire run` and can also run standalone.
+
+---
+
+## Features
+
+### Resources view
+
+Displays all resources (projects, containers, executables) with:
+
+- **Name** and **type** (Project, Container, Executable)
+- **State** (Starting, Running, Stopped, FailedToStart, etc.)
+- **Start time** and **uptime**
+- **Endpoints** — clickable URLs for each exposed endpoint
+- **Source** — project path, container image, or executable path
+- **Actions** — Stop, Start, Restart buttons
+
+### Console logs
+
+Aggregated raw stdout/stderr from all resources:
+
+- Filter by resource name
+- Search within logs
+- Auto-scroll with pause
+- Color-coded by resource
+
+### Structured logs
+
+Application-level structured logs (via ILogger, OpenTelemetry):
+
+- **Filterable** by resource, log level, category, message content
+- **Expandable** — click to see full log entry with all properties
+- **Correlated** with traces — click to jump to the related trace
+- Supports .NET ILogger structured logging properties
+- Supports OpenTelemetry log signals from any language
+
+### Distributed traces
+
+End-to-end request traces across all services:
+
+- **Waterfall view** — shows the full call chain with timing
+- **Span details** — HTTP method, URL, status code, duration
+- **Database spans** — SQL queries, connection details
+- **Messaging spans** — queue operations, topic publishes
+- **Error highlighting** — failed spans shown in red
+- **Cross-service correlation** — trace context propagated automatically for .NET; manual for other languages
+
+### Metrics
+
+Real-time and historical metrics:
+
+- **Runtime metrics** — CPU, memory, GC, thread pool
+- **HTTP metrics** — request rate, error rate, latency percentiles
+- **Custom metrics** — any metrics your services emit via OpenTelemetry
+- **Chartable** — time-series graphs for each metric
+
+### GenAI Visualizer
+
+For applications using AI/LLM integrations:
+
+- **Token usage** — prompt tokens, completion tokens, total tokens per request
+- **Prompt/completion pairs** — see the exact prompt sent and response received
+- **Model metadata** — which model, temperature, max tokens
+- **Latency** — time per AI call
+- Requires services to emit [GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) via OpenTelemetry
+
+---
+
+## Dashboard URL
+
+By default, the dashboard runs on an auto-assigned port. Find it:
+
+- In the terminal output when `aspire run` starts
+- Via MCP: `list_resources` tool
+- Override with `--dashboard-port`:
+
+```bash
+aspire run --dashboard-port 18888
+```
+
+---
+
+## Standalone Dashboard
+
+Run the dashboard without an AppHost — useful for existing applications that already emit OpenTelemetry:
+
+```bash
+docker run --rm -d \
+  -p 18888:18888 \
+  -p 4317:18889 \
+  mcr.microsoft.com/dotnet/aspire-dashboard:latest
+```
+
+| Port             | Purpose                                                      |
+| ---------------- | ------------------------------------------------------------ |
+| `18888`          | Dashboard web UI                                             |
+| `4317` → `18889` | OTLP gRPC receiver (standard OTel port → dashboard internal) |
+
+### Configure your services
+
+Point your OpenTelemetry exporters at the dashboard:
+
+```bash
+# Environment variables for any language's OpenTelemetry SDK
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
+OTEL_SERVICE_NAME=my-service
+```
+
+### Docker Compose example
+
+```yaml
+services:
+  dashboard:
+    image: mcr.microsoft.com/dotnet/aspire-dashboard:latest
+    ports:
+      - "18888:18888"
+      - "4317:18889"
+
+  api:
+    build: ./api
+    environment:
+      - OTEL_EXPORTER_OTLP_ENDPOINT=http://dashboard:18889
+      - OTEL_SERVICE_NAME=api
+
+  worker:
+    build: ./worker
+    environment:
+      - OTEL_EXPORTER_OTLP_ENDPOINT=http://dashboard:18889
+      - OTEL_SERVICE_NAME=worker
+```
+
+---
+
+## Dashboard configuration
+
+### Authentication
+
+The standalone dashboard supports authentication via browser tokens:
+
+```bash
+docker run --rm -d \
+  -p 18888:18888 \
+  -p 4317:18889 \
+  -e DASHBOARD__FRONTEND__AUTHMODE=BrowserToken \
+  -e DASHBOARD__FRONTEND__BROWSERTOKEN__TOKEN=my-secret-token \
+  mcr.microsoft.com/dotnet/aspire-dashboard:latest
+```
+
+### OTLP configuration
+
+```bash
+# Accept OTLP over gRPC (default)
+-e DASHBOARD__OTLP__GRPC__ENDPOINT=http://0.0.0.0:18889
+
+# Accept OTLP over HTTP
+-e DASHBOARD__OTLP__HTTP__ENDPOINT=http://0.0.0.0:18890
+
+# Require API key for OTLP
+-e DASHBOARD__OTLP__AUTHMODE=ApiKey
+-e DASHBOARD__OTLP__PRIMARYAPIKEY=my-api-key
+```
+
+### Resource limits
+
+```bash
+# Limit log entries retained
+-e DASHBOARD__TELEMETRYLIMITS__MAXLOGCOUNT=10000
+
+# Limit trace entries retained
+-e DASHBOARD__TELEMETRYLIMITS__MAXTRACECOUNT=10000
+
+# Limit metric data points
+-e DASHBOARD__TELEMETRYLIMITS__MAXMETRICCOUNT=50000
+```
+
+---
+
+## Copilot integration
+
+The dashboard integrates with GitHub Copilot in VS Code:
+
+- Ask questions about resource status
+- Query logs and traces in natural language
+- The MCP server (see [MCP Server](mcp-server.md)) provides the bridge
+
+---
+
+## Non-.NET service telemetry
+
+For non-.NET services to appear in the dashboard, they must emit OpenTelemetry signals. Aspire auto-injects the OTLP endpoint env var when using `.WithReference()`:
+
+### Python (OpenTelemetry SDK)
+
+```python
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+import os
+
+# Aspire injects OTEL_EXPORTER_OTLP_ENDPOINT automatically
+endpoint = os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT", "http://localhost:4317")
+
+provider = TracerProvider()
+provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter(endpoint=endpoint)))
+trace.set_tracer_provider(provider)
+```
+
+### JavaScript (OpenTelemetry SDK)
+
+```javascript
+const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
+const { OTLPTraceExporter } = require("@opentelemetry/exporter-trace-otlp-grpc");
+
+const provider = new NodeTracerProvider();
+provider.addSpanProcessor(
+  new BatchSpanProcessor(
+    new OTLPTraceExporter({
+      url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || "http://localhost:4317",
+    })
+  )
+);
+provider.register();
+```
diff --git a/.github/skills/aspire/references/deployment.md b/.github/skills/aspire/references/deployment.md
new file mode 100644
index 0000000..bb1521a
--- /dev/null
+++ b/.github/skills/aspire/references/deployment.md
@@ -0,0 +1,237 @@
+# Deployment — Complete Reference
+
+Aspire separates **orchestration** (what to run) from **deployment** (where to run it). The `aspire publish` command translates your AppHost resource model into deployment manifests for your target platform.
+
+---
+
+## Publish vs Deploy
+
+| Concept | What it does |
+|---|---|
+| **`aspire publish`** | Generates deployment artifacts (Dockerfiles, Helm charts, Bicep, etc.) |
+| **Deploy** | You run the generated artifacts through your CI/CD pipeline |
+
+Aspire does NOT deploy directly. It generates the manifests — you deploy them.
+
+---
+
+## Supported Targets
+
+### Docker
+
+**Package:** `Aspire.Hosting.Docker`
+
+```bash
+aspire publish -p docker -o ./docker-output
+```
+
+Generates:
+- `docker-compose.yml` — service definitions matching your AppHost
+- `Dockerfile` for each .NET project
+- Environment variable configuration
+- Volume mounts
+- Network configuration
+
+```csharp
+// AppHost configuration for Docker publishing
+var api = builder.AddProject<Projects.Api>("api")
+    .PublishAsDockerFile();  // override default publish behavior
+```
+
+### Kubernetes
+
+**Package:** `Aspire.Hosting.Kubernetes`
+
+```bash
+aspire publish -p kubernetes -o ./k8s-output
+```
+
+Generates:
+- Kubernetes YAML manifests (Deployments, Services, ConfigMaps, Secrets)
+- Helm chart (optional)
+- Ingress configuration
+- Resource limits based on AppHost configuration
+
+```csharp
+// AppHost: customize K8s publishing
+var api = builder.AddProject<Projects.Api>("api")
+    .WithReplicas(3)                    // maps to K8s replicas
+    .WithExternalHttpEndpoints();       // maps to Ingress/LoadBalancer
+```
+
+### Azure Container Apps
+
+**Package:** `Aspire.Hosting.Azure.AppContainers`
+
+```bash
+aspire publish -p azure -o ./azure-output
+```
+
+Generates:
+- Bicep templates for Azure Container Apps Environment
+- Container App definitions for each service
+- Azure Container Registry configuration
+- Managed identity configuration
+- Dapr components (if using Dapr integration)
+- VNET configuration
+
+```csharp
+// AppHost: Azure-specific configuration
+var api = builder.AddProject<Projects.Api>("api")
+    .WithExternalHttpEndpoints()        // maps to external ingress
+    .WithReplicas(3);                   // maps to min replicas
+
+// Azure resources are auto-provisioned
+var storage = builder.AddAzureStorage("storage");   // creates Storage Account
+var cosmos = builder.AddAzureCosmosDB("cosmos");    // creates Cosmos DB account
+var sb = builder.AddAzureServiceBus("messaging");   // creates Service Bus namespace
+```
+
+### Azure App Service
+
+**Package:** `Aspire.Hosting.Azure.AppService`
+
+```bash
+aspire publish -p appservice -o ./appservice-output
+```
+
+Generates:
+- Bicep templates for App Service Plans and Web Apps
+- Connection string configuration
+- Application settings
+
+---
+
+## Resource model to deployment mapping
+
+| AppHost concept | Docker Compose | Kubernetes | Azure Container Apps |
+|---|---|---|---|
+| `AddProject<T>()` | `service` with Dockerfile | `Deployment` + `Service` | `Container App` |
+| `AddContainer()` | `service` with `image:` | `Deployment` + `Service` | `Container App` |
+| `AddRedis()` | `service: redis` | `StatefulSet` | Managed Redis |
+| `AddPostgres()` | `service: postgres` | `StatefulSet` | Azure PostgreSQL |
+| `.WithReference()` | `environment:` vars | `ConfigMap` / `Secret` | App settings |
+| `.WithReplicas(n)` | `deploy: replicas: n` | `replicas: n` | `minReplicas: n` |
+| `.WithVolume()` | `volumes:` | `PersistentVolumeClaim` | Azure Files |
+| `.WithHttpEndpoint()` | `ports:` | `Service` port | Ingress |
+| `.WithExternalHttpEndpoints()` | `ports:` (host) | `Ingress` / `LoadBalancer` | External ingress |
+| `AddParameter(secret: true)` | `.env` file | `Secret` | Key Vault reference |
+
+---
+
+## CI/CD integration
+
+### GitHub Actions example
+
+```yaml
+name: Deploy
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: '10.0.x'
+
+      - name: Install Aspire CLI
+        run: curl -sSL https://aspire.dev/install.sh | bash
+
+      - name: Generate manifests
+        run: aspire publish -p azure -o ./deploy
+
+      - name: Deploy to Azure
+        uses: azure/arm-deploy@v2
+        with:
+          template: ./deploy/main.bicep
+          parameters: ./deploy/main.parameters.json
+```
+
+### Azure DevOps example
+
+```yaml
+trigger:
+  branches:
+    include: [main]
+
+pool:
+  vmImage: 'ubuntu-latest'
+
+steps:
+  - task: UseDotNet@2
+    inputs:
+      version: '10.0.x'
+
+  - script: curl -sSL https://aspire.dev/install.sh | bash
+    displayName: 'Install Aspire CLI'
+
+  - script: aspire publish -p azure -o $(Build.ArtifactStagingDirectory)/deploy
+    displayName: 'Generate deployment manifests'
+
+  - task: AzureResourceManagerTemplateDeployment@3
+    inputs:
+      deploymentScope: 'Resource Group'
+      templateLocation: '$(Build.ArtifactStagingDirectory)/deploy/main.bicep'
+```
+
+---
+
+## Environment-specific configuration
+
+### Using parameters for secrets
+
+```csharp
+// AppHost
+var dbPassword = builder.AddParameter("db-password", secret: true);
+var postgres = builder.AddPostgres("db", password: dbPassword);
+```
+
+In deployment:
+- **Docker:** Loaded from `.env` file
+- **Kubernetes:** Loaded from `Secret` resource
+- **Azure:** Loaded from Key Vault via managed identity
+
+### Conditional resources
+
+```csharp
+// Use Azure services in production, emulators locally
+if (builder.ExecutionContext.IsPublishMode)
+{
+    var cosmos = builder.AddAzureCosmosDB("cosmos");    // real Azure resource
+}
+else
+{
+    var cosmos = builder.AddAzureCosmosDB("cosmos")
+        .RunAsEmulator();                                // local emulator
+}
+```
+
+---
+
+## Dev Containers & GitHub Codespaces
+
+Aspire templates include `.devcontainer/` configuration:
+
+```json
+{
+  "name": "Aspire App",
+  "image": "mcr.microsoft.com/devcontainers/dotnet:10.0",
+  "features": {
+    "ghcr.io/devcontainers/features/docker-in-docker:2": {},
+    "ghcr.io/devcontainers/features/node:1": {}
+  },
+  "postCreateCommand": "curl -sSL https://aspire.dev/install.sh | bash",
+  "forwardPorts": [18888],
+  "portsAttributes": {
+    "18888": { "label": "Aspire Dashboard" }
+  }
+}
+```
+
+Port forwarding works automatically in Codespaces — the dashboard and all service endpoints are accessible via forwarded URLs.
diff --git a/.github/skills/aspire/references/integrations-catalog.md b/.github/skills/aspire/references/integrations-catalog.md
new file mode 100644
index 0000000..0e8fbb6
--- /dev/null
+++ b/.github/skills/aspire/references/integrations-catalog.md
@@ -0,0 +1,68 @@
+# Integrations Catalog
+
+Aspire has **144+ integrations** across 13 categories. Rather than maintaining a static list, use the MCP tools to get live, up-to-date integration data.
+
+---
+
+## Discovering integrations (MCP tools)
+
+The Aspire MCP server provides two tools for integration discovery — these work on **all CLI versions** (13.1+) and do **not** require a running AppHost.
+
+| Tool                   | What it does                                                                                             | When to use                                                                                 |
+| ---------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `list_integrations`    | Returns all available Aspire hosting integrations with their NuGet package IDs                           | "What integrations are available for databases?" / "Show me all Redis-related integrations" |
+| `get_integration_docs` | Retrieves detailed documentation for a specific integration package (setup, configuration, code samples) | "How do I configure PostgreSQL?" / "Show me the docs for `Aspire.Hosting.Redis`"            |
+
+### Workflow
+
+1. **Browse** — Call `list_integrations` to see what's available. Filter results by category or keyword.
+2. **Deep dive** — Call `get_integration_docs` with the package ID (e.g., `Aspire.Hosting.Redis`) and version (e.g., `9.0.0`) to get full setup instructions.
+3. **Add** — Run `aspire add <integration>` to install the hosting package into your AppHost.
+
+> **Tip:** These tools return the same data as the [official integrations gallery](https://aspire.dev/integrations/gallery/). Prefer them over static docs — integrations are added frequently.
+
+---
+
+## Integration pattern
+
+Every integration follows a two-package pattern:
+
+- **Hosting package** (`Aspire.Hosting.*`) — adds the resource to the AppHost
+- **Client package** (`Aspire.*`) — configures the client SDK in your service with health checks, telemetry, and retries
+- **Community Toolkit** (`CommunityToolkit.Aspire.*`) — community-maintained integrations from [Aspire Community Toolkit](https://github.com/CommunityToolkit/Aspire)
+
+```csharp
+// === AppHost (hosting side) ===
+var redis = builder.AddRedis("cache");  // Aspire.Hosting.Redis
+var api = builder.AddProject<Projects.Api>("api")
+    .WithReference(redis);
+
+// === Service (client side) — in API's Program.cs ===
+builder.AddRedisClient("cache");        // Aspire.StackExchange.Redis
+// Automatically configures: connection string, health checks, OpenTelemetry, retries
+```
+
+---
+
+## Categories at a glance
+
+Use `list_integrations` for the full live list. This summary covers the major categories:
+
+| Category            | Key integrations                                                                      | Example hosting package                  |
+| ------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------- |
+| **AI**              | Azure OpenAI, OpenAI, GitHub Models, Ollama                                           | `Aspire.Hosting.Azure.CognitiveServices` |
+| **Caching**         | Redis, Garnet, Valkey, Azure Cache for Redis                                          | `Aspire.Hosting.Redis`                   |
+| **Cloud / Azure**   | Storage, Cosmos DB, Service Bus, Key Vault, Event Hubs, Functions, SQL, SignalR (25+) | `Aspire.Hosting.Azure.Storage`           |
+| **Cloud / AWS**     | AWS SDK integration                                                                   | `Aspire.Hosting.AWS`                     |
+| **Databases**       | PostgreSQL, SQL Server, MongoDB, MySQL, Oracle, Elasticsearch, Milvus, Qdrant, SQLite | `Aspire.Hosting.PostgreSQL`              |
+| **DevTools**        | Data API Builder, Dev Tunnels, Mailpit, k6, Flagd, Ngrok, Stripe                      | `Aspire.Hosting.DevTunnels`              |
+| **Messaging**       | RabbitMQ, Kafka, NATS, ActiveMQ, LavinMQ                                              | `Aspire.Hosting.RabbitMQ`                |
+| **Observability**   | OpenTelemetry (built-in), Seq, OTel Collector                                         | `Aspire.Hosting.Seq`                     |
+| **Compute**         | Docker Compose, Kubernetes                                                            | `Aspire.Hosting.Docker`                  |
+| **Reverse Proxies** | YARP                                                                                  | `Aspire.Hosting.Yarp`                    |
+| **Security**        | Keycloak                                                                              | `Aspire.Hosting.Keycloak`                |
+| **Frameworks**      | JavaScript, Python, Go, Java, Rust, Bun, Deno, Orleans, MAUI, Dapr, PowerShell        | `Aspire.Hosting.Python`                  |
+
+For polyglot framework method signatures, see [Polyglot APIs](polyglot-apis.md).
+
+---
diff --git a/.github/skills/aspire/references/mcp-server.md b/.github/skills/aspire/references/mcp-server.md
new file mode 100644
index 0000000..bca2d93
--- /dev/null
+++ b/.github/skills/aspire/references/mcp-server.md
@@ -0,0 +1,195 @@
+# MCP Server — Complete Reference
+
+Aspire exposes an **MCP (Model Context Protocol) server** that lets AI coding assistants query and control your running distributed application, and search Aspire documentation. This enables AI tools to inspect resource status, read logs, view traces, restart services, and look up docs — all from within the AI assistant's context.
+
+Reference: https://aspire.dev/get-started/configure-mcp/
+
+---
+
+## Setup: `aspire mcp init`
+
+The easiest way to configure the MCP server is using the Aspire CLI:
+
+```bash
+# Open a terminal in your project directory
+aspire mcp init
+```
+
+The command walks you through an interactive setup:
+
+1. **Workspace root** — prompts for the path to your workspace root (defaults to current directory)
+2. **Environment detection** — detects supported AI environments (VS Code, Copilot CLI, Claude Code, OpenCode) and asks which to configure
+3. **Playwright MCP** — optionally offers to configure the Playwright MCP server alongside Aspire
+4. **Config creation** — writes the appropriate configuration files (e.g., `.vscode/mcp.json`)
+5. **AGENTS.md** — if one doesn't already exist, creates an `AGENTS.md` with Aspire-specific instructions for AI agents
+
+> **Note:** `aspire mcp init` uses interactive prompts (Spectre.Console). It must be run in a real terminal — the VS Code integrated terminal may not handle the prompts correctly. Use an external terminal if needed.
+
+---
+
+## Understanding the Configuration
+
+When you run `aspire mcp init`, the CLI creates configuration files appropriate for your detected environment.
+
+### VS Code (GitHub Copilot)
+
+Creates or updates `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "aspire": {
+      "type": "stdio",
+      "command": "aspire",
+      "args": ["mcp", "start"]
+    }
+  }
+}
+```
+
+## MCP Tools
+
+The tools available depend on your Aspire CLI version. Check with `aspire --version`.
+
+### Tools available in 13.1+ (stable)
+
+#### Resource management tools
+
+These tools require a running AppHost (`aspire run`).
+
+| Tool                         | Description                                                                          |
+| ---------------------------- | ------------------------------------------------------------------------------------ |
+| `list_resources`             | Lists all resources, including state, health status, source, endpoints, and commands                |
+| `list_console_logs`          | Lists console logs for a resource                                                                   |
+| `list_structured_logs`       | Lists structured logs, optionally filtered by resource name                                         |
+| `list_traces`                | Lists distributed traces. Traces can be filtered using an optional resource name parameter          |
+| `list_trace_structured_logs` | Lists structured logs for a specific trace                                                          |
+| `execute_resource_command`   | Executes a resource command (accepts resource name and command name)                                |
+
+#### AppHost management tools
+
+| Tool             | Description                                                                                 |
+| ---------------- | ------------------------------------------------------------------------------------------- |
+| `list_apphosts`  | Lists all detected AppHost connections, showing which are in/out of working directory scope |
+| `select_apphost` | Selects which AppHost to use when multiple are running                                      |
+
+#### Integration tools
+
+These work without a running AppHost.
+
+| Tool                   | Description                                                                                                       |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `list_integrations`    | Lists available Aspire hosting integrations (NuGet packages for databases, message brokers, cloud services, etc.) |
+| `get_integration_docs` | Gets documentation for a specific Aspire hosting integration package                                              |
+
+### Tools added in 13.2+ (documentation search)
+
+> **Version gate:** These tools were added in [PR #14028](https://github.com/dotnet/aspire/pull/14028) and ship in Aspire CLI **13.2**. If you are on 13.1, these tools will NOT appear. To get them early, update to the daily channel: `aspire update --self --channel daily`.
+
+| Tool          | Description                                                              |
+| ------------- | ------------------------------------------------------------------------ |
+| `list_docs`   | Lists all available documentation from aspire.dev                        |
+| `search_docs` | Performs weighted lexical search across indexed aspire.dev documentation |
+| `get_doc`     | Retrieves a specific document by its slug                                |
+
+These tools index aspire.dev content using the `llms.txt` specification and provide weighted lexical search (titles 10x, summaries 8x, headings 6x, code 5x, body 1x). They work without a running AppHost.
+
+### Fallback for documentation (13.1 users)
+
+If you are on Aspire CLI 13.1 and don't have `list_docs`/`search_docs`/`get_doc`, use **Context7** as a fallback for documentation queries. See the [SKILL.md documentation research section](../SKILL.md#1-researching-aspire-documentation) for details.
+
+---
+
+## Excluding Resources from MCP
+
+Resources and associated telemetry can be excluded from MCP results by annotating the resource:
+
+```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
+var apiService = builder.AddProject<Projects.Api>("apiservice")
+    .ExcludeFromMcp();  // Hidden from MCP tools
+
+builder.AddProject<Projects.Web>("webfrontend")
+    .WithExternalHttpEndpoints()
+    .WithReference(apiService);
+
+builder.Build().Run();
+```
+
+---
+
+## Supported AI Assistants
+
+The `aspire mcp init` command supports:
+
+- [VS Code](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) (GitHub Copilot)
+- [Copilot CLI](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/use-copilot-cli#add-an-mcp-server)
+- [Claude Code](https://docs.claude.com/en/docs/claude-code/mcp)
+- [OpenCode](https://opencode.ai/docs/mcp-servers/)
+
+The MCP server uses the **STDIO transport protocol** and may work with other agentic coding environments that support this protocol.
+
+---
+
+## Usage Patterns
+
+### Debugging with AI assistance
+
+Once MCP is configured, your AI assistant can:
+
+1. **Inspect running state:**
+
+   - "List all my Aspire resources and their status"
+   - "Is the database healthy?"
+   - "What port is the API running on?"
+
+2. **Read logs:**
+
+   - "Show me the recent logs from the ML service"
+   - "Are there any errors in the worker logs?"
+
+3. **View traces:**
+
+   - "Show me the trace for the last failed request"
+   - "What's the latency for API → Database calls?"
+
+4. **Control resources:**
+
+   - "Restart the API service"
+   - "Stop the worker while I debug the queue"
+
+5. **Search docs (13.2+):**
+   - "Search the Aspire docs for Redis caching"
+   - "How do I configure service discovery?"
+   - _(Requires CLI 13.2+. On 13.1, use Context7 or `list_integrations`/`get_integration_docs` for integration-specific docs.)_
+
+---
+
+## Security Considerations
+
+- The MCP server only exposes resources from the local AppHost
+- No authentication is required (local development only)
+- The STDIO transport only works for the AI tool that spawned the process
+- **Do not expose the MCP endpoint to the network in production**
+
+---
+
+## Limitations
+
+- AI models have limits on data processing. Large data fields (e.g., stack traces) may be truncated.
+- Requests involving large collections of telemetry may be shortened by omitting older items.
+
+---
+
+## Troubleshooting
+
+If you run into issues, check the [open MCP issues on GitHub](https://github.com/dotnet/aspire/issues?q=is%3Aissue+is%3Aopen+label%3Aarea-mcp).
+
+## See Also
+
+- [aspire mcp command](https://aspire.dev/reference/cli/commands/aspire-mcp/)
+- [aspire mcp init command](https://aspire.dev/reference/cli/commands/aspire-mcp-init/)
+- [aspire mcp start command](https://aspire.dev/reference/cli/commands/aspire-mcp-start/)
+- [GitHub Copilot in the Dashboard](https://aspire.dev/dashboard/copilot/)
+- [How I taught AI to read Aspire docs](https://davidpine.dev/posts/aspire-docs-mcp-tools/)
diff --git a/.github/skills/aspire/references/polyglot-apis.md b/.github/skills/aspire/references/polyglot-apis.md
new file mode 100644
index 0000000..ec4796f
--- /dev/null
+++ b/.github/skills/aspire/references/polyglot-apis.md
@@ -0,0 +1,296 @@
+# Polyglot APIs — Complete Reference
+
+Aspire supports 10+ languages/runtimes. The AppHost is always .NET, but orchestrated workloads can be any language. Each language has a hosting method that returns a resource you wire into the dependency graph.
+
+---
+
+## Hosting model differences
+
+| Model | Resource type | How it runs | Examples |
+|---|---|---|---|
+| **Project** | `ProjectResource` | .NET project reference, built by SDK | `AddProject<T>()` |
+| **Container** | `ContainerResource` | Docker/OCI image | `AddContainer()`, `AddRedis()`, `AddPostgres()` |
+| **Executable** | `ExecutableResource` | Native OS process | `AddExecutable()`, all `Add*App()` polyglot methods |
+
+All polyglot `Add*App()` methods create `ExecutableResource` instances under the hood. They don't require the target language's SDK on the AppHost side — only that the workload's runtime is installed on the dev machine.
+
+---
+
+## Official (Microsoft-maintained)
+
+### .NET / C\#
+
+```csharp
+builder.AddProject<Projects.MyApi>("api")
+```
+
+**Chaining methods:**
+- `.WithHttpEndpoint(port?, targetPort?, name?)` — expose HTTP endpoint
+- `.WithHttpsEndpoint(port?, targetPort?, name?)` — expose HTTPS endpoint
+- `.WithEndpoint(port?, targetPort?, scheme?, name?)` — generic endpoint
+- `.WithReference(resource)` — wire dependency (connection string or service discovery)
+- `.WithReplicas(count)` — run multiple instances
+- `.WithEnvironment(key, value)` — set environment variable
+- `.WithEnvironment(callback)` — set env vars via callback (deferred resolution)
+- `.WaitFor(resource)` — don't start until dependency is healthy
+- `.WithExternalHttpEndpoints()` — mark endpoints as externally accessible
+- `.WithOtlpExporter()` — configure OpenTelemetry exporter
+- `.PublishAsDockerFile()` — override publish behavior to Dockerfile
+
+### Python
+
+```csharp
+// Standard Python script
+builder.AddPythonApp("service", "../python-service", "main.py")
+
+// Uvicorn ASGI server (FastAPI, Starlette, etc.)
+builder.AddUvicornApp("fastapi", "../fastapi-app", "app:app")
+```
+
+**`AddPythonApp(name, projectDirectory, scriptPath, args?)`**
+
+Chaining methods:
+- `.WithHttpEndpoint(port?, targetPort?, name?)` — expose HTTP
+- `.WithVirtualEnvironment(path?)` — use venv (default: `.venv`)
+- `.WithPipPackages(packages)` — install pip packages on start
+- `.WithReference(resource)` — wire dependency
+- `.WithEnvironment(key, value)` — set env var
+- `.WaitFor(resource)` — wait for dependency health
+
+**`AddUvicornApp(name, projectDirectory, appModule, args?)`**
+
+Chaining methods:
+- `.WithHttpEndpoint(port?, targetPort?, name?)` — expose HTTP
+- `.WithVirtualEnvironment(path?)` — use venv
+- `.WithReference(resource)` — wire dependency
+- `.WithEnvironment(key, value)` — set env var
+- `.WaitFor(resource)` — wait for dependency health
+
+**Python service discovery:** Environment variables are injected automatically. Use `os.environ` to read:
+```python
+import os
+redis_conn = os.environ["ConnectionStrings__cache"]
+api_url = os.environ["services__api__http__0"]
+```
+
+### JavaScript / TypeScript
+
+```csharp
+// Generic JavaScript app (npm start)
+builder.AddJavaScriptApp("frontend", "../web-app")
+
+// Vite dev server
+builder.AddViteApp("spa", "../vite-app")
+
+// Node.js script
+builder.AddNodeApp("worker", "server.js", "../node-worker")
+```
+
+**`AddJavaScriptApp(name, workingDirectory)`**
+
+Chaining methods:
+- `.WithHttpEndpoint(port?, targetPort?, name?)` — expose HTTP
+- `.WithNpmPackageInstallation()` — run `npm install` before start
+- `.WithReference(resource)` — wire dependency
+- `.WithEnvironment(key, value)` — set env var
+- `.WaitFor(resource)` — wait for dependency health
+
+**`AddViteApp(name, workingDirectory)`**
+
+Chaining methods (same as `AddJavaScriptApp` plus):
+- `.WithNpmPackageInstallation()` — run `npm install` before start
+- `.WithHttpEndpoint(port?, targetPort?, name?)` — Vite defaults to 5173
+
+**`AddNodeApp(name, scriptPath, workingDirectory)`**
+
+Chaining methods:
+- `.WithHttpEndpoint(port?, targetPort?, name?)` — expose HTTP
+- `.WithNpmPackageInstallation()` — run `npm install` before start
+- `.WithReference(resource)` — wire dependency
+- `.WithEnvironment(key, value)` — set env var
+
+**JS/TS service discovery:** Environment variables are injected. Use `process.env`:
+```javascript
+const redisUrl = process.env.ConnectionStrings__cache;
+const apiUrl = process.env.services__api__http__0;
+```
+
+---
+
+## Community (CommunityToolkit/Aspire)
+
+All community integrations follow the same pattern: install the NuGet package in your AppHost, then use the `Add*App()` method.
+
+### Go
+
+**Package:** `CommunityToolkit.Aspire.Hosting.Golang`
+
+```csharp
+builder.AddGolangApp("go-api", "../go-service")
+    .WithHttpEndpoint(targetPort: 8080)
+    .WithReference(redis)
+    .WithEnvironment("LOG_LEVEL", "debug")
+    .WaitFor(redis);
+```
+
+Chaining methods:
+- `.WithHttpEndpoint(port?, targetPort?, name?)`
+- `.WithReference(resource)`
+- `.WithEnvironment(key, value)`
+- `.WaitFor(resource)`
+
+**Go service discovery:** Standard env vars via `os.Getenv()`:
+```go
+redisAddr := os.Getenv("ConnectionStrings__cache")
+```
+
+### Java (Spring Boot)
+
+**Package:** `CommunityToolkit.Aspire.Hosting.Java`
+
+```csharp
+builder.AddSpringApp("spring-api", "../spring-service")
+    .WithHttpEndpoint(targetPort: 8080)
+    .WithReference(postgres)
+    .WaitFor(postgres);
+```
+
+Chaining methods:
+- `.WithHttpEndpoint(port?, targetPort?, name?)`
+- `.WithReference(resource)`
+- `.WithEnvironment(key, value)`
+- `.WaitFor(resource)`
+- `.WithMavenBuild()` — run Maven build before start
+- `.WithGradleBuild()` — run Gradle build before start
+
+**Java service discovery:** Env vars via `System.getenv()`:
+```java
+String dbConn = System.getenv("ConnectionStrings__db");
+```
+
+### Rust
+
+**Package:** `CommunityToolkit.Aspire.Hosting.Rust`
+
+```csharp
+builder.AddRustApp("rust-worker", "../rust-service")
+    .WithHttpEndpoint(targetPort: 3000)
+    .WithReference(redis)
+    .WaitFor(redis);
+```
+
+Chaining methods:
+- `.WithHttpEndpoint(port?, targetPort?, name?)`
+- `.WithReference(resource)`
+- `.WithEnvironment(key, value)`
+- `.WaitFor(resource)`
+- `.WithCargoBuild()` — run `cargo build` before start
+
+### Bun
+
+**Package:** `CommunityToolkit.Aspire.Hosting.Bun`
+
+```csharp
+builder.AddBunApp("bun-api", "../bun-service")
+    .WithHttpEndpoint(targetPort: 3000)
+    .WithReference(redis);
+```
+
+Chaining methods:
+- `.WithHttpEndpoint(port?, targetPort?, name?)`
+- `.WithReference(resource)`
+- `.WithEnvironment(key, value)`
+- `.WaitFor(resource)`
+- `.WithBunPackageInstallation()` — run `bun install` before start
+
+### Deno
+
+**Package:** `CommunityToolkit.Aspire.Hosting.Deno`
+
+```csharp
+builder.AddDenoApp("deno-api", "../deno-service")
+    .WithHttpEndpoint(targetPort: 8000)
+    .WithReference(redis);
+```
+
+Chaining methods:
+- `.WithHttpEndpoint(port?, targetPort?, name?)`
+- `.WithReference(resource)`
+- `.WithEnvironment(key, value)`
+- `.WaitFor(resource)`
+
+### PowerShell
+
+```csharp
+builder.AddPowerShell("ps-script", "../scripts/process.ps1")
+    .WithReference(storageAccount);
+```
+
+### Dapr
+
+**Package:** `Aspire.Hosting.Dapr` (official)
+
+```csharp
+var dapr = builder.AddDapr();
+var api = builder.AddProject<Projects.Api>("api")
+    .WithDaprSidecar("api-sidecar");
+```
+
+---
+
+## Complete mixed-language example
+
+```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
+// Infrastructure
+var redis = builder.AddRedis("cache");
+var postgres = builder.AddPostgres("pg").AddDatabase("catalog");
+var mongo = builder.AddMongoDB("mongo").AddDatabase("analytics");
+var rabbit = builder.AddRabbitMQ("messaging");
+
+// .NET API (primary)
+var api = builder.AddProject<Projects.CatalogApi>("api")
+    .WithReference(postgres)
+    .WithReference(redis)
+    .WithReference(rabbit)
+    .WaitFor(postgres)
+    .WaitFor(redis);
+
+// Python ML service (FastAPI)
+var ml = builder.AddUvicornApp("ml", "../ml-service", "app:app")
+    .WithHttpEndpoint(targetPort: 8000)
+    .WithVirtualEnvironment()
+    .WithReference(redis)
+    .WithReference(mongo)
+    .WaitFor(redis);
+
+// TypeScript frontend (Vite + React)
+var web = builder.AddViteApp("web", "../frontend")
+    .WithNpmPackageInstallation()
+    .WithHttpEndpoint(targetPort: 5173)
+    .WithReference(api);
+
+// Go event processor
+var processor = builder.AddGolangApp("processor", "../go-processor")
+    .WithReference(rabbit)
+    .WithReference(mongo)
+    .WaitFor(rabbit);
+
+// Java analytics service (Spring Boot)
+var analytics = builder.AddSpringApp("analytics", "../spring-analytics")
+    .WithHttpEndpoint(targetPort: 8080)
+    .WithReference(mongo)
+    .WithReference(rabbit)
+    .WaitFor(mongo);
+
+// Rust high-perf worker
+var worker = builder.AddRustApp("worker", "../rust-worker")
+    .WithReference(redis)
+    .WithReference(rabbit)
+    .WaitFor(redis);
+
+builder.Build().Run();
+```
+
+This single AppHost starts 6 services across 5 languages plus 4 infrastructure resources, all wired together with automatic service discovery.
diff --git a/.github/skills/aspire/references/testing.md b/.github/skills/aspire/references/testing.md
new file mode 100644
index 0000000..7642ffc
--- /dev/null
+++ b/.github/skills/aspire/references/testing.md
@@ -0,0 +1,281 @@
+# Testing — Complete Reference
+
+Aspire provides `Aspire.Hosting.Testing` for running integration tests against your full AppHost. Tests spin up the entire distributed application (or a subset) and run assertions against real services.
+
+---
+
+## Package
+
+```xml
+<PackageReference Include="Aspire.Hosting.Testing" Version="*" />
+```
+
+---
+
+## Core pattern: DistributedApplicationTestingBuilder
+
+```csharp
+// 1. Create a testing builder from your AppHost
+var builder = await DistributedApplicationTestingBuilder
+    .CreateAsync<Projects.MyAppHost>();
+
+// 2. (Optional) Override resources for testing
+// ... see customization section below
+
+// 3. Build and start the application
+await using var app = await builder.BuildAsync();
+await app.StartAsync();
+
+// 4. Create HTTP clients for your services
+var client = app.CreateHttpClient("api");
+
+// 5. Run assertions
+var response = await client.GetAsync("/health");
+Assert.Equal(HttpStatusCode.OK, response.StatusCode);
+```
+
+---
+
+## xUnit examples
+
+### Basic health check test
+
+```csharp
+public class HealthTests(ITestOutputHelper output)
+{
+    [Fact]
+    public async Task AllServicesAreHealthy()
+    {
+        var builder = await DistributedApplicationTestingBuilder
+            .CreateAsync<Projects.AppHost>();
+
+        await using var app = await builder.BuildAsync();
+        await app.StartAsync();
+
+        // Test each service's health endpoint
+        var apiClient = app.CreateHttpClient("api");
+        var apiHealth = await apiClient.GetAsync("/health");
+        Assert.Equal(HttpStatusCode.OK, apiHealth.StatusCode);
+
+        var workerClient = app.CreateHttpClient("worker");
+        var workerHealth = await workerClient.GetAsync("/health");
+        Assert.Equal(HttpStatusCode.OK, workerHealth.StatusCode);
+    }
+}
+```
+
+### API integration test
+
+```csharp
+public class ApiTests(ITestOutputHelper output)
+{
+    [Fact]
+    public async Task CreateOrder_ReturnsCreated()
+    {
+        var builder = await DistributedApplicationTestingBuilder
+            .CreateAsync<Projects.AppHost>();
+
+        await using var app = await builder.BuildAsync();
+        await app.StartAsync();
+
+        var client = app.CreateHttpClient("api");
+
+        var order = new { ProductId = 1, Quantity = 2 };
+        var response = await client.PostAsJsonAsync("/orders", order);
+
+        Assert.Equal(HttpStatusCode.Created, response.StatusCode);
+
+        var created = await response.Content.ReadFromJsonAsync<Order>();
+        Assert.NotNull(created);
+        Assert.Equal(1, created.ProductId);
+    }
+}
+```
+
+### Testing with wait for readiness
+
+```csharp
+[Fact]
+public async Task DatabaseIsSeeded()
+{
+    var builder = await DistributedApplicationTestingBuilder
+        .CreateAsync<Projects.AppHost>();
+
+    await using var app = await builder.BuildAsync();
+    await app.StartAsync();
+
+    // Wait for the API to be fully ready (all dependencies healthy)
+    await app.WaitForResourceReadyAsync("api");
+
+    var client = app.CreateHttpClient("api");
+    var response = await client.GetAsync("/products");
+
+    Assert.Equal(HttpStatusCode.OK, response.StatusCode);
+    var products = await response.Content.ReadFromJsonAsync<List<Product>>();
+    Assert.NotEmpty(products);
+}
+```
+
+---
+
+## MSTest examples
+
+```csharp
+[TestClass]
+public class IntegrationTests
+{
+    [TestMethod]
+    public async Task ApiReturnsProducts()
+    {
+        var builder = await DistributedApplicationTestingBuilder
+            .CreateAsync<Projects.AppHost>();
+
+        await using var app = await builder.BuildAsync();
+        await app.StartAsync();
+
+        var client = app.CreateHttpClient("api");
+        var response = await client.GetAsync("/products");
+
+        Assert.AreEqual(HttpStatusCode.OK, response.StatusCode);
+    }
+}
+```
+
+---
+
+## NUnit examples
+
+```csharp
+[TestFixture]
+public class IntegrationTests
+{
+    [Test]
+    public async Task ApiReturnsProducts()
+    {
+        var builder = await DistributedApplicationTestingBuilder
+            .CreateAsync<Projects.AppHost>();
+
+        await using var app = await builder.BuildAsync();
+        await app.StartAsync();
+
+        var client = app.CreateHttpClient("api");
+        var response = await client.GetAsync("/products");
+
+        Assert.That(response.StatusCode, Is.EqualTo(HttpStatusCode.OK));
+    }
+}
+```
+
+---
+
+## Customizing the test AppHost
+
+### Override resources
+
+```csharp
+var builder = await DistributedApplicationTestingBuilder
+    .CreateAsync<Projects.AppHost>();
+
+// Replace a real database with a test container
+builder.Services.ConfigureHttpClientDefaults(http =>
+{
+    http.AddStandardResilienceHandler();
+});
+
+// Add test-specific configuration
+builder.Configuration["TestMode"] = "true";
+
+await using var app = await builder.BuildAsync();
+await app.StartAsync();
+```
+
+### Exclude resources
+
+```csharp
+var builder = await DistributedApplicationTestingBuilder
+    .CreateAsync<Projects.AppHost>(args =>
+    {
+        // Don't start the worker for API-only tests
+        args.Args = ["--exclude-resource", "worker"];
+    });
+```
+
+### Test with specific environment
+
+```csharp
+var builder = await DistributedApplicationTestingBuilder
+    .CreateAsync<Projects.AppHost>(args =>
+    {
+        args.Args = ["--environment", "Testing"];
+    });
+```
+
+---
+
+## Connection string access
+
+```csharp
+// Get the connection string for a resource in tests
+var connectionString = await app.GetConnectionStringAsync("db");
+
+// Use it to query the database directly in tests
+using var conn = new NpgsqlConnection(connectionString);
+await conn.OpenAsync();
+var count = await conn.ExecuteScalarAsync<int>("SELECT COUNT(*) FROM products");
+Assert.True(count > 0);
+```
+
+---
+
+## Best practices
+
+1. **Use `WaitForResourceReadyAsync`** before making requests — ensures all dependencies are healthy
+2. **Each test should be independent** — don't rely on state from previous tests
+3. **Use `await using`** for the app — ensures cleanup even on test failure
+4. **Test real infrastructure** — Aspire spins up real containers (Redis, PostgreSQL, etc.), giving you high-fidelity integration tests
+5. **Keep test AppHost lean** — exclude resources you don't need for specific test scenarios
+6. **Use test-specific configuration** — override settings for test isolation
+7. **Timeout protection** — set reasonable test timeouts since containers take time to start:
+
+```csharp
+[Fact(Timeout = 120_000)]  // 2 minutes
+public async Task SlowIntegrationTest() { ... }
+```
+
+---
+
+## Project structure
+
+```
+MyApp/
+├── src/
+│   ├── MyApp.AppHost/           # AppHost project
+│   ├── MyApp.Api/               # API service
+│   ├── MyApp.Worker/            # Worker service
+│   └── MyApp.ServiceDefaults/   # Shared defaults
+└── tests/
+    └── MyApp.Tests/             # Integration tests
+        ├── MyApp.Tests.csproj   # References AppHost + Testing package
+        └── ApiTests.cs          # Test classes
+```
+
+```xml
+<!-- MyApp.Tests.csproj -->
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <IsAspireTestProject>true</IsAspireTestProject>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Aspire.Hosting.Testing" Version="*" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="*" />
+    <PackageReference Include="xunit" Version="*" />
+    <PackageReference Include="xunit.runner.visualstudio" Version="*" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\MyApp.AppHost\MyApp.AppHost.csproj" />
+  </ItemGroup>
+</Project>
+```
diff --git a/.github/skills/aspire/references/troubleshooting.md b/.github/skills/aspire/references/troubleshooting.md
new file mode 100644
index 0000000..c59991d
--- /dev/null
+++ b/.github/skills/aspire/references/troubleshooting.md
@@ -0,0 +1,194 @@
+# Troubleshooting — Diagnostics & Common Issues
+
+---
+
+## Diagnostic Codes
+
+Aspire emits diagnostic codes for common issues. These appear in build warnings/errors and IDE diagnostics.
+
+### Standard diagnostics
+
+| Code          | Severity | Description                                                |
+| ------------- | -------- | ---------------------------------------------------------- |
+| **ASPIRE001** | Warning  | Resource name contains invalid characters                  |
+| **ASPIRE002** | Warning  | Duplicate resource name detected                           |
+| **ASPIRE003** | Error    | Missing required package reference                         |
+| **ASPIRE004** | Warning  | Deprecated API usage                                       |
+| **ASPIRE005** | Error    | Invalid endpoint configuration                             |
+| **ASPIRE006** | Warning  | Health check not configured for resource with `.WaitFor()` |
+| **ASPIRE007** | Warning  | Container image tag not specified (using `latest`)         |
+| **ASPIRE008** | Error    | Circular dependency detected in resource graph             |
+
+### Experimental diagnostics (ASPIREHOSTINGX\*)
+
+These codes indicate usage of experimental/preview APIs. They may require `#pragma warning disable` or `<NoWarn>` if you intentionally use experimental features:
+
+| Code                      | Area                             |
+| ------------------------- | -------------------------------- |
+| ASPIRE_HOSTINGX_0001–0005 | Experimental hosting APIs        |
+| ASPIRE_HOSTINGX_0006–0010 | Experimental integration APIs    |
+| ASPIRE_HOSTINGX_0011–0015 | Experimental deployment APIs     |
+| ASPIRE_HOSTINGX_0016–0022 | Experimental resource model APIs |
+
+To suppress experimental warnings:
+
+```xml
+<!-- In .csproj -->
+<PropertyGroup>
+  <NoWarn>$(NoWarn);ASPIRE_HOSTINGX_0001</NoWarn>
+</PropertyGroup>
+```
+
+Or per-line:
+
+```csharp
+#pragma warning disable ASPIRE_HOSTINGX_0001
+var resource = builder.AddExperimentalResource("test");
+#pragma warning restore ASPIRE_HOSTINGX_0001
+```
+
+---
+
+## Common Issues & Solutions
+
+### Container runtime
+
+| Problem                           | Solution                                                                                               |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| "Cannot connect to Docker daemon" | Start Docker Desktop / Podman / Rancher Desktop                                                        |
+| Container fails to start          | Check `docker ps -a` for exit codes; check dashboard console logs                                      |
+| Port already in use               | Another process is using the port; Aspire auto-assigns, but `targetPort` must be free on the container |
+| Container image pull fails        | Check network connectivity; verify image name and tag                                                  |
+| "Permission denied" on Linux      | Add user to `docker` group: `sudo usermod -aG docker $USER`                                            |
+
+### Service discovery
+
+| Problem                       | Solution                                                                     |
+| ----------------------------- | ---------------------------------------------------------------------------- |
+| Service can't find dependency | Verify `.WithReference()` in AppHost; check env vars in dashboard            |
+| Connection string is null     | The reference resource name doesn't match; check `ConnectionStrings__<name>` |
+| Wrong port in service URL     | Check `targetPort` vs actual service listen port                             |
+| Env var not set               | Rebuild AppHost; verify resource name matches exactly                        |
+
+### Python workloads
+
+| Problem                           | Solution                                                        |
+| --------------------------------- | --------------------------------------------------------------- |
+| "Python not found"                | Ensure Python is on PATH; specify full path in `AddPythonApp()` |
+| venv not found                    | Use `.WithVirtualEnvironment()` or create venv manually         |
+| pip packages fail to install      | Use `.WithPipPackages()` or install in venv before `aspire run` |
+| ModuleNotFoundError               | venv isn't activated; `.WithVirtualEnvironment()` handles this  |
+| "Port already in use" for Uvicorn | Check `targetPort` — another instance may be running            |
+
+### JavaScript / TypeScript workloads
+
+| Problem                       | Solution                                                         |
+| ----------------------------- | ---------------------------------------------------------------- |
+| "node_modules not found"      | Use `.WithNpmPackageInstallation()` to auto-install              |
+| npm install fails             | Check `package.json` is valid; check npm registry connectivity   |
+| Vite dev server won't start   | Verify `vite` is in devDependencies; check Vite config           |
+| Port mismatch                 | Ensure `targetPort` matches the port in your JS framework config |
+| TypeScript compilation errors | These happen in the service, not Aspire — check service logs     |
+
+### Go workloads
+
+| Problem                    | Solution                                                   |
+| -------------------------- | ---------------------------------------------------------- |
+| "go not found"             | Ensure Go is installed and on PATH                         |
+| Build fails                | Check `go.mod` exists in working directory                 |
+| "no Go files in directory" | Verify `workingDir` points to the directory with `main.go` |
+
+### Java workloads
+
+| Problem                  | Solution                                                |
+| ------------------------ | ------------------------------------------------------- |
+| "java not found"         | Ensure JDK is installed and `JAVA_HOME` is set          |
+| Maven/Gradle build fails | Verify build files exist; check build tool installation |
+| Spring Boot won't start  | Check `application.properties`; verify main class       |
+
+### Rust workloads
+
+| Problem              | Solution                                                             |
+| -------------------- | -------------------------------------------------------------------- |
+| "cargo not found"    | Install Rust via rustup                                              |
+| Build takes too long | Rust compile times are normal; use `.WithCargoBuild()` for pre-build |
+
+### Health checks & startup
+
+| Problem                      | Solution                                                                       |
+| ---------------------------- | ------------------------------------------------------------------------------ |
+| Resource stuck in "Starting" | Health check endpoint not responding; check service logs                       |
+| `.WaitFor()` timeout         | Increase timeout or fix health endpoint; default is 30 seconds                 |
+| Health check always fails    | Verify endpoint path (default: `/health`); check service binds to correct port |
+| Cascading startup failures   | A dependency failed; check the root resource first                             |
+
+### Dashboard
+
+| Problem                               | Solution                                                                  |
+| ------------------------------------- | ------------------------------------------------------------------------- |
+| Dashboard doesn't open                | Check terminal for URL; use `--dashboard-port` for fixed port             |
+| No logs appearing                     | Service may not be writing to stdout/stderr; check console output         |
+| No traces for non-.NET services       | Configure OpenTelemetry SDK in the service; see [Dashboard](dashboard.md) |
+| Traces don't show cross-service calls | Propagate trace context headers (`traceparent`, `tracestate`)             |
+
+### Build & configuration
+
+| Problem                                   | Solution                                                            |
+| ----------------------------------------- | ------------------------------------------------------------------- |
+| "Project not found" for `AddProject<T>()` | Ensure `.csproj` is in the solution and referenced by AppHost       |
+| Package version conflicts                 | Pin all Aspire packages to the same version                         |
+| AppHost won't build                       | Check `Aspire.AppHost.Sdk` is in the project; run `dotnet restore`  |
+| `aspire run` build error                  | Fix the build error first; `aspire run` requires a successful build |
+
+### Deployment
+
+| Problem                                  | Solution                                                             |
+| ---------------------------------------- | -------------------------------------------------------------------- |
+| `aspire publish` fails                   | Check publisher package is installed (e.g., `Aspire.Hosting.Docker`) |
+| Generated Bicep has errors               | Check for unsupported resource configurations                        |
+| Container image push fails               | Verify registry credentials and permissions                          |
+| Missing connection strings in deployment | Check generated ConfigMaps/Secrets match resource names              |
+
+---
+
+## Debugging strategies
+
+### 1. Check the dashboard first
+
+The dashboard shows resource state, logs, traces, and metrics. Start here for any issue.
+
+### 2. Check environment variables
+
+In the dashboard, click a resource to see all injected environment variables. Verify connection strings and service URLs are correct.
+
+### 3. Read console logs
+
+Dashboard → Console Logs → filter by the failing resource. Raw stdout/stderr often contains the root cause.
+
+### 4. Check the DAG
+
+If services fail to start, check the dependency order. A failed dependency blocks all downstream resources.
+
+### 5. Use MCP for AI-assisted debugging
+
+If MCP is configured (see [MCP Server](mcp-server.md)), ask your AI assistant:
+
+- "What resources are failing?"
+- "Show me the logs for [service]"
+- "What traces show errors?"
+
+### 6. Isolate the problem
+
+Run just the failing resource by commenting out others in the AppHost. This narrows whether the issue is the resource itself or a dependency.
+
+---
+
+## Getting help
+
+| Channel                 | URL                                            |
+| ----------------------- | ---------------------------------------------- |
+| GitHub Issues (runtime) | https://github.com/dotnet/aspire/issues        |
+| GitHub Issues (docs)    | https://github.com/microsoft/aspire.dev/issues |
+| Discord                 | https://aka.ms/aspire/discord                  |
+| Stack Overflow          | Tag: `dotnet-aspire`                           |
+| Reddit                  | https://www.reddit.com/r/aspiredotdev/         |
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..2fde437
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,491 @@
+# ---> Visual Studio
+# User-specific files
+*.rsuser
+*.suo
+*.user
+*.userosscache
+*.sln.docstates
+
+# User-specific files (MonoDevelop/Xamarin Studio)
+*.userprefs
+
+# Mono auto generated files
+mono_crash.*
+
+# Build results
+[Dd]ebug/
+[Dd]ebugPublic/
+[Rr]elease/
+[Rr]eleases/
+
+[Dd]ebug/x64/
+[Dd]ebugPublic/x64/
+[Rr]elease/x64/
+[Rr]eleases/x64/
+bin/x64/
+obj/x64/
+
+[Dd]ebug/x86/
+[Dd]ebugPublic/x86/
+[Rr]elease/x86/
+[Rr]eleases/x86/
+bin/x86/
+obj/x86/
+
+[Ww][Ii][Nn]32/
+[Aa][Rr][Mm]/
+[Aa][Rr][Mm]64/
+[Aa][Rr][Mm]64[Ee][Cc]/
+bld/
+[Oo]bj/
+[Oo]ut/
+[Ll]og/
+[Ll]ogs/
+
+# Build results on 'Bin' directories
+**/[Bb]in/*
+# Uncomment if you have tasks that rely on *.refresh files to move binaries
+# (https://github.com/github/gitignore/pull/3736)
+#!**/[Bb]in/*.refresh
+
+# Visual Studio 2015/2017 cache/options directory
+.vs/
+# Uncomment if you have tasks that create the project's static files in wwwroot
+#wwwroot/
+
+# Visual Studio 2017 auto generated files
+Generated\ Files/
+
+# MSTest test Results
+[Tt]est[Rr]esult*/
+[Bb]uild[Ll]og.*
+*.trx
+
+# NUnit
+*.VisualState.xml
+TestResult.xml
+nunit-*.xml
+
+# Approval Tests result files
+*.received.*
+
+# Build Results of an ATL Project
+[Dd]ebugPS/
+[Rr]eleasePS/
+dlldata.c
+
+# Benchmark Results
+BenchmarkDotNet.Artifacts/
+
+# .NET Core
+project.lock.json
+project.fragment.lock.json
+artifacts/
+
+# ASP.NET Scaffolding
+ScaffoldingReadMe.txt
+
+# StyleCop
+StyleCopReport.xml
+
+# Files built by Visual Studio
+*_i.c
+*_p.c
+*_h.h
+*.ilk
+*.meta
+*.obj
+*.idb
+*.iobj
+*.pch
+*.pdb
+*.ipdb
+*.pgc
+*.pgd
+*.rsp
+# but not Directory.Build.rsp, as it configures directory-level build defaults
+!Directory.Build.rsp
+*.sbr
+*.tlb
+*.tli
+*.tlh
+*.tmp
+*.tmp_proj
+*_wpftmp.csproj
+*.log
+*.tlog
+*.vspscc
+*.vssscc
+.builds
+*.pidb
+*.svclog
+*.scc
+
+# Chutzpah Test files
+_Chutzpah*
+
+# Visual C++ cache files
+ipch/
+*.aps
+*.ncb
+*.opendb
+*.opensdf
+*.sdf
+*.cachefile
+*.VC.db
+*.VC.VC.opendb
+
+# Visual Studio profiler
+*.psess
+*.vsp
+*.vspx
+*.sap
+
+# Visual Studio Trace Files
+*.e2e
+
+# TFS 2012 Local Workspace
+$tf/
+
+# Guidance Automation Toolkit
+*.gpState
+
+# ReSharper is a .NET coding add-in
+_ReSharper*/
+*.[Rr]e[Ss]harper
+*.DotSettings.user
+
+# TeamCity is a build add-in
+_TeamCity*
+
+# DotCover is a Code Coverage Tool
+*.dotCover
+
+# AxoCover is a Code Coverage Tool
+.axoCover/*
+!.axoCover/settings.json
+
+# Coverlet is a free, cross platform Code Coverage Tool
+coverage*.json
+coverage*.xml
+coverage*.info
+
+# Visual Studio code coverage results
+*.coverage
+*.coveragexml
+
+# NCrunch
+_NCrunch_*
+.NCrunch_*
+.*crunch*.local.xml
+nCrunchTemp_*
+
+# MightyMoose
+*.mm.*
+AutoTest.Net/
+
+# Web workbench (sass)
+.sass-cache/
+
+# Installshield output folder
+[Ee]xpress/
+
+# DocProject is a documentation generator add-in
+DocProject/buildhelp/
+DocProject/Help/*.HxT
+DocProject/Help/*.HxC
+DocProject/Help/*.hhc
+DocProject/Help/*.hhk
+DocProject/Help/*.hhp
+DocProject/Help/Html2
+DocProject/Help/html
+
+# Click-Once directory
+publish/
+
+# Publish Web Output
+*.[Pp]ublish.xml
+*.azurePubxml
+# Note: Comment the next line if you want to checkin your web deploy settings,
+# but database connection strings (with potential passwords) will be unencrypted
+*.pubxml
+*.publishproj
+
+# Microsoft Azure Web App publish settings. Comment the next line if you want to
+# checkin your Azure Web App publish settings, but sensitive information contained
+# in these scripts will be unencrypted
+PublishScripts/
+
+# NuGet Packages
+*.nupkg
+# NuGet Symbol Packages
+*.snupkg
+# The packages folder can be ignored because of Package Restore
+**/[Pp]ackages/*
+# except build/, which is used as an MSBuild target.
+!**/[Pp]ackages/build/
+# Uncomment if necessary however generally it will be regenerated when needed
+#!**/[Pp]ackages/repositories.config
+# NuGet v3's project.json files produces more ignorable files
+*.nuget.props
+*.nuget.targets
+
+# Microsoft Azure Build Output
+csx/
+*.build.csdef
+
+# Microsoft Azure Emulator
+ecf/
+rcf/
+
+# Windows Store app package directories and files
+AppPackages/
+BundleArtifacts/
+Package.StoreAssociation.xml
+_pkginfo.txt
+*.appx
+*.appxbundle
+*.appxupload
+
+# Visual Studio cache files
+# files ending in .cache can be ignored
+*.[Cc]ache
+# but keep track of directories ending in .cache
+!?*.[Cc]ache/
+
+# Others
+ClientBin/
+~$*
+*~
+*.dbmdl
+*.dbproj.schemaview
+*.jfm
+*.pfx
+*.publishsettings
+orleans.codegen.cs
+
+# Including strong name files can present a security risk
+# (https://github.com/github/gitignore/pull/2483#issue-259490424)
+#*.snk
+
+# Since there are multiple workflows, uncomment next line to ignore bower_components
+# (https://github.com/github/gitignore/pull/1529#issuecomment-104372622)
+#bower_components/
+
+# RIA/Silverlight projects
+Generated_Code/
+
+# Backup & report files from converting an old project file
+# to a newer Visual Studio version. Backup files are not needed,
+# because we have git ;-)
+_UpgradeReport_Files/
+Backup*/
+UpgradeLog*.XML
+UpgradeLog*.htm
+ServiceFabricBackup/
+*.rptproj.bak
+
+# SQL Server files
+*.mdf
+*.ldf
+*.ndf
+
+# Business Intelligence projects
+*.rdl.data
+*.bim.layout
+*.bim_*.settings
+*.rptproj.rsuser
+*- [Bb]ackup.rdl
+*- [Bb]ackup ([0-9]).rdl
+*- [Bb]ackup ([0-9][0-9]).rdl
+
+# Microsoft Fakes
+FakesAssemblies/
+
+# GhostDoc plugin setting file
+*.GhostDoc.xml
+
+# Node.js Tools for Visual Studio
+.ntvs_analysis.dat
+node_modules/
+
+# Visual Studio 6 build log
+*.plg
+
+# Visual Studio 6 workspace options file
+*.opt
+
+# Visual Studio 6 auto-generated workspace file (contains which files were open etc.)
+*.vbw
+
+# Visual Studio 6 workspace and project file (working project files containing files to include in project)
+*.dsw
+*.dsp
+
+# Visual Studio 6 technical files
+*.ncb
+*.aps
+
+# Visual Studio LightSwitch build output
+**/*.HTMLClient/GeneratedArtifacts
+**/*.DesktopClient/GeneratedArtifacts
+**/*.DesktopClient/ModelManifest.xml
+**/*.Server/GeneratedArtifacts
+**/*.Server/ModelManifest.xml
+_Pvt_Extensions
+
+# Paket dependency manager
+**/.paket/paket.exe
+paket-files/
+
+# FAKE - F# Make
+**/.fake/
+
+# CodeRush personal settings
+**/.cr/personal
+
+# Python Tools for Visual Studio (PTVS)
+**/__pycache__/
+*.pyc
+
+# Cake - Uncomment if you are using it
+#tools/**
+#!tools/packages.config
+
+# Tabs Studio
+*.tss
+
+# Telerik's JustMock configuration file
+*.jmconfig
+
+# BizTalk build output
+*.btp.cs
+*.btm.cs
+*.odx.cs
+*.xsd.cs
+
+# OpenCover UI analysis results
+OpenCover/
+
+# Azure Stream Analytics local run output
+ASALocalRun/
+
+# MSBuild Binary and Structured Log
+*.binlog
+MSBuild_Logs/
+
+# AWS SAM Build and Temporary Artifacts folder
+.aws-sam
+
+# NVidia Nsight GPU debugger configuration file
+*.nvuser
+
+# MFractors (Xamarin productivity tool) working folder
+**/.mfractor/
+
+# Local History for Visual Studio
+**/.localhistory/
+
+# Visual Studio History (VSHistory) files
+.vshistory/
+
+# BeatPulse healthcheck temp database
+healthchecksdb
+
+# Backup folder for Package Reference Convert tool in Visual Studio 2017
+MigrationBackup/
+
+# Ionide (cross platform F# VS Code tools) working folder
+**/.ionide/
+
+# Fody - auto-generated XML schema
+FodyWeavers.xsd
+
+# VS Code files for those working on multiple tools
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+!.vscode/*.code-snippets
+
+# Local History for Visual Studio Code
+.history/
+
+# Built Visual Studio Code Extensions
+*.vsix
+
+# Windows Installer files from build outputs
+*.cab
+*.msi
+*.msix
+*.msm
+*.msp
+
+# ---> Visual Studio Code
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+!.vscode/*.code-snippets
+!*.code-workspace
+
+# Built Visual Studio Code Extensions
+*.vsix
+
+# ---> macOS
+# General
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+# ---> Windows
+# Windows thumbnail cache files
+Thumbs.db
+Thumbs.db:encryptable
+ehthumbs.db
+ehthumbs_vista.db
+
+# Dump file
+*.stackdump
+
+# Folder config file
+[Dd]esktop.ini
+
+# Recycle Bin used on file shares
+$RECYCLE.BIN/
+
+# Windows Installer files
+*.cab
+*.msi
+*.msix
+*.msm
+*.msp
+
+# Windows shortcuts
+*.lnk
+
diff --git a/.vscode/extensions.json b/.vscode/extensions.json
new file mode 100644
index 0000000..2657236
--- /dev/null
+++ b/.vscode/extensions.json
@@ -0,0 +1,6 @@
+{
+  "recommendations": [
+    "editorconfig.editorconfig",
+    "ms-dotnettools.csdevkit",
+  ]
+}
diff --git a/.vscode/launch.json b/.vscode/launch.json
new file mode 100644
index 0000000..94a9555
--- /dev/null
+++ b/.vscode/launch.json
@@ -0,0 +1,21 @@
+{
+  "configurations": [
+    {
+      "type": "aspire",
+      "request": "launch",
+      "name": "Aspire: Launch",
+      "program": "${workspaceFolder}/examples/Aspire.AppHost/Examples.Aspire.AppHost.csproj",
+      "debuggers": {
+        "project": {
+          "console": "integratedTerminal",
+          "logging": {
+            "moduleLoad": false
+          }
+        },
+        "apphost": {
+          "stopAtEntry": true
+        }
+      }
+    }
+  ]
+}
diff --git a/.vscode/mcp.json b/.vscode/mcp.json
new file mode 100644
index 0000000..d542aa9
--- /dev/null
+++ b/.vscode/mcp.json
@@ -0,0 +1,12 @@
+{
+  "servers": {
+    "aspire": {
+      "type": "stdio",
+      "command": "aspire",
+      "args": [
+        "mcp",
+        "start"
+      ]
+    }
+  }
+}
\ No newline at end of file
diff --git a/.vscode/settings.json b/.vscode/settings.json
new file mode 100644
index 0000000..83352cf
--- /dev/null
+++ b/.vscode/settings.json
@@ -0,0 +1,19 @@
+{
+    "dotnet.defaultSolution": "RemoteContainers.slnx",
+    "editor.minimap.enabled": false,
+    "files.exclude": {
+      "**/bin": true,
+      "**/obj": true
+    },
+    "git.enableCommitSigning": true,
+    "csharp.debug.symbolOptions.searchNuGetOrgSymbolServer": true,
+    "csharp.debug.symbolOptions.searchMicrosoftSymbolServer": true,
+    "csharp.debug.justMyCode": true,
+    "csharp.debug.requireExactSource": true,
+    "csharp.debug.suppressJITOptimizations": false,
+    "editor.inlayHints.enabled": "on",
+    "csharp.inlayHints.enableInlayHintsForImplicitVariableTypes": true,
+    "csharp.inlayHints.enableInlayHintsForTypes": true,
+    "dotnet.inlayHints.enableInlayHintsForIndexerParameters": true,
+    "dotnet.inlayHints.enableInlayHintsForLiteralParameters": true
+}
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..3ba40f1
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,74 @@
+# Agent Instructions
+
+Instructions for GitHub Copilot and other AI coding agents working with the Aspire repository.
+
+## Repository Overview
+**RemoteContainers.Aspire** contains an extension that creates SSH tunnels for container resources if a DOCKER_HOST is configured in launch settings. It allows using a remote container runtime such as Docker Engine with Aspire.
+
+### Technology Stack
+- .NET 10.0 (LTS)
+- Aspire
+- C#
+- Multi-platform support (Windows, Linux, macOS, containers)
+
+## General
+
+* Make only high confidence suggestions when reviewing code changes.
+* Always use the version of C# that matches the latest .NET LTS.
+* Always use the latest released (stable) version of Aspire.
+* Never change global.json unless explicitly asked to.
+* Never change package.json or package-lock.json files unless explicitly asked to.
+* Never change NuGet.config files unless explicitly asked to.
+
+## Formatting
+
+* Apply code-formatting style defined in `.editorconfig` and `.editorconfig` files in nested directories.
+* Prefer file-scoped namespace declarations and single-line using directives.
+* Insert a newline before the opening curly brace of any code block (e.g., after `if`, `for`, `while`, `foreach`, `using`, `try`, etc.).
+* Ensure that the final return statement of a method is on its own line.
+* Use pattern matching and switch expressions wherever possible.
+* Use `nameof` instead of string literals when referring to member names.
+* Place private class declarations at the bottom of the file.
+
+### Nullable Reference Types
+
+* Declare variables non-nullable, and check for `null` at entry points.
+* Always use `is null` or `is not null` instead of `== null` or `!= null`.
+* Trust the C# null annotations and don't add null checks when the type system says a value cannot be null.
+
+## Project Layout and Architecture
+
+### Directory Structure
+- **`/src`**: Main source code for the Remote Containers Aspire extension
+- **`/exampels`**: Source code for an example App Host that uses the Containers Aspire extension
+
+### Key Configuration Files
+- **`global.json`**: Pins .NET SDK version - never modify without explicit request
+- **`.editorconfig`**: Code formatting rules, null annotations, diagnostic configurations
+- **`Directory.Build.props`**: Shared MSBuild properties across all projects
+- **`Directory.Build.targets`**: Shared project configuration
+- **`Directory.Packages.props`**: Centralized package version management
+- **`RemoteContainers.slnx`**: Main solution file (XML-based solution format)
+
+### Dependencies and Hidden Requirements
+- **Local .NET SDK**: Automatically uses local SDK when available after running restore due to paths configuration in global.json
+- **Package References**: Centrally managed via Directory.Packages.props
+
+## Markdown files
+
+* Markdown files should not have multiple consecutive blank lines.
+* Code blocks should be formatted with triple backticks (```) and include the language identifier for syntax highlighting.
+* JSON code blocks should be indented properly.
+
+## Available Skills
+
+The following specialized skills are available in `.github/skills/`:
+
+- **aspire**: Aspire skill covering the Aspire CLI, AppHost orchestration, service discovery, integrations, MCP server, VS Code extension, Dev Containers, templates, dashboard, and deployment
+
+## Trust These Instructions
+
+These instructions are comprehensive and tested. Only search for additional information if:
+1. The instructions appear outdated or incorrect
+2. You encounter specific errors not covered here
+3. You need details about new features not yet documented
diff --git a/Directory.Build.props b/Directory.Build.props
new file mode 100644
index 0000000..a4b2000
--- /dev/null
+++ b/Directory.Build.props
@@ -0,0 +1,23 @@
+<Project>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.SourceLink.GitHub">
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+      <PrivateAssets>all</PrivateAssets>
+    </PackageReference>
+    <PackageReference Include="Microsoft.CodeAnalysis.Analyzers">
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+      <PrivateAssets>all</PrivateAssets>
+    </PackageReference>
+    <PackageReference Include="Microsoft.CodeAnalysis.CSharp">
+      <PrivateAssets>all</PrivateAssets>
+    </PackageReference>
+    <PackageReference Include="StyleCop.Analyzers">
+      <PrivateAssets>all</PrivateAssets>
+    </PackageReference>
+  </ItemGroup>
+  <ItemGroup>
+    <AdditionalFiles Include="..\..\stylecop.json" />
+  </ItemGroup>
+
+</Project>
diff --git a/Directory.Build.targets b/Directory.Build.targets
new file mode 100644
index 0000000..2d36c62
--- /dev/null
+++ b/Directory.Build.targets
@@ -0,0 +1,15 @@
+<Project>
+
+  <PropertyGroup>
+    <RootNamespace>Hj.$(MSBuildProjectName.Replace(" ", "_"))</RootNamespace>
+    <LangVersion>Latest</LangVersion>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <Authors>Henrik Jensen</Authors>
+    <Copyright>Copyright 2026 Henrik Jensen</Copyright>
+    <PackageProjectUrl>https://github.com/henrikhimself/Aspire-RemoteContainers</PackageProjectUrl>
+    <RepositoryUrl>https://github.com/henrikhimself/Aspire-RemoteContainers.git</RepositoryUrl>
+    <RepositoryType>git</RepositoryType>
+  </PropertyGroup>
+
+</Project>
diff --git a/Directory.Packages.props b/Directory.Packages.props
new file mode 100644
index 0000000..8f1d427
--- /dev/null
+++ b/Directory.Packages.props
@@ -0,0 +1,16 @@
+<Project>
+
+  <PropertyGroup>
+    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
+  </PropertyGroup>
+  <ItemGroup>
+    <PackageVersion Include="Aspire.Hosting" Version="13.1.2" />
+    <PackageVersion Include="Microsoft.SourceLink.GitHub" Version="10.0.103" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.Analyzers" Version="5.3.0-2.final" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="5.3.0-2.final" />
+    <PackageVersion Include="Microsoft.Extensions.Http.Resilience" Version="10.3.0" />
+    <PackageVersion Include="SSH.NET" Version="2025.1.0" />
+    <PackageVersion Include="StyleCop.Analyzers" Version="1.2.0-beta.556 " />
+  </ItemGroup>
+
+</Project>
diff --git a/LICENSE b/LICENSE
index 5c3d694..261eeb9 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,21 +1,201 @@
-MIT License
-
-Copyright (c) 2026 Henrik Jensen
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
diff --git a/NuGet.config b/NuGet.config
new file mode 100644
index 0000000..993d13d
--- /dev/null
+++ b/NuGet.config
@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="utf-8"?>
+<configuration>
+  <packageSources>
+    <clear />
+    <add key="https://api.nuget.org/v3/index.json" value="https://api.nuget.org/v3/index.json" />
+  </packageSources>
+  <packageSourceMapping>
+    <packageSource key="https://api.nuget.org/v3/index.json">
+      <package pattern="*" />
+    </packageSource>
+  </packageSourceMapping>
+</configuration>
\ No newline at end of file
diff --git a/README.md b/README.md
index 9cb3435..d77b425 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,104 @@
-# Aspire-RemoteContainers
-Use Aspire with a remote Docker/Podman engine via SSH tunneling.
+# Aspire Remote Containers
+
+Use [Aspire](https://learn.microsoft.com/dotnet/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
+
+```shell
+dotnet add package HenrikJensen.RemoteContainers.Aspire
+```
+
+### Usage
+
+Add a single line to your Aspire AppHost:
+
+```csharp
+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 these in your Aspire AppHost `launchSettings.json`:
+
+| Variable | Description |
+|---|---|
+| `DOCKER_HOST` | Remote Docker engine address, e.g. `tcp://my-server:2376`. Must use the `tcp://` scheme. |
+| `DOCKER_TLS_VERIFY` | Set to 1 to enable TLS. |
+| `DOCKER_CERT_PATH` | Path to a directory containing `ca.pem`, `cert.pem`, and `key.pem` for mutual TLS authentication with the Docker API. |
+
+Example `launchSettings.json`:
+
+```json
+{
+  "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.):
+
+| Key | Default | Description |
+|---|---|---|
+| `SSH_HOST` | Hostname from `DOCKER_HOST` | Override the SSH connection target if it differs from the Docker API host. |
+| `SSH_USER` | Current OS username | Override the SSH username. |
+
+### 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](https://dotnet.microsoft.com/download) or later
+- [.NET Aspire](https://learn.microsoft.com/dotnet/aspire/fundamentals/setup-tooling)
+- A remote Docker or Podman engine exposed over TCP with TLS
+- SSH access to the remote host with key-based authentication
diff --git a/RemoteContainers.slnx b/RemoteContainers.slnx
new file mode 100644
index 0000000..0f6318f
--- /dev/null
+++ b/RemoteContainers.slnx
@@ -0,0 +1,6 @@
+<Solution>
+  <Folder Name="/examples/">
+    <Project Path="examples/Aspire.AppHost/Aspire.AppHost.csproj" />
+  </Folder>
+  <Project Path="src/RemoteContainers.Aspire/RemoteContainers.Aspire.csproj" />
+</Solution>
diff --git a/examples/.editorconfig b/examples/.editorconfig
new file mode 100644
index 0000000..d9a88d4
--- /dev/null
+++ b/examples/.editorconfig
@@ -0,0 +1,5 @@
+root = false
+
+[*.cs]
+# CA1515: Consider making public types internal
+dotnet_diagnostic.CA1515.severity = none
diff --git a/examples/Aspire.AppHost/Aspire.AppHost.csproj b/examples/Aspire.AppHost/Aspire.AppHost.csproj
new file mode 100644
index 0000000..385d255
--- /dev/null
+++ b/examples/Aspire.AppHost/Aspire.AppHost.csproj
@@ -0,0 +1,13 @@
+<Project Sdk="Aspire.AppHost.Sdk/13.1.2">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net10.0</TargetFramework>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="../../src/RemoteContainers.Aspire/RemoteContainers.Aspire.csproj" IsAspireProjectResource="false" />
+  </ItemGroup>
+
+</Project>
diff --git a/examples/Aspire.AppHost/Properties/launchSettings.json b/examples/Aspire.AppHost/Properties/launchSettings.json
new file mode 100644
index 0000000..ecc7486
--- /dev/null
+++ b/examples/Aspire.AppHost/Properties/launchSettings.json
@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json.schemastore.org/launchsettings.json",
+  "profiles": {
+    "https": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "applicationUrl": "https://localhost:17126;http://localhost:15238",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development",
+        "DOTNET_ENVIRONMENT": "Development",
+        "ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL": "https://localhost:21021",
+        "ASPIRE_DASHBOARD_MCP_ENDPOINT_URL": "https://localhost:23005",
+        "ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "https://localhost:22264",
+        "DOCKER_HOST": "tcp://lyn.td:2376",
+        "DOCKER_TLS_VERIFY": "1",
+        "DOCKER_CERT_PATH": "/opt/certs/client"
+      }
+    },
+    "http": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "applicationUrl": "http://localhost:15238",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development",
+        "DOTNET_ENVIRONMENT": "Development",
+        "ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL": "http://localhost:19033",
+        "ASPIRE_DASHBOARD_MCP_ENDPOINT_URL": "http://localhost:18068",
+        "ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "http://localhost:20172",
+        "DOCKER_HOST": "tcp://lyn.td:2376",
+        "DOCKER_TLS_VERIFY": "1",
+        "DOCKER_CERT_PATH": "/opt/certs/client"
+      }
+    }
+  }
+}
diff --git a/examples/Aspire.AppHost/apphost.cs b/examples/Aspire.AppHost/apphost.cs
new file mode 100644
index 0000000..ffafc3c
--- /dev/null
+++ b/examples/Aspire.AppHost/apphost.cs
@@ -0,0 +1,10 @@
+using Hj.RemoteContainers.Aspire;
+
+var builder = DistributedApplication.CreateBuilder(args);
+
+builder.AddSshTunneling();
+
+_ = builder.AddContainer("whoami", "traefik/whoami:latest")
+    .WithHttpEndpoint(port: 8080, targetPort: 80);
+
+await builder.Build().RunAsync();
diff --git a/examples/Aspire.AppHost/appsettings.json b/examples/Aspire.AppHost/appsettings.json
new file mode 100644
index 0000000..5d4dcfe
--- /dev/null
+++ b/examples/Aspire.AppHost/appsettings.json
@@ -0,0 +1,11 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning",
+      "Aspire.Hosting.Dcp": "Warning"
+    }
+  },
+  "SSH_HOST": "",
+  "SSH_USER": ""
+}
diff --git a/global.json b/global.json
new file mode 100644
index 0000000..55c1a3e
--- /dev/null
+++ b/global.json
@@ -0,0 +1,7 @@
+{
+  "sdk": {
+    "version": "10.0.0",
+    "rollForward": "major",
+    "allowPrerelease": false
+  }
+}
diff --git a/src/.editorconfig b/src/.editorconfig
new file mode 100644
index 0000000..92cd91f
--- /dev/null
+++ b/src/.editorconfig
@@ -0,0 +1,9 @@
+root = false
+
+[*.cs]
+# SA1633: A C# code file is missing a standard file header
+dotnet_diagnostic.SA1633.severity = error
+file_header_template=<copyright file="{fileName}" company="Henrik Jensen">\nCopyright 2025 Henrik Jensen\n\nLicensed under the Apache License, Version 2.0 (the "License")\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\nhttp://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an "AS IS" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n</copyright>
+
+# SA1636: The file header at the top of a C# code file does not contain the appropriate copyright text
+dotnet_diagnostic.SA1636.severity = none
diff --git a/src/RemoteContainers.Aspire/DockerApiClient.cs b/src/RemoteContainers.Aspire/DockerApiClient.cs
new file mode 100644
index 0000000..d3ce803
--- /dev/null
+++ b/src/RemoteContainers.Aspire/DockerApiClient.cs
@@ -0,0 +1,280 @@
+// <copyright file="DockerApiClient.cs" company="Henrik Jensen">
+// Copyright 2025 Henrik Jensen
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+using System.Diagnostics.CodeAnalysis;
+using System.Security.Cryptography.X509Certificates;
+using System.Text.Json;
+using Hj.RemoteContainers.Aspire.Models;
+using Microsoft.Extensions.Logging;
+
+namespace Hj.RemoteContainers.Aspire;
+
+/// <summary>
+/// Queries the Docker REST API to resolve container port bindings.
+/// </summary>
+internal sealed class DockerApiClient
+{
+  private static readonly TimeSpan _containerStartTimeout = TimeSpan.FromMinutes(5);
+  private static readonly TimeSpan _containerPollInterval = TimeSpan.FromSeconds(5);
+
+  private readonly ILogger<DockerApiClient> _logger;
+  private readonly HttpClient _httpClient;
+  private readonly bool _isEnabled;
+
+  public DockerApiClient(ILogger<DockerApiClient> logger, HttpClient httpClient)
+  {
+    _logger = logger;
+    _httpClient = httpClient;
+
+    var dockerHost = Environment.GetEnvironmentVariable("DOCKER_HOST");
+    _isEnabled = !string.IsNullOrEmpty(dockerHost) && dockerHost.StartsWith("tcp://", StringComparison.OrdinalIgnoreCase);
+  }
+
+  /// <summary>
+  /// Polls until the named container is running and returns ALL its published port mappings, or null if the container
+  /// is not found within the timeout.
+  /// </summary>
+  /// <remarks>
+  /// <para>
+  /// ResourceEndpointsAllocatedEvent fires before DCP actually starts containers on the remote Docker host, so an
+  /// immediate query would return an empty list. Polling handles this toctou.
+  /// </para>
+  /// <para>
+  /// A stale container from a previous Aspire run may still be running when the event fires. To avoid tunnelling the wrong ports,
+  /// the method requires the same container ID to appear on two consecutive polls before accepting the result. If DCP recycles
+  /// the container between polls the ID changes and polling continues until the replacement stabilises.
+  /// </para>
+  /// </remarks>
+  /// <param name="resourceName">A resource name for which remote container ports will be retrieved.</param>
+  /// <param name="cancellationToken">A cancellation token.</param>
+  /// <returns>
+  /// A dictionary mapping container port → Docker host port, or null when disabled or timed out.
+  /// </returns>
+  public async Task<IReadOnlyDictionary<int, int>?> GetAllContainerHostPortsAsync(
+    string resourceName,
+    CancellationToken cancellationToken = default)
+  {
+    if (!_isEnabled)
+    {
+      return null;
+    }
+
+    var deadline = DateTime.UtcNow + _containerStartTimeout;
+    string? lastSeenId = null;
+    var isFirstPoll = true;
+
+    while (DateTime.UtcNow < deadline)
+    {
+      try
+      {
+        var result = await TryQueryAllContainerHostPortsAsync(resourceName, cancellationToken);
+
+        if (result is not null)
+        {
+          if (isFirstPoll)
+          {
+            // Found on the very first attempt — might be a stale container from a previous Aspire run. Record the ID and re-poll to confirm.
+            lastSeenId = result.Id;
+            isFirstPoll = false;
+            await Task.Delay(_containerPollInterval, cancellationToken);
+            continue;
+          }
+
+          if (lastSeenId is null || result.Id == lastSeenId)
+          {
+            // Either appeared after an empty poll (definitely new) or confirmed stable across two consecutive polls. Accept.
+            return result.Ports;
+          }
+
+          // Container ID changed between polls — track the new one and re-confirm.
+          lastSeenId = result.Id;
+          await Task.Delay(_containerPollInterval, cancellationToken);
+          continue;
+        }
+
+        // Container not found — any future find is definitely from the current run.
+        lastSeenId = null;
+        isFirstPoll = false;
+      }
+      catch (HttpRequestException ex)
+      {
+        if (_logger.IsEnabled(LogLevel.Debug))
+        {
+          _logger.LogDebug(ex, "Docker API request failed for {ResourceName}; retrying…", resourceName);
+        }
+
+        lastSeenId = null;
+        isFirstPoll = false;
+        await Task.Delay(_containerPollInterval, cancellationToken);
+        continue;
+      }
+
+      if (_logger.IsEnabled(LogLevel.Debug))
+      {
+        _logger.LogDebug(
+          "Container {ResourceName} not yet visible in Docker; retrying in {Interval}ms…",
+          resourceName,
+          _containerPollInterval.TotalMilliseconds);
+      }
+
+      await Task.Delay(_containerPollInterval, cancellationToken);
+    }
+
+    if (_logger.IsEnabled(LogLevel.Warning))
+    {
+      _logger.LogWarning(
+        "Container {ResourceName} not found in Docker after {Timeout}s — no SSH tunnels created",
+        resourceName,
+        _containerStartTimeout.TotalSeconds);
+    }
+
+    return null;
+  }
+
+  /// <summary>
+  /// Creates the <see cref="HttpClientHandler"/> for the Docker API. Loads mutual TLS certificates
+  /// from DOCKER_CERT_PATH when DOCKER_HOST is a remote tcp:// address.
+  /// Throws <see cref="InvalidOperationException"/> if DOCKER_CERT_PATH is not set.
+  /// </summary>
+  /// <returns>A http client handler configured to use a client certificate.</returns>
+  [SuppressMessage(
+    "Reliability",
+    "CA2000:Dispose objects before losing scope",
+    Justification = "Certificates are app-lifetime objects: clientCert is owned by ClientCertificates, caCert is captured by the validation callback. Both live until process exit.")]
+  internal static HttpClientHandler CreateTlsHandler()
+  {
+    var dockerHost = Environment.GetEnvironmentVariable("DOCKER_HOST");
+
+    if (string.IsNullOrEmpty(dockerHost)
+      || !dockerHost.StartsWith("tcp://", StringComparison.OrdinalIgnoreCase))
+    {
+      return new HttpClientHandler();
+    }
+
+    var certPath = Environment.GetEnvironmentVariable("DOCKER_CERT_PATH")
+      ?? throw new InvalidOperationException(
+        "DOCKER_CERT_PATH must be set in the environment when DOCKER_HOST is a remote tcp:// address.");
+
+    var caCert = X509Certificate2.CreateFromPem(
+      File.ReadAllText(Path.Combine(certPath, "ca.pem")));
+
+    var clientCert = X509Certificate2.CreateFromPem(
+      File.ReadAllText(Path.Combine(certPath, "cert.pem")),
+      File.ReadAllText(Path.Combine(certPath, "key.pem")));
+
+    var handler = new HttpClientHandler();
+    handler.ClientCertificates.Add(clientCert);
+    handler.ServerCertificateCustomValidationCallback = (_, serverCert, chain, _) =>
+    {
+      chain!.ChainPolicy.CustomTrustStore.Add(caCert);
+      chain!.ChainPolicy.TrustMode = X509ChainTrustMode.CustomRootTrust;
+      return chain.Build(serverCert!);
+    };
+
+    return handler;
+  }
+
+  private async Task<ContainerPorts?> TryQueryAllContainerHostPortsAsync(
+    string resourceName,
+    CancellationToken cancellationToken)
+  {
+    var json = await _httpClient.GetStringAsync("containers/json", cancellationToken);
+
+    if (_logger.IsEnabled(LogLevel.Debug))
+    {
+      _logger.LogDebug("Docker containers/json for {ResourceName}: {Json}", resourceName, json);
+    }
+
+    using var doc = JsonDocument.Parse(json);
+    var resourcePrefix = resourceName + "-";
+
+    foreach (var container in doc.RootElement.EnumerateArray())
+    {
+      if (!container.TryGetProperty("Names", out var names))
+      {
+        continue;
+      }
+
+      var matched = false;
+      foreach (var nameEl in names.EnumerateArray())
+      {
+        var rawName = nameEl.GetString();
+        if (rawName is null)
+        {
+          continue;
+        }
+
+        // Docker API returns names with a leading "/" — strip it before comparing.
+        var name = rawName.AsSpan().TrimStart('/');
+        if (name.Equals(resourceName, StringComparison.OrdinalIgnoreCase)
+          || name.StartsWith(resourcePrefix, StringComparison.OrdinalIgnoreCase))
+        {
+          matched = true;
+          break;
+        }
+      }
+
+      if (!matched)
+      {
+        continue;
+      }
+
+      var containerId = container.TryGetProperty("Id", out var idProp) ? idProp.GetString() ?? string.Empty : string.Empty;
+
+      if (!container.TryGetProperty("Ports", out var ports))
+      {
+        continue;
+      }
+
+      var portMappings = new Dictionary<int, int>();
+
+      foreach (var port in ports.EnumerateArray())
+      {
+        if (port.TryGetProperty("PrivatePort", out var priv)
+          && priv.TryGetInt32(out var privPort)
+          && port.TryGetProperty("PublicPort", out var pub)
+          && pub.TryGetInt32(out var hostPort)
+          && hostPort > 0)
+        {
+          portMappings[privPort] = hostPort;
+        }
+      }
+
+      if (portMappings.Count > 0)
+      {
+        if (_logger.IsEnabled(LogLevel.Information))
+        {
+          foreach (var (containerPort, hostPort) in portMappings)
+          {
+            _logger.LogInformation(
+              "Resolved Docker host port: {ResourceName} container:{ContainerPort} → host:{HostPort}",
+              resourceName,
+              containerPort,
+              hostPort);
+          }
+        }
+
+        return new ContainerPorts()
+        {
+          Id = containerId,
+          Ports = portMappings,
+        };
+      }
+    }
+
+    return null;
+  }
+}
diff --git a/src/RemoteContainers.Aspire/Models/ContainerPorts.cs b/src/RemoteContainers.Aspire/Models/ContainerPorts.cs
new file mode 100644
index 0000000..9deac7b
--- /dev/null
+++ b/src/RemoteContainers.Aspire/Models/ContainerPorts.cs
@@ -0,0 +1,24 @@
+// <copyright file="ContainerPorts.cs" company="Henrik Jensen">
+// Copyright 2025 Henrik Jensen
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+namespace Hj.RemoteContainers.Aspire.Models;
+
+internal sealed record ContainerPorts
+{
+  public required string Id { get; init; }
+
+  public required Dictionary<int, int> Ports { get; init; }
+}
diff --git a/src/RemoteContainers.Aspire/RemoteContainers.Aspire.csproj b/src/RemoteContainers.Aspire/RemoteContainers.Aspire.csproj
new file mode 100644
index 0000000..6fb1d48
--- /dev/null
+++ b/src/RemoteContainers.Aspire/RemoteContainers.Aspire.csproj
@@ -0,0 +1,34 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <AnalysisMode>Recommended</AnalysisMode>
+    <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
+    <IsPackable>true</IsPackable>
+    <IncludeSymbols>true</IncludeSymbols>
+    <SymbolPackageFormat>snupkg</SymbolPackageFormat>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    <PackageId>HenrikJensen.RemoteContainers.Aspire</PackageId>
+    <Description>Use Aspire with a remote Docker/Podman engine via SSH tunneling.</Description>
+    <PackageTags>aspire;docker;podman;ssh;tunneling;remote;containers</PackageTags>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
+    <PackageLicenseFile>LICENSE</PackageLicenseFile>
+    <Version>1.0.0-beta1</Version>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <None Include="..\..\README.md" Pack="true" PackagePath="" />
+    <None Include="..\..\LICENSE" Pack="true" PackagePath="" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Aspire.Hosting" />
+    <PackageReference Include="Microsoft.Extensions.Http.Resilience" />
+    <PackageReference Include="SSH.NET" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <Folder Include="Models/" />
+  </ItemGroup>
+
+</Project>
diff --git a/src/RemoteContainers.Aspire/SshTunnelExtensions.cs b/src/RemoteContainers.Aspire/SshTunnelExtensions.cs
new file mode 100644
index 0000000..78e73b4
--- /dev/null
+++ b/src/RemoteContainers.Aspire/SshTunnelExtensions.cs
@@ -0,0 +1,58 @@
+// <copyright file="SshTunnelExtensions.cs" company="Henrik Jensen">
+// Copyright 2025 Henrik Jensen
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+using Aspire.Hosting;
+using Aspire.Hosting.Lifecycle;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.DependencyInjection.Extensions;
+
+namespace Hj.RemoteContainers.Aspire;
+
+public static class SshTunnelExtensions
+{
+  /// <summary>
+  /// Enables automatic SSH port forwarding for all container resources when DOCKER_HOST points to
+  /// a remote Docker engine. After DCP allocates endpoints, every resource with at least one endpoint
+  /// is matched against running Docker containers and tunnelled automatically.
+  /// </summary>
+  /// <param name="builder">An application builder instance.</param>
+  /// <returns>The application builder instance.</returns>
+  public static IDistributedApplicationBuilder AddSshTunneling(this IDistributedApplicationBuilder builder)
+  {
+    // Guard against double registration.
+    if (builder.Services.Any(d => d.ServiceType == typeof(SshTunnelManager)))
+    {
+      return builder;
+    }
+
+    builder.Services.AddHttpClient<DockerApiClient>(client =>
+    {
+      var dockerHost = Environment.GetEnvironmentVariable("DOCKER_HOST");
+      if (!string.IsNullOrEmpty(dockerHost)
+        && dockerHost.StartsWith("tcp://", StringComparison.OrdinalIgnoreCase))
+      {
+        client.BaseAddress = new Uri(
+          dockerHost.Replace("tcp://", "https://", StringComparison.OrdinalIgnoreCase));
+      }
+    })
+    .ConfigurePrimaryHttpMessageHandler(DockerApiClient.CreateTlsHandler)
+    .AddStandardResilienceHandler();
+
+    builder.Services.TryAddSingleton<SshTunnelManager>();
+    builder.Services.TryAddEventingSubscriber<SshTunnelLifecycleHook>();
+    return builder;
+  }
+}
diff --git a/src/RemoteContainers.Aspire/SshTunnelLifecycleHook.cs b/src/RemoteContainers.Aspire/SshTunnelLifecycleHook.cs
new file mode 100644
index 0000000..c7c21c0
--- /dev/null
+++ b/src/RemoteContainers.Aspire/SshTunnelLifecycleHook.cs
@@ -0,0 +1,51 @@
+// <copyright file="SshTunnelLifecycleHook.cs" company="Henrik Jensen">
+// Copyright 2025 Henrik Jensen
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+using Aspire.Hosting;
+using Aspire.Hosting.ApplicationModel;
+using Aspire.Hosting.Eventing;
+using Aspire.Hosting.Lifecycle;
+
+namespace Hj.RemoteContainers.Aspire;
+
+internal sealed class SshTunnelLifecycleHook : IDistributedApplicationEventingSubscriber
+{
+  private readonly SshTunnelManager _tunnelManager;
+
+  public SshTunnelLifecycleHook(SshTunnelManager tunnelManager) => _tunnelManager = tunnelManager;
+
+  public Task SubscribeAsync(
+    IDistributedApplicationEventing eventing,
+    DistributedApplicationExecutionContext executionContext,
+    CancellationToken cancellationToken = default)
+  {
+    eventing.Subscribe<ResourceEndpointsAllocatedEvent>(SetUpTunnelAsync);
+    return Task.CompletedTask;
+  }
+
+  private async Task SetUpTunnelAsync(
+    ResourceEndpointsAllocatedEvent evt,
+    CancellationToken cancellationToken)
+  {
+    // Only tunnel container resources.
+    if (!evt.Resource.Annotations.OfType<ContainerImageAnnotation>().Any())
+    {
+      return;
+    }
+
+    await _tunnelManager.AddAllContainerPortForwardsAsync(evt.Resource.Name, cancellationToken);
+  }
+}
diff --git a/src/RemoteContainers.Aspire/SshTunnelManager.cs b/src/RemoteContainers.Aspire/SshTunnelManager.cs
new file mode 100644
index 0000000..c798eb4
--- /dev/null
+++ b/src/RemoteContainers.Aspire/SshTunnelManager.cs
@@ -0,0 +1,225 @@
+// <copyright file="SshTunnelManager.cs" company="Henrik Jensen">
+// Copyright 2025 Henrik Jensen
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.Logging;
+using Renci.SshNet;
+
+namespace Hj.RemoteContainers.Aspire;
+
+/// <summary>
+/// Manages SSH port forwarding tunnels for remote Docker container access.
+/// </summary>
+internal sealed class SshTunnelManager : IDisposable
+{
+  private readonly ILogger<SshTunnelManager> _logger;
+  private readonly SshClient? _sshClient;
+  private readonly List<ForwardedPortLocal> _forwardedPorts = [];
+  private readonly object _lock = new();
+  private readonly PrivateKeyFile[]? _keyFiles;
+  private readonly DockerApiClient _dockerApiClient;
+
+  public SshTunnelManager(ILogger<SshTunnelManager> logger, IConfiguration configuration, DockerApiClient dockerApiClient)
+  {
+    _logger = logger;
+    _dockerApiClient = dockerApiClient;
+
+    var dockerHost = Environment.GetEnvironmentVariable("DOCKER_HOST");
+    var sshHost = configuration["SSH_HOST"];
+    var sshUser = configuration["SSH_USER"];
+
+    if (string.IsNullOrEmpty(dockerHost)
+      || !dockerHost.StartsWith("tcp://", StringComparison.OrdinalIgnoreCase))
+    {
+      _logger.LogInformation("SSH tunneling disabled - DOCKER_HOST is not a remote tcp:// address");
+      return;
+    }
+
+    if (string.IsNullOrEmpty(sshHost))
+    {
+      sshHost = new Uri(dockerHost).Host;
+    }
+
+    if (string.IsNullOrEmpty(sshUser))
+    {
+      sshUser = Environment.UserName;
+    }
+
+    try
+    {
+      if (_logger.IsEnabled(LogLevel.Information))
+      {
+        _logger.LogInformation("Connecting to SSH host {SshHost} as {SshUser}", sshHost, sshUser);
+      }
+
+      _keyFiles = LoadSshKeyFiles();
+      _sshClient = new SshClient(sshHost, sshUser, _keyFiles);
+      _sshClient.Connect();
+
+      if (_logger.IsEnabled(LogLevel.Information))
+      {
+        _logger.LogInformation("SSH connection established");
+      }
+    }
+    catch (Exception ex)
+    {
+      if (_logger.IsEnabled(LogLevel.Warning))
+      {
+        _logger.LogWarning(ex, "Failed to establish SSH connection - port forwarding disabled");
+      }
+
+      _sshClient?.Dispose();
+      _sshClient = null;
+    }
+  }
+
+  /// <summary>
+  /// Queries the Docker API for all published ports of the named container and creates SSH tunnels for each one.
+  /// </summary>
+  /// <param name="resourceName">A resource name for which remote container ports will be retrieved.</param>
+  /// <param name="cancellationToken">A cancellation token.</param>
+  /// <returns>A task.</returns>
+  public async Task AddAllContainerPortForwardsAsync(
+    string resourceName,
+    CancellationToken cancellationToken = default)
+  {
+    if (_sshClient is null || !_sshClient.IsConnected)
+    {
+      return;
+    }
+
+    var portMappings = await _dockerApiClient.GetAllContainerHostPortsAsync(resourceName, cancellationToken);
+
+    if (portMappings is null)
+    {
+      return;
+    }
+
+    foreach (var (containerPort, hostPort) in portMappings)
+    {
+      AddPortForward((uint)hostPort, $"{resourceName} (container:{containerPort})");
+    }
+  }
+
+  public void Dispose()
+  {
+    foreach (var port in _forwardedPorts)
+    {
+      try
+      {
+        port.Stop();
+        port.Dispose();
+      }
+      catch
+      {
+        // Best effort cleanup
+      }
+    }
+
+    _sshClient?.Disconnect();
+    _sshClient?.Dispose();
+
+    if (_keyFiles is not null)
+    {
+      foreach (var keyFile in _keyFiles)
+      {
+        keyFile.Dispose();
+      }
+    }
+
+    if (_logger.IsEnabled(LogLevel.Information))
+    {
+      _logger.LogInformation("SSH tunnels closed");
+    }
+  }
+
+  private static PrivateKeyFile[] LoadSshKeyFiles()
+  {
+    var homeDir = Environment.GetFolderPath(Environment.SpecialFolder.UserProfile);
+    var sshDir = Path.Combine(homeDir, ".ssh");
+
+    // Try common SSH key locations
+    var keyPaths = new[]
+    {
+      Path.Combine(sshDir, "id_rsa"),
+      Path.Combine(sshDir, "id_ed25519"),
+      Path.Combine(sshDir, "id_ecdsa"),
+    };
+
+    var keys = new List<PrivateKeyFile>();
+
+    foreach (var keyPath in keyPaths)
+    {
+      if (File.Exists(keyPath))
+      {
+        try
+        {
+          keys.Add(new PrivateKeyFile(keyPath));
+        }
+        catch
+        {
+          // Key might be encrypted or invalid, skip it
+        }
+      }
+    }
+
+    if (keys.Count == 0)
+    {
+      throw new InvalidOperationException(
+        $"No SSH private keys found in {sshDir}. Ensure you have id_rsa, id_ed25519, or id_ecdsa.");
+    }
+
+    return [.. keys];
+  }
+
+  /// <summary>
+  /// Creates a port forward from local port to remote localhost:port through the SSH tunnel.
+  /// </summary>
+  private void AddPortForward(uint port, string description)
+  {
+    if (_sshClient is null || !_sshClient.IsConnected)
+    {
+      return;
+    }
+
+    lock (_lock)
+    {
+      try
+      {
+        var forwardedPort = new ForwardedPortLocal("127.0.0.1", port, "127.0.0.1", port);
+        _sshClient.AddForwardedPort(forwardedPort);
+        forwardedPort.Start();
+        _forwardedPorts.Add(forwardedPort);
+
+        if (_logger.IsEnabled(LogLevel.Information))
+        {
+          _logger.LogInformation(
+            "Port forward established: localhost:{Port} → remote:{Port} ({Description})",
+            port,
+            port,
+            description);
+        }
+      }
+      catch (Exception ex)
+      {
+        if (_logger.IsEnabled(LogLevel.Warning))
+        {
+          _logger.LogWarning(ex, "Failed to create port forward for {Port} ({Description})", port, description);
+        }
+      }
+    }
+  }
+}
diff --git a/stylecop.json b/stylecop.json
new file mode 100644
index 0000000..ec0e302
--- /dev/null
+++ b/stylecop.json
@@ -0,0 +1,8 @@
+{
+  "$schema": "https://raw.githubusercontent.com/DotNetAnalyzers/StyleCopAnalyzers/master/StyleCop.Analyzers/StyleCop.Analyzers/Settings/stylecop.schema.json",
+  "settings": {
+    "documentationRules": {
+      "xmlHeader": true
+    }
+  }
+}

From ad579e7ae2b0463e7a99672040d9e1ab69af3272 Mon Sep 17 00:00:00 2001
From: Henrik Jensen <1175002+henrikhimself@users.noreply.github.com>
Date: Tue, 3 Mar 2026 09:17:22 +0100
Subject: [PATCH 02/25] Add ci/cd and dependbot. Fix launch.

---
 .github/dependabot.yml   | 12 ++++++++++++
 .github/workflows/cd.yml | 30 ++++++++++++++++++++++++++++++
 .github/workflows/ci.yml | 19 +++++++++++++++++++
 .vscode/extensions.json  |  2 ++
 .vscode/launch.json      | 16 +++-------------
 5 files changed, 66 insertions(+), 13 deletions(-)
 create mode 100644 .github/dependabot.yml
 create mode 100644 .github/workflows/cd.yml
 create mode 100644 .github/workflows/ci.yml

diff --git a/.github/dependabot.yml b/.github/dependabot.yml
new file mode 100644
index 0000000..8c73057
--- /dev/null
+++ b/.github/dependabot.yml
@@ -0,0 +1,12 @@
+version: 2
+updates:
+  - package-ecosystem: "nuget"
+    target-branch: "develop"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "github-actions"
+    target-branch: "develop"
+    directory: "/"
+    schedule:
+      interval: "weekly"
diff --git a/.github/workflows/cd.yml b/.github/workflows/cd.yml
new file mode 100644
index 0000000..9e70eeb
--- /dev/null
+++ b/.github/workflows/cd.yml
@@ -0,0 +1,30 @@
+name: cd
+
+on:
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      packages: read
+
+    steps:
+    - uses: actions/checkout@v6
+    - name: Setup CodeQL
+      uses: github/codeql-action/init@v4
+      with:
+        languages: csharp
+        build-mode: none
+    - name: Setup .NET
+      uses: actions/setup-dotnet@v5
+      with:
+        dotnet-version: 10.0.x
+    - name: Restore
+      run: dotnet restore
+    - name: Build
+      run: dotnet build --no-restore
+    - name: CodeQL Analysis
+      uses: github/codeql-action/analyze@v4
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..cc399d5
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,19 @@
+name: ci
+
+on:
+  push:
+    branches: [ "develop" ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v6
+    - name: Setup
+      uses: actions/setup-dotnet@v5
+      with:
+        dotnet-version: 10.0.x
+    - name: Build
+      run: dotnet build
+    - name: Test
+      run: dotnet test --no-build
diff --git a/.vscode/extensions.json b/.vscode/extensions.json
index 2657236..008720a 100644
--- a/.vscode/extensions.json
+++ b/.vscode/extensions.json
@@ -2,5 +2,7 @@
   "recommendations": [
     "editorconfig.editorconfig",
     "ms-dotnettools.csdevkit",
+    "github.vscode-github-actions",
+    "microsoft-aspire.aspire-vscode"
   ]
 }
diff --git a/.vscode/launch.json b/.vscode/launch.json
index 94a9555..5859962 100644
--- a/.vscode/launch.json
+++ b/.vscode/launch.json
@@ -1,21 +1,11 @@
 {
+  "version": "0.2.0",
   "configurations": [
     {
       "type": "aspire",
       "request": "launch",
-      "name": "Aspire: Launch",
-      "program": "${workspaceFolder}/examples/Aspire.AppHost/Examples.Aspire.AppHost.csproj",
-      "debuggers": {
-        "project": {
-          "console": "integratedTerminal",
-          "logging": {
-            "moduleLoad": false
-          }
-        },
-        "apphost": {
-          "stopAtEntry": true
-        }
-      }
+      "name": "Aspire: Launch default apphost",
+      "program": "${workspaceFolder}"
     }
   ]
 }

From b2fe88ff9fc363d600562a829c20dc21f952ec27 Mon Sep 17 00:00:00 2001
From: Henrik Jensen <1175002+henrikhimself@users.noreply.github.com>
Date: Sat, 7 Mar 2026 16:50:28 +0100
Subject: [PATCH 03/25] Address code review comments

---
 .editorconfig                                 |  2 +-
 .github/workflows/cd.yml                      |  2 +-
 AGENTS.md                                     | 28 ++++++-----------
 Directory.Build.props                         |  3 --
 Directory.Build.targets                       |  2 +-
 Directory.Packages.props                      |  2 +-
 README.md                                     |  6 ++--
 examples/Aspire.AppHost/Aspire.AppHost.csproj |  4 +++
 .../Aspire.AppHost/{apphost.cs => Program.cs} |  0
 .../Properties/launchSettings.json            | 18 +----------
 .../DockerApiClient.cs                        | 18 +++++------
 .../RemoteContainers.Aspire.csproj            |  2 +-
 .../SshTunnelExtensions.cs                    | 31 ++++++++++++-------
 .../SshTunnelManager.cs                       | 13 ++++----
 14 files changed, 57 insertions(+), 74 deletions(-)
 rename examples/Aspire.AppHost/{apphost.cs => Program.cs} (100%)

diff --git a/.editorconfig b/.editorconfig
index 7d8983c..2cddeca 100644
--- a/.editorconfig
+++ b/.editorconfig
@@ -23,7 +23,7 @@ indent_size = 2
 [*.{json,jsonc}]
 indent_size = 2
 
-[*.{sh,bash,ps1,,psm1}]
+[*.{sh,bash,ps1,psm1}]
 indent_style = space
 indent_size = 2
 insert_final_newline = true
diff --git a/.github/workflows/cd.yml b/.github/workflows/cd.yml
index 9e70eeb..2176aa3 100644
--- a/.github/workflows/cd.yml
+++ b/.github/workflows/cd.yml
@@ -17,7 +17,7 @@ jobs:
       uses: github/codeql-action/init@v4
       with:
         languages: csharp
-        build-mode: none
+        build-mode: manual
     - name: Setup .NET
       uses: actions/setup-dotnet@v5
       with:
diff --git a/AGENTS.md b/AGENTS.md
index 3ba40f1..5892514 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -12,7 +12,6 @@ Instructions for GitHub Copilot and other AI coding agents working with the Aspi
 - Multi-platform support (Windows, Linux, macOS, containers)
 
 ## General
-
 * Make only high confidence suggestions when reviewing code changes.
 * Always use the version of C# that matches the latest .NET LTS.
 * Always use the latest released (stable) version of Aspire.
@@ -21,7 +20,6 @@ Instructions for GitHub Copilot and other AI coding agents working with the Aspi
 * Never change NuGet.config files unless explicitly asked to.
 
 ## Formatting
-
 * Apply code-formatting style defined in `.editorconfig` and `.editorconfig` files in nested directories.
 * Prefer file-scoped namespace declarations and single-line using directives.
 * Insert a newline before the opening curly brace of any code block (e.g., after `if`, `for`, `while`, `foreach`, `using`, `try`, etc.).
@@ -31,11 +29,19 @@ Instructions for GitHub Copilot and other AI coding agents working with the Aspi
 * Place private class declarations at the bottom of the file.
 
 ### Nullable Reference Types
-
 * Declare variables non-nullable, and check for `null` at entry points.
 * Always use `is null` or `is not null` instead of `== null` or `!= null`.
 * Trust the C# null annotations and don't add null checks when the type system says a value cannot be null.
 
+## Markdown files
+* Markdown files should not have multiple consecutive blank lines.
+* Code blocks should be formatted with triple backticks (```) and include the language identifier for syntax highlighting.
+* JSON code blocks should be indented properly.
+
+## Available Skills
+The following specialized skills are available in `.github/skills/`:
+- **aspire**: Aspire skill covering the Aspire CLI, AppHost orchestration, service discovery, integrations, MCP server, VS Code extension, Dev Containers, templates, dashboard, and deployment
+
 ## Project Layout and Architecture
 
 ### Directory Structure
@@ -50,24 +56,10 @@ Instructions for GitHub Copilot and other AI coding agents working with the Aspi
 - **`Directory.Packages.props`**: Centralized package version management
 - **`RemoteContainers.slnx`**: Main solution file (XML-based solution format)
 
-### Dependencies and Hidden Requirements
-- **Local .NET SDK**: Automatically uses local SDK when available after running restore due to paths configuration in global.json
+### Dependencies
 - **Package References**: Centrally managed via Directory.Packages.props
 
-## Markdown files
-
-* Markdown files should not have multiple consecutive blank lines.
-* Code blocks should be formatted with triple backticks (```) and include the language identifier for syntax highlighting.
-* JSON code blocks should be indented properly.
-
-## Available Skills
-
-The following specialized skills are available in `.github/skills/`:
-
-- **aspire**: Aspire skill covering the Aspire CLI, AppHost orchestration, service discovery, integrations, MCP server, VS Code extension, Dev Containers, templates, dashboard, and deployment
-
 ## Trust These Instructions
-
 These instructions are comprehensive and tested. Only search for additional information if:
 1. The instructions appear outdated or incorrect
 2. You encounter specific errors not covered here
diff --git a/Directory.Build.props b/Directory.Build.props
index a4b2000..666ffb9 100644
--- a/Directory.Build.props
+++ b/Directory.Build.props
@@ -16,8 +16,5 @@
       <PrivateAssets>all</PrivateAssets>
     </PackageReference>
   </ItemGroup>
-  <ItemGroup>
-    <AdditionalFiles Include="..\..\stylecop.json" />
-  </ItemGroup>
 
 </Project>
diff --git a/Directory.Build.targets b/Directory.Build.targets
index 2d36c62..65e5728 100644
--- a/Directory.Build.targets
+++ b/Directory.Build.targets
@@ -6,7 +6,7 @@
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
     <Authors>Henrik Jensen</Authors>
-    <Copyright>Copyright 2026 Henrik Jensen</Copyright>
+    <Copyright>Copyright 2025 Henrik Jensen</Copyright>
     <PackageProjectUrl>https://github.com/henrikhimself/Aspire-RemoteContainers</PackageProjectUrl>
     <RepositoryUrl>https://github.com/henrikhimself/Aspire-RemoteContainers.git</RepositoryUrl>
     <RepositoryType>git</RepositoryType>
diff --git a/Directory.Packages.props b/Directory.Packages.props
index 8f1d427..0462473 100644
--- a/Directory.Packages.props
+++ b/Directory.Packages.props
@@ -10,7 +10,7 @@
     <PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="5.3.0-2.final" />
     <PackageVersion Include="Microsoft.Extensions.Http.Resilience" Version="10.3.0" />
     <PackageVersion Include="SSH.NET" Version="2025.1.0" />
-    <PackageVersion Include="StyleCop.Analyzers" Version="1.2.0-beta.556 " />
+    <PackageVersion Include="StyleCop.Analyzers" Version="1.2.0-beta.556" />
   </ItemGroup>
 
 </Project>
diff --git a/README.md b/README.md
index d77b425..be9bc68 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # Aspire Remote Containers
 
-Use [Aspire](https://learn.microsoft.com/dotnet/aspire/) with a remote Docker or Podman engine via automatic SSH port forwarding.
+Use Aspire with a remote Docker or Podman engine via automatic SSH port forwarding.
 
 ## The Problem
 
@@ -98,7 +98,7 @@ If `DOCKER_HOST` is not set or does not start with `tcp://`, the extension does
 
 ## Prerequisites
 
-- [.NET 10 SDK](https://dotnet.microsoft.com/download) or later
-- [.NET Aspire](https://learn.microsoft.com/dotnet/aspire/fundamentals/setup-tooling)
+- .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
diff --git a/examples/Aspire.AppHost/Aspire.AppHost.csproj b/examples/Aspire.AppHost/Aspire.AppHost.csproj
index 385d255..c9f3be2 100644
--- a/examples/Aspire.AppHost/Aspire.AppHost.csproj
+++ b/examples/Aspire.AppHost/Aspire.AppHost.csproj
@@ -10,4 +10,8 @@
     <ProjectReference Include="../../src/RemoteContainers.Aspire/RemoteContainers.Aspire.csproj" IsAspireProjectResource="false" />
   </ItemGroup>
 
+  <ItemGroup>
+    <AdditionalFiles Include="..\..\stylecop.json" />
+  </ItemGroup>
+
 </Project>
diff --git a/examples/Aspire.AppHost/apphost.cs b/examples/Aspire.AppHost/Program.cs
similarity index 100%
rename from examples/Aspire.AppHost/apphost.cs
rename to examples/Aspire.AppHost/Program.cs
diff --git a/examples/Aspire.AppHost/Properties/launchSettings.json b/examples/Aspire.AppHost/Properties/launchSettings.json
index ecc7486..35a14e4 100644
--- a/examples/Aspire.AppHost/Properties/launchSettings.json
+++ b/examples/Aspire.AppHost/Properties/launchSettings.json
@@ -12,23 +12,7 @@
         "ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL": "https://localhost:21021",
         "ASPIRE_DASHBOARD_MCP_ENDPOINT_URL": "https://localhost:23005",
         "ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "https://localhost:22264",
-        "DOCKER_HOST": "tcp://lyn.td:2376",
-        "DOCKER_TLS_VERIFY": "1",
-        "DOCKER_CERT_PATH": "/opt/certs/client"
-      }
-    },
-    "http": {
-      "commandName": "Project",
-      "dotnetRunMessages": true,
-      "launchBrowser": true,
-      "applicationUrl": "http://localhost:15238",
-      "environmentVariables": {
-        "ASPNETCORE_ENVIRONMENT": "Development",
-        "DOTNET_ENVIRONMENT": "Development",
-        "ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL": "http://localhost:19033",
-        "ASPIRE_DASHBOARD_MCP_ENDPOINT_URL": "http://localhost:18068",
-        "ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "http://localhost:20172",
-        "DOCKER_HOST": "tcp://lyn.td:2376",
+        "DOCKER_HOST": "tcp://docker-host.local:2376",
         "DOCKER_TLS_VERIFY": "1",
         "DOCKER_CERT_PATH": "/opt/certs/client"
       }
diff --git a/src/RemoteContainers.Aspire/DockerApiClient.cs b/src/RemoteContainers.Aspire/DockerApiClient.cs
index d3ce803..2ac2988 100644
--- a/src/RemoteContainers.Aspire/DockerApiClient.cs
+++ b/src/RemoteContainers.Aspire/DockerApiClient.cs
@@ -38,11 +38,11 @@ public DockerApiClient(ILogger<DockerApiClient> logger, HttpClient httpClient)
   {
     _logger = logger;
     _httpClient = httpClient;
-
-    var dockerHost = Environment.GetEnvironmentVariable("DOCKER_HOST");
-    _isEnabled = !string.IsNullOrEmpty(dockerHost) && dockerHost.StartsWith("tcp://", StringComparison.OrdinalIgnoreCase);
+    _isEnabled = httpClient.BaseAddress is not null;
   }
 
+  internal string? RemoteHost => _httpClient.BaseAddress?.Host;
+
   /// <summary>
   /// Polls until the named container is running and returns ALL its published port mappings, or null if the container
   /// is not found within the timeout.
@@ -146,27 +146,25 @@ public DockerApiClient(ILogger<DockerApiClient> logger, HttpClient httpClient)
 
   /// <summary>
   /// Creates the <see cref="HttpClientHandler"/> for the Docker API. Loads mutual TLS certificates
-  /// from DOCKER_CERT_PATH when DOCKER_HOST is a remote tcp:// address.
+  /// from DOCKER_CERT_PATH when TLS verification is enabled.
   /// Throws <see cref="InvalidOperationException"/> if DOCKER_CERT_PATH is not set.
   /// </summary>
+  /// <param name="tlsVerify">Whether DOCKER_TLS_VERIFY is enabled.</param>
   /// <returns>A http client handler configured to use a client certificate.</returns>
   [SuppressMessage(
     "Reliability",
     "CA2000:Dispose objects before losing scope",
     Justification = "Certificates are app-lifetime objects: clientCert is owned by ClientCertificates, caCert is captured by the validation callback. Both live until process exit.")]
-  internal static HttpClientHandler CreateTlsHandler()
+  internal static HttpClientHandler CreateTlsHandler(bool tlsVerify)
   {
-    var dockerHost = Environment.GetEnvironmentVariable("DOCKER_HOST");
-
-    if (string.IsNullOrEmpty(dockerHost)
-      || !dockerHost.StartsWith("tcp://", StringComparison.OrdinalIgnoreCase))
+    if (!tlsVerify)
     {
       return new HttpClientHandler();
     }
 
     var certPath = Environment.GetEnvironmentVariable("DOCKER_CERT_PATH")
       ?? throw new InvalidOperationException(
-        "DOCKER_CERT_PATH must be set in the environment when DOCKER_HOST is a remote tcp:// address.");
+        "DOCKER_CERT_PATH must be set in the environment when DOCKER_TLS_VERIFY=1.");
 
     var caCert = X509Certificate2.CreateFromPem(
       File.ReadAllText(Path.Combine(certPath, "ca.pem")));
diff --git a/src/RemoteContainers.Aspire/RemoteContainers.Aspire.csproj b/src/RemoteContainers.Aspire/RemoteContainers.Aspire.csproj
index 6fb1d48..5eb7ab9 100644
--- a/src/RemoteContainers.Aspire/RemoteContainers.Aspire.csproj
+++ b/src/RemoteContainers.Aspire/RemoteContainers.Aspire.csproj
@@ -28,7 +28,7 @@
   </ItemGroup>
 
   <ItemGroup>
-    <Folder Include="Models/" />
+    <AdditionalFiles Include="..\..\stylecop.json" />
   </ItemGroup>
 
 </Project>
diff --git a/src/RemoteContainers.Aspire/SshTunnelExtensions.cs b/src/RemoteContainers.Aspire/SshTunnelExtensions.cs
index 78e73b4..94c95f1 100644
--- a/src/RemoteContainers.Aspire/SshTunnelExtensions.cs
+++ b/src/RemoteContainers.Aspire/SshTunnelExtensions.cs
@@ -32,27 +32,34 @@ public static class SshTunnelExtensions
   /// <returns>The application builder instance.</returns>
   public static IDistributedApplicationBuilder AddSshTunneling(this IDistributedApplicationBuilder builder)
   {
-    // Guard against double registration.
-    if (builder.Services.Any(d => d.ServiceType == typeof(SshTunnelManager)))
+    var dockerHost = Environment.GetEnvironmentVariable("DOCKER_HOST");
+    if (string.IsNullOrWhiteSpace(dockerHost))
     {
       return builder;
     }
 
-    builder.Services.AddHttpClient<DockerApiClient>(client =>
+    if (!builder.Services.Any(d => d.ServiceType == typeof(DockerApiClient)))
     {
-      var dockerHost = Environment.GetEnvironmentVariable("DOCKER_HOST");
-      if (!string.IsNullOrEmpty(dockerHost)
-        && dockerHost.StartsWith("tcp://", StringComparison.OrdinalIgnoreCase))
+      var tlsVerify = string.Equals(
+        Environment.GetEnvironmentVariable("DOCKER_TLS_VERIFY"), "1", StringComparison.Ordinal);
+
+      builder.Services.AddHttpClient<DockerApiClient>(client =>
       {
-        client.BaseAddress = new Uri(
-          dockerHost.Replace("tcp://", "https://", StringComparison.OrdinalIgnoreCase));
-      }
-    })
-    .ConfigurePrimaryHttpMessageHandler(DockerApiClient.CreateTlsHandler)
-    .AddStandardResilienceHandler();
+        if (!string.IsNullOrEmpty(dockerHost)
+          && dockerHost.StartsWith("tcp://", StringComparison.OrdinalIgnoreCase))
+        {
+          var scheme = tlsVerify ? "https://" : "http://";
+          client.BaseAddress = new Uri(
+            dockerHost.Replace("tcp://", scheme, StringComparison.OrdinalIgnoreCase));
+        }
+      })
+      .ConfigurePrimaryHttpMessageHandler(() => DockerApiClient.CreateTlsHandler(tlsVerify))
+      .AddStandardResilienceHandler();
+    }
 
     builder.Services.TryAddSingleton<SshTunnelManager>();
     builder.Services.TryAddEventingSubscriber<SshTunnelLifecycleHook>();
+
     return builder;
   }
 }
diff --git a/src/RemoteContainers.Aspire/SshTunnelManager.cs b/src/RemoteContainers.Aspire/SshTunnelManager.cs
index c798eb4..dbdefc2 100644
--- a/src/RemoteContainers.Aspire/SshTunnelManager.cs
+++ b/src/RemoteContainers.Aspire/SshTunnelManager.cs
@@ -37,12 +37,11 @@ public SshTunnelManager(ILogger<SshTunnelManager> logger, IConfiguration configu
     _logger = logger;
     _dockerApiClient = dockerApiClient;
 
-    var dockerHost = Environment.GetEnvironmentVariable("DOCKER_HOST");
+    var remoteHost = dockerApiClient.RemoteHost;
     var sshHost = configuration["SSH_HOST"];
     var sshUser = configuration["SSH_USER"];
 
-    if (string.IsNullOrEmpty(dockerHost)
-      || !dockerHost.StartsWith("tcp://", StringComparison.OrdinalIgnoreCase))
+    if (remoteHost is null)
     {
       _logger.LogInformation("SSH tunneling disabled - DOCKER_HOST is not a remote tcp:// address");
       return;
@@ -50,7 +49,7 @@ public SshTunnelManager(ILogger<SshTunnelManager> logger, IConfiguration configu
 
     if (string.IsNullOrEmpty(sshHost))
     {
-      sshHost = new Uri(dockerHost).Host;
+      sshHost = remoteHost;
     }
 
     if (string.IsNullOrEmpty(sshUser))
@@ -197,13 +196,14 @@ private void AddPortForward(uint port, string description)
 
     lock (_lock)
     {
+      ForwardedPortLocal? forwardedPort = null;
       try
       {
-        var forwardedPort = new ForwardedPortLocal("127.0.0.1", port, "127.0.0.1", port);
+        forwardedPort = new ForwardedPortLocal("127.0.0.1", port, "127.0.0.1", port);
         _sshClient.AddForwardedPort(forwardedPort);
         forwardedPort.Start();
-        _forwardedPorts.Add(forwardedPort);
 
+        _forwardedPorts.Add(forwardedPort);
         if (_logger.IsEnabled(LogLevel.Information))
         {
           _logger.LogInformation(
@@ -215,6 +215,7 @@ private void AddPortForward(uint port, string description)
       }
       catch (Exception ex)
       {
+        forwardedPort?.Dispose();
         if (_logger.IsEnabled(LogLevel.Warning))
         {
           _logger.LogWarning(ex, "Failed to create port forward for {Port} ({Description})", port, description);

From e5965b55bc66cd7a360d75dcdef2e8c6b98464c6 Mon Sep 17 00:00:00 2001
From: Henrik Jensen <1175002+henrikhimself@users.noreply.github.com>
Date: Sat, 7 Mar 2026 17:07:14 +0100
Subject: [PATCH 04/25] Address code review comments

---
 .github/workflows/ci.yml                          |  2 --
 AGENTS.md                                         |  2 +-
 src/RemoteContainers.Aspire/DockerApiClient.cs    |  8 ++------
 .../SshTunnelLifecycleHook.cs                     |  9 ++-------
 src/RemoteContainers.Aspire/SshTunnelManager.cs   | 15 ++++++++++-----
 5 files changed, 15 insertions(+), 21 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index cc399d5..7c196d6 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -15,5 +15,3 @@ jobs:
         dotnet-version: 10.0.x
     - name: Build
       run: dotnet build
-    - name: Test
-      run: dotnet test --no-build
diff --git a/AGENTS.md b/AGENTS.md
index 5892514..585dff9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -46,7 +46,7 @@ The following specialized skills are available in `.github/skills/`:
 
 ### Directory Structure
 - **`/src`**: Main source code for the Remote Containers Aspire extension
-- **`/exampels`**: Source code for an example App Host that uses the Containers Aspire extension
+- **`/examples`**: Source code for an example App Host that uses the Containers Aspire extension
 
 ### Key Configuration Files
 - **`global.json`**: Pins .NET SDK version - never modify without explicit request
diff --git a/src/RemoteContainers.Aspire/DockerApiClient.cs b/src/RemoteContainers.Aspire/DockerApiClient.cs
index 2ac2988..404c6de 100644
--- a/src/RemoteContainers.Aspire/DockerApiClient.cs
+++ b/src/RemoteContainers.Aspire/DockerApiClient.cs
@@ -63,9 +63,7 @@ public DockerApiClient(ILogger<DockerApiClient> logger, HttpClient httpClient)
   /// <returns>
   /// A dictionary mapping container port → Docker host port, or null when disabled or timed out.
   /// </returns>
-  public async Task<IReadOnlyDictionary<int, int>?> GetAllContainerHostPortsAsync(
-    string resourceName,
-    CancellationToken cancellationToken = default)
+  public async Task<IReadOnlyDictionary<int, int>?> GetAllContainerHostPortsAsync(string resourceName, CancellationToken cancellationToken)
   {
     if (!_isEnabled)
     {
@@ -185,9 +183,7 @@ internal static HttpClientHandler CreateTlsHandler(bool tlsVerify)
     return handler;
   }
 
-  private async Task<ContainerPorts?> TryQueryAllContainerHostPortsAsync(
-    string resourceName,
-    CancellationToken cancellationToken)
+  private async Task<ContainerPorts?> TryQueryAllContainerHostPortsAsync(string resourceName, CancellationToken cancellationToken)
   {
     var json = await _httpClient.GetStringAsync("containers/json", cancellationToken);
 
diff --git a/src/RemoteContainers.Aspire/SshTunnelLifecycleHook.cs b/src/RemoteContainers.Aspire/SshTunnelLifecycleHook.cs
index c7c21c0..0a9f224 100644
--- a/src/RemoteContainers.Aspire/SshTunnelLifecycleHook.cs
+++ b/src/RemoteContainers.Aspire/SshTunnelLifecycleHook.cs
@@ -27,18 +27,13 @@ internal sealed class SshTunnelLifecycleHook : IDistributedApplicationEventingSu
 
   public SshTunnelLifecycleHook(SshTunnelManager tunnelManager) => _tunnelManager = tunnelManager;
 
-  public Task SubscribeAsync(
-    IDistributedApplicationEventing eventing,
-    DistributedApplicationExecutionContext executionContext,
-    CancellationToken cancellationToken = default)
+  public Task SubscribeAsync(IDistributedApplicationEventing eventing, DistributedApplicationExecutionContext executionContext, CancellationToken cancellationToken)
   {
     eventing.Subscribe<ResourceEndpointsAllocatedEvent>(SetUpTunnelAsync);
     return Task.CompletedTask;
   }
 
-  private async Task SetUpTunnelAsync(
-    ResourceEndpointsAllocatedEvent evt,
-    CancellationToken cancellationToken)
+  private async Task SetUpTunnelAsync(ResourceEndpointsAllocatedEvent evt, CancellationToken cancellationToken)
   {
     // Only tunnel container resources.
     if (!evt.Resource.Annotations.OfType<ContainerImageAnnotation>().Any())
diff --git a/src/RemoteContainers.Aspire/SshTunnelManager.cs b/src/RemoteContainers.Aspire/SshTunnelManager.cs
index dbdefc2..7667c72 100644
--- a/src/RemoteContainers.Aspire/SshTunnelManager.cs
+++ b/src/RemoteContainers.Aspire/SshTunnelManager.cs
@@ -91,9 +91,7 @@ public SshTunnelManager(ILogger<SshTunnelManager> logger, IConfiguration configu
   /// <param name="resourceName">A resource name for which remote container ports will be retrieved.</param>
   /// <param name="cancellationToken">A cancellation token.</param>
   /// <returns>A task.</returns>
-  public async Task AddAllContainerPortForwardsAsync(
-    string resourceName,
-    CancellationToken cancellationToken = default)
+  public async Task AddAllContainerPortForwardsAsync(string resourceName, CancellationToken cancellationToken)
   {
     if (_sshClient is null || !_sshClient.IsConnected)
     {
@@ -115,7 +113,14 @@ public async Task AddAllContainerPortForwardsAsync(
 
   public void Dispose()
   {
-    foreach (var port in _forwardedPorts)
+    ForwardedPortLocal[] portsSnapshot;
+    lock (_lock)
+    {
+      portsSnapshot = [.. _forwardedPorts];
+      _forwardedPorts.Clear();
+    }
+
+    foreach (var port in portsSnapshot)
     {
       try
       {
@@ -207,7 +212,7 @@ private void AddPortForward(uint port, string description)
         if (_logger.IsEnabled(LogLevel.Information))
         {
           _logger.LogInformation(
-            "Port forward established: localhost:{Port} → remote:{Port} ({Description})",
+            "Port forward established: localhost:{LocalPort} → remote:{RemotePort} ({Description})",
             port,
             port,
             description);

From ce3e439f0af80e8fb44cbb8d361983c0a2bf7680 Mon Sep 17 00:00:00 2001
From: Henrik Jensen <1175002+henrikhimself@users.noreply.github.com>
Date: Sat, 7 Mar 2026 17:10:05 +0100
Subject: [PATCH 05/25] Address code review comments

---
 src/RemoteContainers.Aspire/DockerApiClient.cs | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/src/RemoteContainers.Aspire/DockerApiClient.cs b/src/RemoteContainers.Aspire/DockerApiClient.cs
index 404c6de..50fc18a 100644
--- a/src/RemoteContainers.Aspire/DockerApiClient.cs
+++ b/src/RemoteContainers.Aspire/DockerApiClient.cs
@@ -175,9 +175,14 @@ internal static HttpClientHandler CreateTlsHandler(bool tlsVerify)
     handler.ClientCertificates.Add(clientCert);
     handler.ServerCertificateCustomValidationCallback = (_, serverCert, chain, _) =>
     {
-      chain!.ChainPolicy.CustomTrustStore.Add(caCert);
-      chain!.ChainPolicy.TrustMode = X509ChainTrustMode.CustomRootTrust;
-      return chain.Build(serverCert!);
+      if (serverCert is null || chain is null)
+      {
+        return false;
+      }
+
+      chain.ChainPolicy.CustomTrustStore.Add(caCert);
+      chain.ChainPolicy.TrustMode = X509ChainTrustMode.CustomRootTrust;
+      return chain.Build(serverCert);
     };
 
     return handler;

From 61f3f5e5b815f8c27c00bc697c65884d28789c89 Mon Sep 17 00:00:00 2001
From: Henrik Jensen <1175002+henrikhimself@users.noreply.github.com>
Date: Sun, 8 Mar 2026 11:59:32 +0100
Subject: [PATCH 06/25] Separate concerns and clean up

---
 .../Properties/launchSettings.json            |   2 +-
 .../AppConfiguration.cs                       | 116 ++++++++++
 .../DockerApiClient.cs                        | 108 ++-------
 .../Models/ContainerPorts.cs                  |   2 +-
 .../SshTunnelClient.cs                        | 143 ++++++++++++
 .../SshTunnelExtensions.cs                    |  50 +++--
 .../SshTunnelLifecycleHook.cs                 |  20 +-
 .../SshTunnelManager.cs                       | 210 +++++-------------
 8 files changed, 379 insertions(+), 272 deletions(-)
 create mode 100644 src/RemoteContainers.Aspire/AppConfiguration.cs
 create mode 100644 src/RemoteContainers.Aspire/SshTunnelClient.cs

diff --git a/examples/Aspire.AppHost/Properties/launchSettings.json b/examples/Aspire.AppHost/Properties/launchSettings.json
index 35a14e4..6c48947 100644
--- a/examples/Aspire.AppHost/Properties/launchSettings.json
+++ b/examples/Aspire.AppHost/Properties/launchSettings.json
@@ -12,7 +12,7 @@
         "ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL": "https://localhost:21021",
         "ASPIRE_DASHBOARD_MCP_ENDPOINT_URL": "https://localhost:23005",
         "ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "https://localhost:22264",
-        "DOCKER_HOST": "tcp://docker-host.local:2376",
+        "DOCKER_HOST": "tcp://lyn.td:2376",
         "DOCKER_TLS_VERIFY": "1",
         "DOCKER_CERT_PATH": "/opt/certs/client"
       }
diff --git a/src/RemoteContainers.Aspire/AppConfiguration.cs b/src/RemoteContainers.Aspire/AppConfiguration.cs
new file mode 100644
index 0000000..2446924
--- /dev/null
+++ b/src/RemoteContainers.Aspire/AppConfiguration.cs
@@ -0,0 +1,116 @@
+// <copyright file="AppConfiguration.cs" company="Henrik Jensen">
+// Copyright 2025 Henrik Jensen
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+using System.Collections;
+using System.Diagnostics.CodeAnalysis;
+using System.Security.Cryptography.X509Certificates;
+using Microsoft.Extensions.Configuration;
+
+namespace Hj.RemoteContainers.Aspire;
+
+internal sealed class AppConfiguration
+{
+  private readonly IConfiguration _configuration;
+  private readonly string _environmentUserName;
+  private readonly string _environmentUserProfilePath;
+  private readonly IDictionary _environmentVariables;
+
+  public AppConfiguration(IConfiguration configuration, string environmentUserName, string environmentUserProfilePath, IDictionary environmentVariables)
+  {
+    _configuration = configuration;
+    _environmentUserName = environmentUserName;
+    _environmentUserProfilePath = environmentUserProfilePath;
+    _environmentVariables = environmentVariables;
+  }
+
+  public string SshKeyPath => Path.Combine(_environmentUserProfilePath, ".ssh");
+
+  public string SshHost
+  {
+    get
+    {
+      var sshHost = _configuration["SSH_HOST"];
+      return string.IsNullOrWhiteSpace(sshHost)
+        ? (DockerHost?.Host ?? throw new InvalidOperationException("No SSH host found."))
+        : sshHost;
+    }
+  }
+
+  public string SshUser
+  {
+    get
+    {
+      var sshUser = _configuration["SSH_USER"];
+      return string.IsNullOrWhiteSpace(sshUser)
+        ? _environmentUserName
+        : sshUser;
+    }
+  }
+
+  [MemberNotNullWhen(true, nameof(DockerHost))]
+  public bool HasDockerHost => DockerHost is not null;
+
+  public UriBuilder? DockerHost
+  {
+    get
+    {
+      var dockerHost = (string?)_environmentVariables["DOCKER_HOST"];
+      if (dockerHost?.StartsWith("tcp://", StringComparison.OrdinalIgnoreCase) ?? false)
+      {
+        var uriBuilder = new UriBuilder(dockerHost)
+        {
+          Scheme = IsDockerTls ? "https://" : "http://",
+        };
+        return uriBuilder;
+      }
+
+      return null;
+    }
+  }
+
+  [MemberNotNullWhen(true, nameof(DockerCertPath))]
+  public bool IsDockerTls =>
+    string.Equals((string?)_environmentVariables["DOCKER_TLS_VERIFY"], "1", StringComparison.Ordinal)
+    && !string.IsNullOrWhiteSpace(DockerCertPath);
+
+  public string? DockerCertPath => (string?)_environmentVariables["DOCKER_CERT_PATH"];
+
+  public bool TryGetDockerCertificate([NotNullWhen(true)] out X509Certificate2? caCert, [NotNullWhen(true)] out X509Certificate2? clientCert)
+  {
+    caCert = null;
+    clientCert = null;
+
+    if (!IsDockerTls)
+    {
+      return false;
+    }
+
+    var caCertPath = Path.Combine(DockerCertPath, "ca.pem");
+    if (File.Exists(caCertPath))
+    {
+      caCert = X509Certificate2.CreateFromPem(File.ReadAllText(caCertPath));
+    }
+
+    var clientCertPath = Path.Combine(DockerCertPath, "cert.pem");
+    var clientKeyPath = Path.Combine(DockerCertPath, "key.pem");
+    if (File.Exists(clientCertPath) && File.Exists(clientKeyPath))
+    {
+      clientCert = X509Certificate2.CreateFromPem(File.ReadAllText(clientCertPath), File.ReadAllText(clientKeyPath));
+    }
+
+    return caCert is not null && clientCert is not null;
+  }
+}
diff --git a/src/RemoteContainers.Aspire/DockerApiClient.cs b/src/RemoteContainers.Aspire/DockerApiClient.cs
index 50fc18a..f30acdf 100644
--- a/src/RemoteContainers.Aspire/DockerApiClient.cs
+++ b/src/RemoteContainers.Aspire/DockerApiClient.cs
@@ -14,8 +14,6 @@
 // limitations under the License.
 // </copyright>
 
-using System.Diagnostics.CodeAnalysis;
-using System.Security.Cryptography.X509Certificates;
 using System.Text.Json;
 using Hj.RemoteContainers.Aspire.Models;
 using Microsoft.Extensions.Logging;
@@ -32,17 +30,13 @@ internal sealed class DockerApiClient
 
   private readonly ILogger<DockerApiClient> _logger;
   private readonly HttpClient _httpClient;
-  private readonly bool _isEnabled;
 
   public DockerApiClient(ILogger<DockerApiClient> logger, HttpClient httpClient)
   {
     _logger = logger;
     _httpClient = httpClient;
-    _isEnabled = httpClient.BaseAddress is not null;
   }
 
-  internal string? RemoteHost => _httpClient.BaseAddress?.Host;
-
   /// <summary>
   /// Polls until the named container is running and returns ALL its published port mappings, or null if the container
   /// is not found within the timeout.
@@ -63,13 +57,8 @@ public DockerApiClient(ILogger<DockerApiClient> logger, HttpClient httpClient)
   /// <returns>
   /// A dictionary mapping container port → Docker host port, or null when disabled or timed out.
   /// </returns>
-  public async Task<IReadOnlyDictionary<int, int>?> GetAllContainerHostPortsAsync(string resourceName, CancellationToken cancellationToken)
+  public async Task<List<uint>?> GetAllContainerHostPortsAsync(string resourceName, CancellationToken cancellationToken)
   {
-    if (!_isEnabled)
-    {
-      return null;
-    }
-
     var deadline = DateTime.UtcNow + _containerStartTimeout;
     string? lastSeenId = null;
     var isFirstPoll = true;
@@ -79,7 +68,6 @@ public DockerApiClient(ILogger<DockerApiClient> logger, HttpClient httpClient)
       try
       {
         var result = await TryQueryAllContainerHostPortsAsync(resourceName, cancellationToken);
-
         if (result is not null)
         {
           if (isFirstPoll)
@@ -93,7 +81,12 @@ public DockerApiClient(ILogger<DockerApiClient> logger, HttpClient httpClient)
 
           if (lastSeenId is null || result.Id == lastSeenId)
           {
-            // Either appeared after an empty poll (definitely new) or confirmed stable across two consecutive polls. Accept.
+            // Either appeared after an empty poll (definitely new) or confirmed stable across two consecutive polls.
+            if (_logger.IsEnabled(LogLevel.Information))
+            {
+              _logger.LogInformation("Resolved Docker port: {ResourceName}: {Port}", resourceName, string.Join(",", result.Ports));
+            }
+
             return result.Ports;
           }
 
@@ -116,16 +109,6 @@ public DockerApiClient(ILogger<DockerApiClient> logger, HttpClient httpClient)
 
         lastSeenId = null;
         isFirstPoll = false;
-        await Task.Delay(_containerPollInterval, cancellationToken);
-        continue;
-      }
-
-      if (_logger.IsEnabled(LogLevel.Debug))
-      {
-        _logger.LogDebug(
-          "Container {ResourceName} not yet visible in Docker; retrying in {Interval}ms…",
-          resourceName,
-          _containerPollInterval.TotalMilliseconds);
       }
 
       await Task.Delay(_containerPollInterval, cancellationToken);
@@ -142,52 +125,6 @@ public DockerApiClient(ILogger<DockerApiClient> logger, HttpClient httpClient)
     return null;
   }
 
-  /// <summary>
-  /// Creates the <see cref="HttpClientHandler"/> for the Docker API. Loads mutual TLS certificates
-  /// from DOCKER_CERT_PATH when TLS verification is enabled.
-  /// Throws <see cref="InvalidOperationException"/> if DOCKER_CERT_PATH is not set.
-  /// </summary>
-  /// <param name="tlsVerify">Whether DOCKER_TLS_VERIFY is enabled.</param>
-  /// <returns>A http client handler configured to use a client certificate.</returns>
-  [SuppressMessage(
-    "Reliability",
-    "CA2000:Dispose objects before losing scope",
-    Justification = "Certificates are app-lifetime objects: clientCert is owned by ClientCertificates, caCert is captured by the validation callback. Both live until process exit.")]
-  internal static HttpClientHandler CreateTlsHandler(bool tlsVerify)
-  {
-    if (!tlsVerify)
-    {
-      return new HttpClientHandler();
-    }
-
-    var certPath = Environment.GetEnvironmentVariable("DOCKER_CERT_PATH")
-      ?? throw new InvalidOperationException(
-        "DOCKER_CERT_PATH must be set in the environment when DOCKER_TLS_VERIFY=1.");
-
-    var caCert = X509Certificate2.CreateFromPem(
-      File.ReadAllText(Path.Combine(certPath, "ca.pem")));
-
-    var clientCert = X509Certificate2.CreateFromPem(
-      File.ReadAllText(Path.Combine(certPath, "cert.pem")),
-      File.ReadAllText(Path.Combine(certPath, "key.pem")));
-
-    var handler = new HttpClientHandler();
-    handler.ClientCertificates.Add(clientCert);
-    handler.ServerCertificateCustomValidationCallback = (_, serverCert, chain, _) =>
-    {
-      if (serverCert is null || chain is null)
-      {
-        return false;
-      }
-
-      chain.ChainPolicy.CustomTrustStore.Add(caCert);
-      chain.ChainPolicy.TrustMode = X509ChainTrustMode.CustomRootTrust;
-      return chain.Build(serverCert);
-    };
-
-    return handler;
-  }
-
   private async Task<ContainerPorts?> TryQueryAllContainerHostPortsAsync(string resourceName, CancellationToken cancellationToken)
   {
     var json = await _httpClient.GetStringAsync("containers/json", cancellationToken);
@@ -218,8 +155,7 @@ internal static HttpClientHandler CreateTlsHandler(bool tlsVerify)
 
         // Docker API returns names with a leading "/" — strip it before comparing.
         var name = rawName.AsSpan().TrimStart('/');
-        if (name.Equals(resourceName, StringComparison.OrdinalIgnoreCase)
-          || name.StartsWith(resourcePrefix, StringComparison.OrdinalIgnoreCase))
+        if (name.Equals(resourceName, StringComparison.OrdinalIgnoreCase) || name.StartsWith(resourcePrefix, StringComparison.OrdinalIgnoreCase))
         {
           matched = true;
           break;
@@ -232,40 +168,24 @@ internal static HttpClientHandler CreateTlsHandler(bool tlsVerify)
       }
 
       var containerId = container.TryGetProperty("Id", out var idProp) ? idProp.GetString() ?? string.Empty : string.Empty;
-
       if (!container.TryGetProperty("Ports", out var ports))
       {
         continue;
       }
 
-      var portMappings = new Dictionary<int, int>();
-
-      foreach (var port in ports.EnumerateArray())
+      var portMappings = new List<uint>();
+      foreach (var portElement in ports.EnumerateArray())
       {
-        if (port.TryGetProperty("PrivatePort", out var priv)
-          && priv.TryGetInt32(out var privPort)
-          && port.TryGetProperty("PublicPort", out var pub)
-          && pub.TryGetInt32(out var hostPort)
-          && hostPort > 0)
+        if (portElement.TryGetProperty("PublicPort", out var publicPort)
+          && publicPort.TryGetUInt32(out var port)
+          && port > 0)
         {
-          portMappings[privPort] = hostPort;
+          portMappings.Add(port);
         }
       }
 
       if (portMappings.Count > 0)
       {
-        if (_logger.IsEnabled(LogLevel.Information))
-        {
-          foreach (var (containerPort, hostPort) in portMappings)
-          {
-            _logger.LogInformation(
-              "Resolved Docker host port: {ResourceName} container:{ContainerPort} → host:{HostPort}",
-              resourceName,
-              containerPort,
-              hostPort);
-          }
-        }
-
         return new ContainerPorts()
         {
           Id = containerId,
diff --git a/src/RemoteContainers.Aspire/Models/ContainerPorts.cs b/src/RemoteContainers.Aspire/Models/ContainerPorts.cs
index 9deac7b..e7774e2 100644
--- a/src/RemoteContainers.Aspire/Models/ContainerPorts.cs
+++ b/src/RemoteContainers.Aspire/Models/ContainerPorts.cs
@@ -20,5 +20,5 @@ internal sealed record ContainerPorts
 {
   public required string Id { get; init; }
 
-  public required Dictionary<int, int> Ports { get; init; }
+  public required List<uint> Ports { get; init; }
 }
diff --git a/src/RemoteContainers.Aspire/SshTunnelClient.cs b/src/RemoteContainers.Aspire/SshTunnelClient.cs
new file mode 100644
index 0000000..fc29fd5
--- /dev/null
+++ b/src/RemoteContainers.Aspire/SshTunnelClient.cs
@@ -0,0 +1,143 @@
+// <copyright file="SshTunnelClient.cs" company="Henrik Jensen">
+// Copyright 2025 Henrik Jensen
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+using Renci.SshNet;
+
+namespace Hj.RemoteContainers.Aspire;
+
+internal sealed class SshTunnelClient : IDisposable
+{
+  private readonly List<PrivateKeyFile> _keyFiles;
+
+  private readonly SshClient _sshClient;
+
+  private bool _disposedValue;
+
+  private SshTunnelClient(List<PrivateKeyFile> keyFiles, SshClient sshClient)
+  {
+    _keyFiles = keyFiles;
+    _sshClient = sshClient;
+  }
+
+  internal bool IsConnected => _sshClient.IsConnected;
+
+  public void Dispose()
+  {
+    Dispose(disposing: true);
+    GC.SuppressFinalize(this);
+  }
+
+  internal static SshTunnelClient Connect(string keyDir, string sshHost, string sshUser)
+  {
+    if (!Directory.Exists(keyDir))
+    {
+      throw new InvalidOperationException($"SSH key path '{keyDir}' does not exist.");
+    }
+
+    var keyFiles = LoadSshKeyFiles(keyDir);
+    if (keyFiles.Count == 0)
+    {
+      throw new InvalidOperationException("No SSH private keys found.");
+    }
+
+    var sshClient = ConnectSshClient(keyFiles, sshHost, sshUser);
+    return new(keyFiles, sshClient);
+  }
+
+  internal bool TryForwardPort(uint port, out ForwardedPortLocal? forwardedPort)
+  {
+    forwardedPort = null;
+    try
+    {
+#pragma warning disable CA2000 // Dispose objects before losing scope
+      forwardedPort = new ForwardedPortLocal("127.0.0.1", port, "127.0.0.1", port);
+#pragma warning restore CA2000 // Dispose objects before losing scope
+      _sshClient.AddForwardedPort(forwardedPort);
+      forwardedPort.Start();
+      return true;
+    }
+    catch (Exception)
+    {
+      forwardedPort?.Dispose();
+      return false;
+    }
+  }
+
+  private static SshClient ConnectSshClient(List<PrivateKeyFile> keyFiles, string sshHost, string sshUser)
+  {
+    var sshClient = new SshClient(sshHost, sshUser, [.. keyFiles]);
+    try
+    {
+      sshClient.Connect();
+      return sshClient;
+    }
+    catch (Exception)
+    {
+      sshClient.Dispose();
+      throw;
+    }
+  }
+
+  private static List<PrivateKeyFile> LoadSshKeyFiles(string keyDir)
+  {
+    var keyPaths = new[]
+    {
+      Path.Combine(keyDir, "id_rsa"),
+      Path.Combine(keyDir, "id_ed25519"),
+      Path.Combine(keyDir, "id_ecdsa"),
+    };
+
+    var keys = new List<PrivateKeyFile>();
+    foreach (var keyPath in keyPaths)
+    {
+      if (File.Exists(keyPath))
+      {
+        try
+        {
+          keys.Add(new PrivateKeyFile(keyPath));
+        }
+        catch
+        {
+          // Key might be encrypted or invalid, skip it
+        }
+      }
+    }
+
+    return keys;
+  }
+
+  private void Dispose(bool disposing)
+  {
+    if (!_disposedValue)
+    {
+      if (disposing)
+      {
+        _sshClient.Disconnect();
+        _sshClient.Dispose();
+
+        if (_keyFiles is not null)
+        {
+          foreach (var keyFile in _keyFiles)
+          {
+            keyFile.Dispose();
+          }
+        }
+      }
+
+      _disposedValue = true;
+    }
+  }
+}
diff --git a/src/RemoteContainers.Aspire/SshTunnelExtensions.cs b/src/RemoteContainers.Aspire/SshTunnelExtensions.cs
index 94c95f1..32dbc17 100644
--- a/src/RemoteContainers.Aspire/SshTunnelExtensions.cs
+++ b/src/RemoteContainers.Aspire/SshTunnelExtensions.cs
@@ -14,10 +14,10 @@
 // limitations under the License.
 // </copyright>
 
+using System.Security.Cryptography.X509Certificates;
 using Aspire.Hosting;
 using Aspire.Hosting.Lifecycle;
 using Microsoft.Extensions.DependencyInjection;
-using Microsoft.Extensions.DependencyInjection.Extensions;
 
 namespace Hj.RemoteContainers.Aspire;
 
@@ -32,33 +32,49 @@ public static class SshTunnelExtensions
   /// <returns>The application builder instance.</returns>
   public static IDistributedApplicationBuilder AddSshTunneling(this IDistributedApplicationBuilder builder)
   {
-    var dockerHost = Environment.GetEnvironmentVariable("DOCKER_HOST");
-    if (string.IsNullOrWhiteSpace(dockerHost))
+    var environmentUserName = Environment.UserName;
+    var environmentUserProfilePath = Environment.GetFolderPath(Environment.SpecialFolder.UserProfile);
+    var environmentVariables = Environment.GetEnvironmentVariables();
+
+    AppConfiguration appConfiguration = new(builder.Configuration, environmentUserName, environmentUserProfilePath, environmentVariables);
+    if (!appConfiguration.HasDockerHost)
     {
+      // Skip setting up SSH tunnels.
       return builder;
     }
 
-    if (!builder.Services.Any(d => d.ServiceType == typeof(DockerApiClient)))
-    {
-      var tlsVerify = string.Equals(
-        Environment.GetEnvironmentVariable("DOCKER_TLS_VERIFY"), "1", StringComparison.Ordinal);
+    var services = builder.Services;
+    services.AddSingleton(appConfiguration);
 
-      builder.Services.AddHttpClient<DockerApiClient>(client =>
+    builder.Services.AddHttpClient<DockerApiClient>(httpClient =>
+      {
+        httpClient.BaseAddress = appConfiguration.DockerHost.Uri;
+      })
+      .ConfigurePrimaryHttpMessageHandler(() =>
       {
-        if (!string.IsNullOrEmpty(dockerHost)
-          && dockerHost.StartsWith("tcp://", StringComparison.OrdinalIgnoreCase))
+        var handler = new HttpClientHandler();
+        if (appConfiguration.TryGetDockerCertificate(out var caCert, out var clientCert))
         {
-          var scheme = tlsVerify ? "https://" : "http://";
-          client.BaseAddress = new Uri(
-            dockerHost.Replace("tcp://", scheme, StringComparison.OrdinalIgnoreCase));
+          handler.ClientCertificates.Add(clientCert);
+          handler.ServerCertificateCustomValidationCallback = (_, serverCert, chain, _) =>
+          {
+            if (serverCert is null || chain is null)
+            {
+              return false;
+            }
+
+            chain.ChainPolicy.CustomTrustStore.Add(caCert);
+            chain.ChainPolicy.TrustMode = X509ChainTrustMode.CustomRootTrust;
+            return chain.Build(serverCert);
+          };
         }
+
+        return handler;
       })
-      .ConfigurePrimaryHttpMessageHandler(() => DockerApiClient.CreateTlsHandler(tlsVerify))
       .AddStandardResilienceHandler();
-    }
 
-    builder.Services.TryAddSingleton<SshTunnelManager>();
-    builder.Services.TryAddEventingSubscriber<SshTunnelLifecycleHook>();
+    builder.Services.AddSingleton<SshTunnelManager>();
+    builder.Services.AddEventingSubscriber<SshTunnelLifecycleHook>();
 
     return builder;
   }
diff --git a/src/RemoteContainers.Aspire/SshTunnelLifecycleHook.cs b/src/RemoteContainers.Aspire/SshTunnelLifecycleHook.cs
index 0a9f224..07dcdbb 100644
--- a/src/RemoteContainers.Aspire/SshTunnelLifecycleHook.cs
+++ b/src/RemoteContainers.Aspire/SshTunnelLifecycleHook.cs
@@ -18,14 +18,20 @@
 using Aspire.Hosting.ApplicationModel;
 using Aspire.Hosting.Eventing;
 using Aspire.Hosting.Lifecycle;
+using Microsoft.Extensions.Logging;
 
 namespace Hj.RemoteContainers.Aspire;
 
 internal sealed class SshTunnelLifecycleHook : IDistributedApplicationEventingSubscriber
 {
+  private readonly ILogger<SshTunnelManager> _logger;
   private readonly SshTunnelManager _tunnelManager;
 
-  public SshTunnelLifecycleHook(SshTunnelManager tunnelManager) => _tunnelManager = tunnelManager;
+  public SshTunnelLifecycleHook(ILogger<SshTunnelManager> logger, SshTunnelManager tunnelManager)
+  {
+    _logger = logger;
+    _tunnelManager = tunnelManager;
+  }
 
   public Task SubscribeAsync(IDistributedApplicationEventing eventing, DistributedApplicationExecutionContext executionContext, CancellationToken cancellationToken)
   {
@@ -41,6 +47,16 @@ private async Task SetUpTunnelAsync(ResourceEndpointsAllocatedEvent evt, Cancell
       return;
     }
 
-    await _tunnelManager.AddAllContainerPortForwardsAsync(evt.Resource.Name, cancellationToken);
+    try
+    {
+      await _tunnelManager.AddAllContainerPortForwardsAsync(evt.Resource.Name, cancellationToken);
+    }
+    catch (Exception ex)
+    {
+      if (_logger.IsEnabled(LogLevel.Error))
+      {
+        _logger.LogError(ex, "Failed to set up SSH tunnel");
+      }
+    }
   }
 }
diff --git a/src/RemoteContainers.Aspire/SshTunnelManager.cs b/src/RemoteContainers.Aspire/SshTunnelManager.cs
index 7667c72..0a01e3e 100644
--- a/src/RemoteContainers.Aspire/SshTunnelManager.cs
+++ b/src/RemoteContainers.Aspire/SshTunnelManager.cs
@@ -14,7 +14,7 @@
 // limitations under the License.
 // </copyright>
 
-using Microsoft.Extensions.Configuration;
+using System.Collections.Concurrent;
 using Microsoft.Extensions.Logging;
 using Renci.SshNet;
 
@@ -26,63 +26,19 @@ namespace Hj.RemoteContainers.Aspire;
 internal sealed class SshTunnelManager : IDisposable
 {
   private readonly ILogger<SshTunnelManager> _logger;
-  private readonly SshClient? _sshClient;
-  private readonly List<ForwardedPortLocal> _forwardedPorts = [];
-  private readonly object _lock = new();
-  private readonly PrivateKeyFile[]? _keyFiles;
+  private readonly AppConfiguration _appConfiguration;
   private readonly DockerApiClient _dockerApiClient;
+  private readonly Lazy<SshTunnelClient> _sshTunnelClient;
 
-  public SshTunnelManager(ILogger<SshTunnelManager> logger, IConfiguration configuration, DockerApiClient dockerApiClient)
+  private readonly ConcurrentBag<ForwardedPortLocal> _forwardedPorts = [];
+  private bool _disposedValue;
+
+  public SshTunnelManager(ILogger<SshTunnelManager> logger, AppConfiguration appConfiguration, DockerApiClient dockerApiClient)
   {
     _logger = logger;
+    _appConfiguration = appConfiguration;
     _dockerApiClient = dockerApiClient;
-
-    var remoteHost = dockerApiClient.RemoteHost;
-    var sshHost = configuration["SSH_HOST"];
-    var sshUser = configuration["SSH_USER"];
-
-    if (remoteHost is null)
-    {
-      _logger.LogInformation("SSH tunneling disabled - DOCKER_HOST is not a remote tcp:// address");
-      return;
-    }
-
-    if (string.IsNullOrEmpty(sshHost))
-    {
-      sshHost = remoteHost;
-    }
-
-    if (string.IsNullOrEmpty(sshUser))
-    {
-      sshUser = Environment.UserName;
-    }
-
-    try
-    {
-      if (_logger.IsEnabled(LogLevel.Information))
-      {
-        _logger.LogInformation("Connecting to SSH host {SshHost} as {SshUser}", sshHost, sshUser);
-      }
-
-      _keyFiles = LoadSshKeyFiles();
-      _sshClient = new SshClient(sshHost, sshUser, _keyFiles);
-      _sshClient.Connect();
-
-      if (_logger.IsEnabled(LogLevel.Information))
-      {
-        _logger.LogInformation("SSH connection established");
-      }
-    }
-    catch (Exception ex)
-    {
-      if (_logger.IsEnabled(LogLevel.Warning))
-      {
-        _logger.LogWarning(ex, "Failed to establish SSH connection - port forwarding disabled");
-      }
-
-      _sshClient?.Dispose();
-      _sshClient = null;
-    }
+    _sshTunnelClient = new Lazy<SshTunnelClient>(ConnectSshTunnelClient);
   }
 
   /// <summary>
@@ -93,139 +49,79 @@ public SshTunnelManager(ILogger<SshTunnelManager> logger, IConfiguration configu
   /// <returns>A task.</returns>
   public async Task AddAllContainerPortForwardsAsync(string resourceName, CancellationToken cancellationToken)
   {
-    if (_sshClient is null || !_sshClient.IsConnected)
+    if (!_sshTunnelClient.Value.IsConnected)
     {
       return;
     }
 
     var portMappings = await _dockerApiClient.GetAllContainerHostPortsAsync(resourceName, cancellationToken);
-
     if (portMappings is null)
     {
       return;
     }
 
-    foreach (var (containerPort, hostPort) in portMappings)
-    {
-      AddPortForward((uint)hostPort, $"{resourceName} (container:{containerPort})");
-    }
-  }
-
-  public void Dispose()
-  {
-    ForwardedPortLocal[] portsSnapshot;
-    lock (_lock)
-    {
-      portsSnapshot = [.. _forwardedPorts];
-      _forwardedPorts.Clear();
-    }
-
-    foreach (var port in portsSnapshot)
+    foreach (var port in portMappings)
     {
-      try
+#pragma warning disable CA2000 // Dispose objects before losing scope
+      var isPortForwarded = _sshTunnelClient.Value.TryForwardPort(port, out var forwardedPort);
+#pragma warning restore CA2000 // Dispose objects before losing scope
+      if (forwardedPort is not null)
       {
-        port.Stop();
-        port.Dispose();
+        _forwardedPorts.Add(forwardedPort);
       }
-      catch
+
+      if (isPortForwarded)
       {
-        // Best effort cleanup
+        if (_logger.IsEnabled(LogLevel.Information))
+        {
+          _logger.LogInformation(
+            "Port forwarded: localhost:{Port} → remote:{Port}",
+            port,
+            port);
+        }
       }
-    }
-
-    _sshClient?.Disconnect();
-    _sshClient?.Dispose();
-
-    if (_keyFiles is not null)
-    {
-      foreach (var keyFile in _keyFiles)
+      else if (_logger.IsEnabled(LogLevel.Warning))
       {
-        keyFile.Dispose();
+        _logger.LogWarning(
+            "Failed to forward port: localhost:{Port} → remote:{Port}",
+            port,
+            port);
       }
     }
-
-    if (_logger.IsEnabled(LogLevel.Information))
-    {
-      _logger.LogInformation("SSH tunnels closed");
-    }
   }
 
-  private static PrivateKeyFile[] LoadSshKeyFiles()
+  public void Dispose()
   {
-    var homeDir = Environment.GetFolderPath(Environment.SpecialFolder.UserProfile);
-    var sshDir = Path.Combine(homeDir, ".ssh");
-
-    // Try common SSH key locations
-    var keyPaths = new[]
-    {
-      Path.Combine(sshDir, "id_rsa"),
-      Path.Combine(sshDir, "id_ed25519"),
-      Path.Combine(sshDir, "id_ecdsa"),
-    };
-
-    var keys = new List<PrivateKeyFile>();
-
-    foreach (var keyPath in keyPaths)
-    {
-      if (File.Exists(keyPath))
-      {
-        try
-        {
-          keys.Add(new PrivateKeyFile(keyPath));
-        }
-        catch
-        {
-          // Key might be encrypted or invalid, skip it
-        }
-      }
-    }
-
-    if (keys.Count == 0)
-    {
-      throw new InvalidOperationException(
-        $"No SSH private keys found in {sshDir}. Ensure you have id_rsa, id_ed25519, or id_ecdsa.");
-    }
-
-    return [.. keys];
+    Dispose(disposing: true);
+    GC.SuppressFinalize(this);
   }
 
-  /// <summary>
-  /// Creates a port forward from local port to remote localhost:port through the SSH tunnel.
-  /// </summary>
-  private void AddPortForward(uint port, string description)
+  private void Dispose(bool disposing)
   {
-    if (_sshClient is null || !_sshClient.IsConnected)
+    if (!_disposedValue)
     {
-      return;
-    }
-
-    lock (_lock)
-    {
-      ForwardedPortLocal? forwardedPort = null;
-      try
+      if (disposing)
       {
-        forwardedPort = new ForwardedPortLocal("127.0.0.1", port, "127.0.0.1", port);
-        _sshClient.AddForwardedPort(forwardedPort);
-        forwardedPort.Start();
-
-        _forwardedPorts.Add(forwardedPort);
-        if (_logger.IsEnabled(LogLevel.Information))
+        while (_forwardedPorts.TryTake(out var forwardedPort))
         {
-          _logger.LogInformation(
-            "Port forward established: localhost:{LocalPort} → remote:{RemotePort} ({Description})",
-            port,
-            port,
-            description);
-        }
-      }
-      catch (Exception ex)
-      {
-        forwardedPort?.Dispose();
-        if (_logger.IsEnabled(LogLevel.Warning))
-        {
-          _logger.LogWarning(ex, "Failed to create port forward for {Port} ({Description})", port, description);
+          try
+          {
+            forwardedPort.Stop();
+            forwardedPort.Dispose();
+          }
+          catch
+          {
+            // Best effort cleanup
+          }
         }
+
+        _sshTunnelClient.Value.Dispose();
       }
+
+      _disposedValue = true;
     }
   }
+
+  private SshTunnelClient ConnectSshTunnelClient()
+    => SshTunnelClient.Connect(_appConfiguration.SshKeyPath, _appConfiguration.SshHost, _appConfiguration.SshUser);
 }

From 992cb8efe22ea22152376dbbffb4fee3be57ebde Mon Sep 17 00:00:00 2001
From: Henrik Jensen <1175002+henrikhimself@users.noreply.github.com>
Date: Sun, 8 Mar 2026 14:15:14 +0100
Subject: [PATCH 07/25] Address code review comments

---
 .../AppConfiguration.cs                       | 32 +++++++++++++------
 .../SshTunnelClient.cs                        |  8 ++---
 .../SshTunnelLifecycleHook.cs                 |  4 +--
 .../SshTunnelManager.cs                       |  5 ++-
 4 files changed, 32 insertions(+), 17 deletions(-)

diff --git a/src/RemoteContainers.Aspire/AppConfiguration.cs b/src/RemoteContainers.Aspire/AppConfiguration.cs
index 2446924..389884e 100644
--- a/src/RemoteContainers.Aspire/AppConfiguration.cs
+++ b/src/RemoteContainers.Aspire/AppConfiguration.cs
@@ -72,7 +72,7 @@ public UriBuilder? DockerHost
       {
         var uriBuilder = new UriBuilder(dockerHost)
         {
-          Scheme = IsDockerTls ? "https://" : "http://",
+          Scheme = IsDockerTls ? "https" : "http",
         };
         return uriBuilder;
       }
@@ -98,19 +98,33 @@ public bool TryGetDockerCertificate([NotNullWhen(true)] out X509Certificate2? ca
       return false;
     }
 
-    var caCertPath = Path.Combine(DockerCertPath, "ca.pem");
-    if (File.Exists(caCertPath))
+    if (!TryCreateCertificate(Path.Combine(DockerCertPath, "ca.pem"), null, out caCert))
     {
-      caCert = X509Certificate2.CreateFromPem(File.ReadAllText(caCertPath));
+      return false;
+    }
+
+    if (!TryCreateCertificate(Path.Combine(DockerCertPath, "cert.pem"), Path.Combine(DockerCertPath, "key.pem"), out clientCert))
+    {
+      caCert.Dispose();
+      return false;
     }
 
-    var clientCertPath = Path.Combine(DockerCertPath, "cert.pem");
-    var clientKeyPath = Path.Combine(DockerCertPath, "key.pem");
-    if (File.Exists(clientCertPath) && File.Exists(clientKeyPath))
+    return true;
+  }
+
+  [SuppressMessage("Reliability", "CA2000:Dispose objects before losing scope", Justification = "Disposed elsewhere")]
+  private static bool TryCreateCertificate(string certPath, string? keyPath, [NotNullWhen(true)] out X509Certificate2? cert)
+  {
+    var certPem = File.Exists(certPath) ? File.ReadAllText(certPath) : null;
+    var keyPem = File.Exists(keyPath) ? File.ReadAllText(keyPath) : null;
+
+    if (keyPem is null)
     {
-      clientCert = X509Certificate2.CreateFromPem(File.ReadAllText(clientCertPath), File.ReadAllText(clientKeyPath));
+      cert = string.IsNullOrWhiteSpace(certPem) ? null : X509Certificate2.CreateFromPem(certPem);
+      return cert is not null;
     }
 
-    return caCert is not null && clientCert is not null;
+    cert = string.IsNullOrWhiteSpace(certPem) ? null : X509Certificate2.CreateFromPem(certPem, keyPem);
+    return cert is not null;
   }
 }
diff --git a/src/RemoteContainers.Aspire/SshTunnelClient.cs b/src/RemoteContainers.Aspire/SshTunnelClient.cs
index fc29fd5..8d04b21 100644
--- a/src/RemoteContainers.Aspire/SshTunnelClient.cs
+++ b/src/RemoteContainers.Aspire/SshTunnelClient.cs
@@ -72,6 +72,7 @@ internal bool TryForwardPort(uint port, out ForwardedPortLocal? forwardedPort)
     catch (Exception)
     {
       forwardedPort?.Dispose();
+      forwardedPort = null;
       return false;
     }
   }
@@ -128,12 +129,9 @@ private void Dispose(bool disposing)
         _sshClient.Disconnect();
         _sshClient.Dispose();
 
-        if (_keyFiles is not null)
+        foreach (var keyFile in _keyFiles)
         {
-          foreach (var keyFile in _keyFiles)
-          {
-            keyFile.Dispose();
-          }
+          keyFile.Dispose();
         }
       }
 
diff --git a/src/RemoteContainers.Aspire/SshTunnelLifecycleHook.cs b/src/RemoteContainers.Aspire/SshTunnelLifecycleHook.cs
index 07dcdbb..89ff27b 100644
--- a/src/RemoteContainers.Aspire/SshTunnelLifecycleHook.cs
+++ b/src/RemoteContainers.Aspire/SshTunnelLifecycleHook.cs
@@ -24,10 +24,10 @@ namespace Hj.RemoteContainers.Aspire;
 
 internal sealed class SshTunnelLifecycleHook : IDistributedApplicationEventingSubscriber
 {
-  private readonly ILogger<SshTunnelManager> _logger;
+  private readonly ILogger<SshTunnelLifecycleHook> _logger;
   private readonly SshTunnelManager _tunnelManager;
 
-  public SshTunnelLifecycleHook(ILogger<SshTunnelManager> logger, SshTunnelManager tunnelManager)
+  public SshTunnelLifecycleHook(ILogger<SshTunnelLifecycleHook> logger, SshTunnelManager tunnelManager)
   {
     _logger = logger;
     _tunnelManager = tunnelManager;
diff --git a/src/RemoteContainers.Aspire/SshTunnelManager.cs b/src/RemoteContainers.Aspire/SshTunnelManager.cs
index 0a01e3e..62784b6 100644
--- a/src/RemoteContainers.Aspire/SshTunnelManager.cs
+++ b/src/RemoteContainers.Aspire/SshTunnelManager.cs
@@ -115,7 +115,10 @@ private void Dispose(bool disposing)
           }
         }
 
-        _sshTunnelClient.Value.Dispose();
+        if (_sshTunnelClient.IsValueCreated)
+        {
+          _sshTunnelClient.Value.Dispose();
+        }
       }
 
       _disposedValue = true;

From 7032c8bf7f7fc76ed2e217c7d293c15c9d0465c0 Mon Sep 17 00:00:00 2001
From: Henrik Jensen <1175002+henrikhimself@users.noreply.github.com>
Date: Sun, 8 Mar 2026 14:16:13 +0100
Subject: [PATCH 08/25] Remove mcp.json

---
 .vscode/mcp.json | 12 ------------
 1 file changed, 12 deletions(-)
 delete mode 100644 .vscode/mcp.json

diff --git a/.vscode/mcp.json b/.vscode/mcp.json
deleted file mode 100644
index d542aa9..0000000
--- a/.vscode/mcp.json
+++ /dev/null
@@ -1,12 +0,0 @@
-{
-  "servers": {
-    "aspire": {
-      "type": "stdio",
-      "command": "aspire",
-      "args": [
-        "mcp",
-        "start"
-      ]
-    }
-  }
-}
\ No newline at end of file

From 30d26b0a6c8e3e71a5c1250bb80161f4744a297c Mon Sep 17 00:00:00 2001
From: Henrik Jensen <1175002+henrikhimself@users.noreply.github.com>
Date: Sun, 8 Mar 2026 14:18:12 +0100
Subject: [PATCH 09/25] Update README.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 README.md | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index be9bc68..05cbda3 100644
--- a/README.md
+++ b/README.md
@@ -46,15 +46,22 @@ No changes are needed to your container resource definitions - the tunneling is
 
 ### Required Environment Variables
 
-Add these in your Aspire AppHost `launchSettings.json`:
+Add this in your Aspire AppHost `launchSettings.json`:
 
 | Variable | Description |
 |---|---|
 | `DOCKER_HOST` | Remote Docker engine address, e.g. `tcp://my-server:2376`. Must use the `tcp://` scheme. |
-| `DOCKER_TLS_VERIFY` | Set to 1 to enable TLS. |
+
+### Optional Environment Variables (TLS)
+
+Set these if your remote Docker endpoint requires TLS:
+
+| Variable | Description |
+|---|---|
+| `DOCKER_TLS_VERIFY` | Set to `1` to enable TLS when connecting to `DOCKER_HOST`. |
 | `DOCKER_CERT_PATH` | Path to a directory containing `ca.pem`, `cert.pem`, and `key.pem` for mutual TLS authentication with the Docker API. |
 
-Example `launchSettings.json`:
+Example `launchSettings.json` with TLS enabled:
 
 ```json
 {

From a42dadadbd9323241c93daec6cc41763d63c934b Mon Sep 17 00:00:00 2001
From: Henrik Jensen <1175002+henrikhimself@users.noreply.github.com>
Date: Sun, 8 Mar 2026 14:20:17 +0100
Subject: [PATCH 10/25] Update launch settings

---
 examples/Aspire.AppHost/Properties/launchSettings.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/Aspire.AppHost/Properties/launchSettings.json b/examples/Aspire.AppHost/Properties/launchSettings.json
index 6c48947..312548a 100644
--- a/examples/Aspire.AppHost/Properties/launchSettings.json
+++ b/examples/Aspire.AppHost/Properties/launchSettings.json
@@ -12,7 +12,7 @@
         "ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL": "https://localhost:21021",
         "ASPIRE_DASHBOARD_MCP_ENDPOINT_URL": "https://localhost:23005",
         "ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "https://localhost:22264",
-        "DOCKER_HOST": "tcp://lyn.td:2376",
+        "DOCKER_HOST": "tcp://my-server:2376",
         "DOCKER_TLS_VERIFY": "1",
         "DOCKER_CERT_PATH": "/opt/certs/client"
       }

From 6207e749927d965dd419360d5e59fc58cfbae311 Mon Sep 17 00:00:00 2001
From: Henrik Jensen <1175002+henrikhimself@users.noreply.github.com>
Date: Tue, 10 Mar 2026 08:42:58 +0100
Subject: [PATCH 11/25] Support stop/start container with port forward renewal

---
 Directory.Build.targets                       |   2 +-
 src/.editorconfig                             |   2 +-
 .../AppConfiguration.cs                       |  47 +------
 .../DockerApiClient.cs                        |   8 +-
 .../DockerCertificate.cs                      | 122 ++++++++++++++++++
 .../Models/ContainerPorts.cs                  |   2 +-
 .../SshTunnelClient.cs                        |  86 ++++++------
 .../SshTunnelExtensions.cs                    |  62 +++++----
 .../SshTunnelLifecycleHook.cs                 |  57 +++++++-
 .../SshTunnelManager.cs                       |  83 +++++++-----
 10 files changed, 315 insertions(+), 156 deletions(-)
 create mode 100644 src/RemoteContainers.Aspire/DockerCertificate.cs

diff --git a/Directory.Build.targets b/Directory.Build.targets
index 65e5728..2d36c62 100644
--- a/Directory.Build.targets
+++ b/Directory.Build.targets
@@ -6,7 +6,7 @@
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
     <Authors>Henrik Jensen</Authors>
-    <Copyright>Copyright 2025 Henrik Jensen</Copyright>
+    <Copyright>Copyright 2026 Henrik Jensen</Copyright>
     <PackageProjectUrl>https://github.com/henrikhimself/Aspire-RemoteContainers</PackageProjectUrl>
     <RepositoryUrl>https://github.com/henrikhimself/Aspire-RemoteContainers.git</RepositoryUrl>
     <RepositoryType>git</RepositoryType>
diff --git a/src/.editorconfig b/src/.editorconfig
index 92cd91f..91d55fe 100644
--- a/src/.editorconfig
+++ b/src/.editorconfig
@@ -3,7 +3,7 @@ root = false
 [*.cs]
 # SA1633: A C# code file is missing a standard file header
 dotnet_diagnostic.SA1633.severity = error
-file_header_template=<copyright file="{fileName}" company="Henrik Jensen">\nCopyright 2025 Henrik Jensen\n\nLicensed under the Apache License, Version 2.0 (the "License")\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\nhttp://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an "AS IS" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n</copyright>
+file_header_template=<copyright file="{fileName}" company="Henrik Jensen">\nCopyright 2026 Henrik Jensen\n\nLicensed under the Apache License, Version 2.0 (the "License")\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\nhttp://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an "AS IS" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n</copyright>
 
 # SA1636: The file header at the top of a C# code file does not contain the appropriate copyright text
 dotnet_diagnostic.SA1636.severity = none
diff --git a/src/RemoteContainers.Aspire/AppConfiguration.cs b/src/RemoteContainers.Aspire/AppConfiguration.cs
index 389884e..25f5aa5 100644
--- a/src/RemoteContainers.Aspire/AppConfiguration.cs
+++ b/src/RemoteContainers.Aspire/AppConfiguration.cs
@@ -1,5 +1,5 @@
 // <copyright file="AppConfiguration.cs" company="Henrik Jensen">
-// Copyright 2025 Henrik Jensen
+// Copyright 2026 Henrik Jensen
 //
 // Licensed under the Apache License, Version 2.0 (the "License")
 // you may not use this file except in compliance with the License.
@@ -16,7 +16,6 @@
 
 using System.Collections;
 using System.Diagnostics.CodeAnalysis;
-using System.Security.Cryptography.X509Certificates;
 using Microsoft.Extensions.Configuration;
 
 namespace Hj.RemoteContainers.Aspire;
@@ -83,48 +82,8 @@ public UriBuilder? DockerHost
 
   [MemberNotNullWhen(true, nameof(DockerCertPath))]
   public bool IsDockerTls =>
-    string.Equals((string?)_environmentVariables["DOCKER_TLS_VERIFY"], "1", StringComparison.Ordinal)
-    && !string.IsNullOrWhiteSpace(DockerCertPath);
+    !string.IsNullOrWhiteSpace(DockerCertPath)
+    && string.Equals((string?)_environmentVariables["DOCKER_TLS_VERIFY"], "1", StringComparison.Ordinal);
 
   public string? DockerCertPath => (string?)_environmentVariables["DOCKER_CERT_PATH"];
-
-  public bool TryGetDockerCertificate([NotNullWhen(true)] out X509Certificate2? caCert, [NotNullWhen(true)] out X509Certificate2? clientCert)
-  {
-    caCert = null;
-    clientCert = null;
-
-    if (!IsDockerTls)
-    {
-      return false;
-    }
-
-    if (!TryCreateCertificate(Path.Combine(DockerCertPath, "ca.pem"), null, out caCert))
-    {
-      return false;
-    }
-
-    if (!TryCreateCertificate(Path.Combine(DockerCertPath, "cert.pem"), Path.Combine(DockerCertPath, "key.pem"), out clientCert))
-    {
-      caCert.Dispose();
-      return false;
-    }
-
-    return true;
-  }
-
-  [SuppressMessage("Reliability", "CA2000:Dispose objects before losing scope", Justification = "Disposed elsewhere")]
-  private static bool TryCreateCertificate(string certPath, string? keyPath, [NotNullWhen(true)] out X509Certificate2? cert)
-  {
-    var certPem = File.Exists(certPath) ? File.ReadAllText(certPath) : null;
-    var keyPem = File.Exists(keyPath) ? File.ReadAllText(keyPath) : null;
-
-    if (keyPem is null)
-    {
-      cert = string.IsNullOrWhiteSpace(certPem) ? null : X509Certificate2.CreateFromPem(certPem);
-      return cert is not null;
-    }
-
-    cert = string.IsNullOrWhiteSpace(certPem) ? null : X509Certificate2.CreateFromPem(certPem, keyPem);
-    return cert is not null;
-  }
 }
diff --git a/src/RemoteContainers.Aspire/DockerApiClient.cs b/src/RemoteContainers.Aspire/DockerApiClient.cs
index f30acdf..1589852 100644
--- a/src/RemoteContainers.Aspire/DockerApiClient.cs
+++ b/src/RemoteContainers.Aspire/DockerApiClient.cs
@@ -1,5 +1,5 @@
 // <copyright file="DockerApiClient.cs" company="Henrik Jensen">
-// Copyright 2025 Henrik Jensen
+// Copyright 2026 Henrik Jensen
 //
 // Licensed under the Apache License, Version 2.0 (the "License")
 // you may not use this file except in compliance with the License.
@@ -55,7 +55,7 @@ public DockerApiClient(ILogger<DockerApiClient> logger, HttpClient httpClient)
   /// <param name="resourceName">A resource name for which remote container ports will be retrieved.</param>
   /// <param name="cancellationToken">A cancellation token.</param>
   /// <returns>
-  /// A dictionary mapping container port → Docker host port, or null when disabled or timed out.
+  /// A list of published host ports, or null when timed out.
   /// </returns>
   public async Task<List<uint>?> GetAllContainerHostPortsAsync(string resourceName, CancellationToken cancellationToken)
   {
@@ -102,9 +102,9 @@ public DockerApiClient(ILogger<DockerApiClient> logger, HttpClient httpClient)
       }
       catch (HttpRequestException ex)
       {
-        if (_logger.IsEnabled(LogLevel.Debug))
+        if (_logger.IsEnabled(LogLevel.Error))
         {
-          _logger.LogDebug(ex, "Docker API request failed for {ResourceName}; retrying…", resourceName);
+          _logger.LogError(ex, "Docker API request failed for {ResourceName}; retrying…", resourceName);
         }
 
         lastSeenId = null;
diff --git a/src/RemoteContainers.Aspire/DockerCertificate.cs b/src/RemoteContainers.Aspire/DockerCertificate.cs
new file mode 100644
index 0000000..9b7aff4
--- /dev/null
+++ b/src/RemoteContainers.Aspire/DockerCertificate.cs
@@ -0,0 +1,122 @@
+// <copyright file="DockerCertificate.cs" company="Henrik Jensen">
+// Copyright 2026 Henrik Jensen
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+using System.Diagnostics.CodeAnalysis;
+using System.Security.Cryptography.X509Certificates;
+using Microsoft.Extensions.Logging;
+
+namespace Hj.RemoteContainers.Aspire;
+
+internal sealed class DockerCertificate : IDisposable
+{
+  private readonly ILogger<DockerCertificate> _logger;
+  private readonly AppConfiguration _appConfiguration;
+
+  private X509Certificate2? _caCert;
+  private X509Certificate2? _clientCert;
+  private bool _disposedValue;
+
+  public DockerCertificate(ILogger<DockerCertificate> logger, AppConfiguration appConfiguration)
+  {
+    _logger = logger;
+    _appConfiguration = appConfiguration;
+  }
+
+  [SuppressMessage("Reliability", "CA2000:Dispose objects before losing scope", Justification = "Disposed by caller")]
+  public bool TryGetCertificate([NotNullWhen(true)] out X509Certificate2? caCert, [NotNullWhen(true)] out X509Certificate2? clientCert)
+  {
+    caCert = null;
+    clientCert = null;
+
+    if (!_appConfiguration.IsDockerTls)
+    {
+      return false;
+    }
+
+    var dockerCertPath = _appConfiguration.DockerCertPath;
+
+    if (_caCert is null
+      && !TryCreateCertificate(Path.Combine(dockerCertPath, "ca.pem"), null, out _caCert))
+    {
+      if (_logger.IsEnabled(LogLevel.Error))
+      {
+        _logger.LogError("Failed to get CA");
+      }
+
+      return false;
+    }
+
+    if (_clientCert is null
+      && !TryCreateCertificate(Path.Combine(dockerCertPath, "cert.pem"), Path.Combine(dockerCertPath, "key.pem"), out _clientCert))
+    {
+      if (_logger.IsEnabled(LogLevel.Error))
+      {
+        _logger.LogError("Failed to get client certificate");
+      }
+
+      _caCert.Dispose();
+      _caCert = null;
+      return false;
+    }
+
+    caCert = Clone(_caCert);
+    clientCert = Clone(_clientCert);
+    return true;
+  }
+
+  public void Dispose()
+  {
+    Dispose(disposing: true);
+    GC.SuppressFinalize(this);
+  }
+
+  [SuppressMessage("Reliability", "CA2000:Dispose objects before losing scope", Justification = "Disposed by caller")]
+  private static bool TryCreateCertificate(string certPath, string? keyPath, [NotNullWhen(true)] out X509Certificate2? cert)
+  {
+    var certPem = File.Exists(certPath) ? File.ReadAllText(certPath) : null;
+    var keyPem = File.Exists(keyPath) ? File.ReadAllText(keyPath) : null;
+
+    if (keyPem is null)
+    {
+      cert = string.IsNullOrWhiteSpace(certPem) ? null : X509Certificate2.CreateFromPem(certPem);
+      return cert is not null;
+    }
+
+    cert = string.IsNullOrWhiteSpace(certPem) ? null : X509Certificate2.CreateFromPem(certPem, keyPem);
+    return cert is not null;
+  }
+
+  private static X509Certificate2 Clone(X509Certificate2 cert)
+  {
+    var keyStorageFlags = X509KeyStorageFlags.Exportable | X509KeyStorageFlags.PersistKeySet;
+    var pfxBytes = cert.Export(X509ContentType.Pkcs12, string.Empty);
+    return X509CertificateLoader.LoadPkcs12(pfxBytes, string.Empty, keyStorageFlags);
+  }
+
+  private void Dispose(bool disposing)
+  {
+    if (!_disposedValue)
+    {
+      if (disposing)
+      {
+        _caCert?.Dispose();
+        _clientCert?.Dispose();
+      }
+
+      _disposedValue = true;
+    }
+  }
+}
diff --git a/src/RemoteContainers.Aspire/Models/ContainerPorts.cs b/src/RemoteContainers.Aspire/Models/ContainerPorts.cs
index e7774e2..75f86e7 100644
--- a/src/RemoteContainers.Aspire/Models/ContainerPorts.cs
+++ b/src/RemoteContainers.Aspire/Models/ContainerPorts.cs
@@ -1,5 +1,5 @@
 // <copyright file="ContainerPorts.cs" company="Henrik Jensen">
-// Copyright 2025 Henrik Jensen
+// Copyright 2026 Henrik Jensen
 //
 // Licensed under the Apache License, Version 2.0 (the "License")
 // you may not use this file except in compliance with the License.
diff --git a/src/RemoteContainers.Aspire/SshTunnelClient.cs b/src/RemoteContainers.Aspire/SshTunnelClient.cs
index 8d04b21..5d5d21e 100644
--- a/src/RemoteContainers.Aspire/SshTunnelClient.cs
+++ b/src/RemoteContainers.Aspire/SshTunnelClient.cs
@@ -1,5 +1,5 @@
 // <copyright file="SshTunnelClient.cs" company="Henrik Jensen">
-// Copyright 2025 Henrik Jensen
+// Copyright 2026 Henrik Jensen
 //
 // Licensed under the Apache License, Version 2.0 (the "License")
 // you may not use this file except in compliance with the License.
@@ -14,80 +14,78 @@
 // limitations under the License.
 // </copyright>
 
+using System.Diagnostics.CodeAnalysis;
 using Renci.SshNet;
 
 namespace Hj.RemoteContainers.Aspire;
 
 internal sealed class SshTunnelClient : IDisposable
 {
-  private readonly List<PrivateKeyFile> _keyFiles;
+  private readonly AppConfiguration _appConfiguration;
 
-  private readonly SshClient _sshClient;
+  private List<PrivateKeyFile>? _keyFiles;
+  private SshClient? _sshClient;
 
   private bool _disposedValue;
 
-  private SshTunnelClient(List<PrivateKeyFile> keyFiles, SshClient sshClient)
-  {
-    _keyFiles = keyFiles;
-    _sshClient = sshClient;
-  }
+  public SshTunnelClient(AppConfiguration appConfiguration) => _appConfiguration = appConfiguration;
 
-  internal bool IsConnected => _sshClient.IsConnected;
+  [MemberNotNullWhen(true, nameof(_sshClient))]
+  public bool IsConnected => _sshClient?.IsConnected ?? false;
 
-  public void Dispose()
-  {
-    Dispose(disposing: true);
-    GC.SuppressFinalize(this);
-  }
-
-  internal static SshTunnelClient Connect(string keyDir, string sshHost, string sshUser)
+  public void Connect()
   {
+    var keyDir = _appConfiguration.SshKeyPath;
     if (!Directory.Exists(keyDir))
     {
       throw new InvalidOperationException($"SSH key path '{keyDir}' does not exist.");
     }
 
-    var keyFiles = LoadSshKeyFiles(keyDir);
-    if (keyFiles.Count == 0)
+    _keyFiles = LoadSshKeyFiles(keyDir);
+    if (_keyFiles.Count == 0)
     {
       throw new InvalidOperationException("No SSH private keys found.");
     }
 
-    var sshClient = ConnectSshClient(keyFiles, sshHost, sshUser);
-    return new(keyFiles, sshClient);
+    _sshClient = new SshClient(_appConfiguration.SshHost, _appConfiguration.SshUser, [.. _keyFiles]);
+    try
+    {
+      _sshClient.Connect();
+    }
+    catch
+    {
+      Dispose();
+      throw;
+    }
+  }
+
+  public void Dispose()
+  {
+    Dispose(disposing: true);
+    GC.SuppressFinalize(this);
   }
 
-  internal bool TryForwardPort(uint port, out ForwardedPortLocal? forwardedPort)
+  [SuppressMessage("Reliability", "CA2000:Dispose objects before losing scope", Justification = "See Dispose()")]
+  public bool TryForwardPort(uint port, out ForwardedPortLocal? forwardedPort)
   {
     forwardedPort = null;
+
+    if (!IsConnected)
+    {
+      return false;
+    }
+
     try
     {
-#pragma warning disable CA2000 // Dispose objects before losing scope
       forwardedPort = new ForwardedPortLocal("127.0.0.1", port, "127.0.0.1", port);
-#pragma warning restore CA2000 // Dispose objects before losing scope
       _sshClient.AddForwardedPort(forwardedPort);
       forwardedPort.Start();
       return true;
     }
-    catch (Exception)
+    catch
     {
       forwardedPort?.Dispose();
       forwardedPort = null;
-      return false;
-    }
-  }
-
-  private static SshClient ConnectSshClient(List<PrivateKeyFile> keyFiles, string sshHost, string sshUser)
-  {
-    var sshClient = new SshClient(sshHost, sshUser, [.. keyFiles]);
-    try
-    {
-      sshClient.Connect();
-      return sshClient;
-    }
-    catch (Exception)
-    {
-      sshClient.Dispose();
       throw;
     }
   }
@@ -126,12 +124,14 @@ private void Dispose(bool disposing)
     {
       if (disposing)
       {
-        _sshClient.Disconnect();
-        _sshClient.Dispose();
+        _sshClient?.Dispose();
 
-        foreach (var keyFile in _keyFiles)
+        if (_keyFiles is not null)
         {
-          keyFile.Dispose();
+          foreach (var keyFile in _keyFiles)
+          {
+            keyFile.Dispose();
+          }
         }
       }
 
diff --git a/src/RemoteContainers.Aspire/SshTunnelExtensions.cs b/src/RemoteContainers.Aspire/SshTunnelExtensions.cs
index 32dbc17..12f75b2 100644
--- a/src/RemoteContainers.Aspire/SshTunnelExtensions.cs
+++ b/src/RemoteContainers.Aspire/SshTunnelExtensions.cs
@@ -1,5 +1,5 @@
 // <copyright file="SshTunnelExtensions.cs" company="Henrik Jensen">
-// Copyright 2025 Henrik Jensen
+// Copyright 2026 Henrik Jensen
 //
 // Licensed under the Apache License, Version 2.0 (the "License")
 // you may not use this file except in compliance with the License.
@@ -32,50 +32,56 @@ public static class SshTunnelExtensions
   /// <returns>The application builder instance.</returns>
   public static IDistributedApplicationBuilder AddSshTunneling(this IDistributedApplicationBuilder builder)
   {
+    var services = builder.Services;
+
     var environmentUserName = Environment.UserName;
     var environmentUserProfilePath = Environment.GetFolderPath(Environment.SpecialFolder.UserProfile);
     var environmentVariables = Environment.GetEnvironmentVariables();
-
     AppConfiguration appConfiguration = new(builder.Configuration, environmentUserName, environmentUserProfilePath, environmentVariables);
+
     if (!appConfiguration.HasDockerHost)
     {
       // Skip setting up SSH tunnels.
       return builder;
     }
 
-    var services = builder.Services;
-    services.AddSingleton(appConfiguration);
-
-    builder.Services.AddHttpClient<DockerApiClient>(httpClient =>
+    services.AddHttpClient<DockerApiClient>(httpClient =>
       {
         httpClient.BaseAddress = appConfiguration.DockerHost.Uri;
       })
-      .ConfigurePrimaryHttpMessageHandler(() =>
+      .ConfigurePrimaryHttpMessageHandler(CreateHttpMessageHandler)
+      .AddStandardResilienceHandler();
+
+    services
+      .AddSingleton(appConfiguration)
+      .AddSingleton<DockerCertificate>()
+      .AddSingleton<SshTunnelClient>()
+      .AddSingleton<SshTunnelManager>()
+      .AddEventingSubscriber<SshTunnelLifecycleHook>();
+
+    return builder;
+  }
+
+  private static HttpMessageHandler CreateHttpMessageHandler(IServiceProvider sp)
+  {
+    var handler = new HttpClientHandler();
+    var dockerCert = sp.GetRequiredService<DockerCertificate>();
+    if (dockerCert.TryGetCertificate(out var caCert, out var clientCert))
+    {
+      handler.ClientCertificates.Add(clientCert);
+      handler.ServerCertificateCustomValidationCallback = (_, serverCert, chain, _) =>
       {
-        var handler = new HttpClientHandler();
-        if (appConfiguration.TryGetDockerCertificate(out var caCert, out var clientCert))
+        if (serverCert is null || chain is null)
         {
-          handler.ClientCertificates.Add(clientCert);
-          handler.ServerCertificateCustomValidationCallback = (_, serverCert, chain, _) =>
-          {
-            if (serverCert is null || chain is null)
-            {
-              return false;
-            }
-
-            chain.ChainPolicy.CustomTrustStore.Add(caCert);
-            chain.ChainPolicy.TrustMode = X509ChainTrustMode.CustomRootTrust;
-            return chain.Build(serverCert);
-          };
+          return false;
         }
 
-        return handler;
-      })
-      .AddStandardResilienceHandler();
-
-    builder.Services.AddSingleton<SshTunnelManager>();
-    builder.Services.AddEventingSubscriber<SshTunnelLifecycleHook>();
+        chain.ChainPolicy.CustomTrustStore.Add(caCert);
+        chain.ChainPolicy.TrustMode = X509ChainTrustMode.CustomRootTrust;
+        return chain.Build(serverCert);
+      };
+    }
 
-    return builder;
+    return handler;
   }
 }
diff --git a/src/RemoteContainers.Aspire/SshTunnelLifecycleHook.cs b/src/RemoteContainers.Aspire/SshTunnelLifecycleHook.cs
index 89ff27b..09475af 100644
--- a/src/RemoteContainers.Aspire/SshTunnelLifecycleHook.cs
+++ b/src/RemoteContainers.Aspire/SshTunnelLifecycleHook.cs
@@ -1,5 +1,5 @@
 // <copyright file="SshTunnelLifecycleHook.cs" company="Henrik Jensen">
-// Copyright 2025 Henrik Jensen
+// Copyright 2026 Henrik Jensen
 //
 // Licensed under the Apache License, Version 2.0 (the "License")
 // you may not use this file except in compliance with the License.
@@ -36,27 +36,76 @@ public SshTunnelLifecycleHook(ILogger<SshTunnelLifecycleHook> logger, SshTunnelM
   public Task SubscribeAsync(IDistributedApplicationEventing eventing, DistributedApplicationExecutionContext executionContext, CancellationToken cancellationToken)
   {
     eventing.Subscribe<ResourceEndpointsAllocatedEvent>(SetUpTunnelAsync);
+    eventing.Subscribe<ResourceReadyEvent>(SetUpTunnelOnReadyAsync);
+    eventing.Subscribe<ResourceStoppedEvent>(TearDownTunnel);
+
     return Task.CompletedTask;
   }
 
+  private static bool IsContainerResource(IResource resource) =>
+    resource.Annotations.OfType<ContainerImageAnnotation>().Any();
+
   private async Task SetUpTunnelAsync(ResourceEndpointsAllocatedEvent evt, CancellationToken cancellationToken)
   {
-    // Only tunnel container resources.
-    if (!evt.Resource.Annotations.OfType<ContainerImageAnnotation>().Any())
+    if (!IsContainerResource(evt.Resource))
+    {
+      return;
+    }
+
+    try
+    {
+      await _tunnelManager.AddAllContainerPortForwardsAsync(evt.Resource.Name, cancellationToken);
+    }
+    catch (Exception ex)
+    {
+      if (_logger.IsEnabled(LogLevel.Error))
+      {
+        _logger.LogError(ex, "Failed to set up SSH tunnel for resource {ResourceName}", evt.Resource.Name);
+      }
+    }
+  }
+
+  private async Task SetUpTunnelOnReadyAsync(ResourceReadyEvent evt, CancellationToken cancellationToken)
+  {
+    if (!IsContainerResource(evt.Resource))
     {
       return;
     }
 
     try
     {
+      // Remove stale tunnels from the previous run of this resource before creating new ones.
+      _tunnelManager.RemoveAllContainerPortForwards(evt.Resource.Name);
       await _tunnelManager.AddAllContainerPortForwardsAsync(evt.Resource.Name, cancellationToken);
     }
     catch (Exception ex)
     {
       if (_logger.IsEnabled(LogLevel.Error))
       {
-        _logger.LogError(ex, "Failed to set up SSH tunnel");
+        _logger.LogError(ex, "Failed to re-establish SSH tunnel for resource {ResourceName}", evt.Resource.Name);
+      }
+    }
+  }
+
+  private Task TearDownTunnel(ResourceStoppedEvent evt, CancellationToken cancellationToken)
+  {
+    if (!IsContainerResource(evt.Resource))
+    {
+      return Task.CompletedTask;
+    }
+
+    try
+    {
+      _tunnelManager.RemoveAllContainerPortForwards(evt.Resource.Name);
+    }
+    catch (Exception ex)
+    {
+      if (_logger.IsEnabled(LogLevel.Error))
+      {
+        _logger.LogError(ex, "Failed to tear down SSH tunnel for resource {ResourceName}", evt.Resource.Name);
       }
     }
+
+    return Task.CompletedTask;
   }
 }
diff --git a/src/RemoteContainers.Aspire/SshTunnelManager.cs b/src/RemoteContainers.Aspire/SshTunnelManager.cs
index 62784b6..83aaf22 100644
--- a/src/RemoteContainers.Aspire/SshTunnelManager.cs
+++ b/src/RemoteContainers.Aspire/SshTunnelManager.cs
@@ -1,5 +1,5 @@
 // <copyright file="SshTunnelManager.cs" company="Henrik Jensen">
-// Copyright 2025 Henrik Jensen
+// Copyright 2026 Henrik Jensen
 //
 // Licensed under the Apache License, Version 2.0 (the "License")
 // you may not use this file except in compliance with the License.
@@ -15,6 +15,7 @@
 // </copyright>
 
 using System.Collections.Concurrent;
+using System.Diagnostics.CodeAnalysis;
 using Microsoft.Extensions.Logging;
 using Renci.SshNet;
 
@@ -26,19 +27,24 @@ namespace Hj.RemoteContainers.Aspire;
 internal sealed class SshTunnelManager : IDisposable
 {
   private readonly ILogger<SshTunnelManager> _logger;
-  private readonly AppConfiguration _appConfiguration;
   private readonly DockerApiClient _dockerApiClient;
   private readonly Lazy<SshTunnelClient> _sshTunnelClient;
 
-  private readonly ConcurrentBag<ForwardedPortLocal> _forwardedPorts = [];
+  private readonly ConcurrentDictionary<string, ConcurrentBag<ForwardedPortLocal>> _forwardedPortsByResource = new();
   private bool _disposedValue;
 
-  public SshTunnelManager(ILogger<SshTunnelManager> logger, AppConfiguration appConfiguration, DockerApiClient dockerApiClient)
+  public SshTunnelManager(
+    ILogger<SshTunnelManager> logger,
+    SshTunnelClient sshTunnelClient,
+    DockerApiClient dockerApiClient)
   {
     _logger = logger;
-    _appConfiguration = appConfiguration;
     _dockerApiClient = dockerApiClient;
-    _sshTunnelClient = new Lazy<SshTunnelClient>(ConnectSshTunnelClient);
+    _sshTunnelClient = new Lazy<SshTunnelClient>(() =>
+    {
+      sshTunnelClient.Connect();
+      return sshTunnelClient;
+    });
   }
 
   /// <summary>
@@ -47,6 +53,7 @@ public SshTunnelManager(ILogger<SshTunnelManager> logger, AppConfiguration appCo
   /// <param name="resourceName">A resource name for which remote container ports will be retrieved.</param>
   /// <param name="cancellationToken">A cancellation token.</param>
   /// <returns>A task.</returns>
+  [SuppressMessage("Reliability", "CA2000:Dispose objects before losing scope", Justification = "See Dispose()")]
   public async Task AddAllContainerPortForwardsAsync(string resourceName, CancellationToken cancellationToken)
   {
     if (!_sshTunnelClient.Value.IsConnected)
@@ -60,32 +67,59 @@ public async Task AddAllContainerPortForwardsAsync(string resourceName, Cancella
       return;
     }
 
+    var resourcePorts = _forwardedPortsByResource.GetOrAdd(resourceName, _ => []);
+
     foreach (var port in portMappings)
     {
-#pragma warning disable CA2000 // Dispose objects before losing scope
       var isPortForwarded = _sshTunnelClient.Value.TryForwardPort(port, out var forwardedPort);
-#pragma warning restore CA2000 // Dispose objects before losing scope
       if (forwardedPort is not null)
       {
-        _forwardedPorts.Add(forwardedPort);
+        resourcePorts.Add(forwardedPort);
       }
 
       if (isPortForwarded)
       {
         if (_logger.IsEnabled(LogLevel.Information))
         {
-          _logger.LogInformation(
-            "Port forwarded: localhost:{Port} → remote:{Port}",
-            port,
-            port);
+          _logger.LogInformation("SSH tunnel created for {ResourceName} port {Port}", resourceName, port);
         }
       }
       else if (_logger.IsEnabled(LogLevel.Warning))
       {
-        _logger.LogWarning(
-            "Failed to forward port: localhost:{Port} → remote:{Port}",
-            port,
-            port);
+        _logger.LogWarning("Failed to forward port {Port} for {ResourceName}", port, resourceName);
+      }
+    }
+  }
+
+  /// <summary>
+  /// Stops and disposes all SSH tunnels associated with the specified resource.
+  /// </summary>
+  /// <param name="resourceName">The resource name whose tunnels should be removed.</param>
+  public void RemoveAllContainerPortForwards(string resourceName)
+  {
+    if (!_forwardedPortsByResource.TryRemove(resourceName, out var ports))
+    {
+      return;
+    }
+
+    while (ports.TryTake(out var forwardedPort))
+    {
+      try
+      {
+        forwardedPort.Stop();
+        forwardedPort.Dispose();
+
+        if (_logger.IsEnabled(LogLevel.Information))
+        {
+          _logger.LogInformation("SSH tunnel removed for {ResourceName} port {Port}", resourceName, forwardedPort.BoundPort);
+        }
+      }
+      catch (Exception ex)
+      {
+        if (_logger.IsEnabled(LogLevel.Warning))
+        {
+          _logger.LogWarning(ex, "Failed to clean up SSH tunnel for {ResourceName} port {Port}", resourceName, forwardedPort.BoundPort);
+        }
       }
     }
   }
@@ -102,17 +136,9 @@ private void Dispose(bool disposing)
     {
       if (disposing)
       {
-        while (_forwardedPorts.TryTake(out var forwardedPort))
+        foreach (var resourceName in _forwardedPortsByResource.Keys)
         {
-          try
-          {
-            forwardedPort.Stop();
-            forwardedPort.Dispose();
-          }
-          catch
-          {
-            // Best effort cleanup
-          }
+          RemoveAllContainerPortForwards(resourceName);
         }
 
         if (_sshTunnelClient.IsValueCreated)
@@ -124,7 +150,4 @@ private void Dispose(bool disposing)
       _disposedValue = true;
     }
   }
-
-  private SshTunnelClient ConnectSshTunnelClient()
-    => SshTunnelClient.Connect(_appConfiguration.SshKeyPath, _appConfiguration.SshHost, _appConfiguration.SshUser);
 }

From 9c2426ef9fa4c29c0e15a1236c17840aa1601fd0 Mon Sep 17 00:00:00 2001
From: Henrik Jensen <1175002+henrikhimself@users.noreply.github.com>
Date: Wed, 11 Mar 2026 06:55:12 +0100
Subject: [PATCH 12/25] Address code review comments

---
 src/RemoteContainers.Aspire/DockerApiClient.cs |  2 +-
 src/RemoteContainers.Aspire/SshTunnelClient.cs | 11 +++++------
 .../SshTunnelManager.cs                        | 18 ++++--------------
 3 files changed, 10 insertions(+), 21 deletions(-)

diff --git a/src/RemoteContainers.Aspire/DockerApiClient.cs b/src/RemoteContainers.Aspire/DockerApiClient.cs
index 1589852..c0ccadf 100644
--- a/src/RemoteContainers.Aspire/DockerApiClient.cs
+++ b/src/RemoteContainers.Aspire/DockerApiClient.cs
@@ -189,7 +189,7 @@ public DockerApiClient(ILogger<DockerApiClient> logger, HttpClient httpClient)
         return new ContainerPorts()
         {
           Id = containerId,
-          Ports = portMappings,
+          Ports = [.. portMappings.Distinct()],
         };
       }
     }
diff --git a/src/RemoteContainers.Aspire/SshTunnelClient.cs b/src/RemoteContainers.Aspire/SshTunnelClient.cs
index 5d5d21e..c86e3d3 100644
--- a/src/RemoteContainers.Aspire/SshTunnelClient.cs
+++ b/src/RemoteContainers.Aspire/SshTunnelClient.cs
@@ -66,28 +66,27 @@ public void Dispose()
   }
 
   [SuppressMessage("Reliability", "CA2000:Dispose objects before losing scope", Justification = "See Dispose()")]
-  public bool TryForwardPort(uint port, out ForwardedPortLocal? forwardedPort)
+  public ForwardedPortLocal ForwardPort(uint port)
   {
-    forwardedPort = null;
-
     if (!IsConnected)
     {
-      return false;
+      throw new InvalidOperationException("SSH client is not connected");
     }
 
+    ForwardedPortLocal? forwardedPort = null;
     try
     {
       forwardedPort = new ForwardedPortLocal("127.0.0.1", port, "127.0.0.1", port);
       _sshClient.AddForwardedPort(forwardedPort);
       forwardedPort.Start();
-      return true;
     }
     catch
     {
       forwardedPort?.Dispose();
-      forwardedPort = null;
       throw;
     }
+
+    return forwardedPort;
   }
 
   private static List<PrivateKeyFile> LoadSshKeyFiles(string keyDir)
diff --git a/src/RemoteContainers.Aspire/SshTunnelManager.cs b/src/RemoteContainers.Aspire/SshTunnelManager.cs
index 83aaf22..f02fa5c 100644
--- a/src/RemoteContainers.Aspire/SshTunnelManager.cs
+++ b/src/RemoteContainers.Aspire/SshTunnelManager.cs
@@ -71,22 +71,12 @@ public async Task AddAllContainerPortForwardsAsync(string resourceName, Cancella
 
     foreach (var port in portMappings)
     {
-      var isPortForwarded = _sshTunnelClient.Value.TryForwardPort(port, out var forwardedPort);
-      if (forwardedPort is not null)
-      {
-        resourcePorts.Add(forwardedPort);
-      }
+      var forwardedPort = _sshTunnelClient.Value.ForwardPort(port);
+      resourcePorts.Add(forwardedPort);
 
-      if (isPortForwarded)
-      {
-        if (_logger.IsEnabled(LogLevel.Information))
-        {
-          _logger.LogInformation("SSH tunnel created for {ResourceName} port {Port}", resourceName, port);
-        }
-      }
-      else if (_logger.IsEnabled(LogLevel.Warning))
+      if (_logger.IsEnabled(LogLevel.Information))
       {
-        _logger.LogWarning("Failed to forward port {Port} for {ResourceName}", port, resourceName);
+        _logger.LogInformation("SSH tunnel created for {ResourceName} port {Port}", resourceName, forwardedPort.Port);
       }
     }
   }

From dbfc913457d6c3d1f9faa34c5270b56ef847e8c8 Mon Sep 17 00:00:00 2001
From: Henrik Jensen <1175002+henrikhimself@users.noreply.github.com>
Date: Wed, 11 Mar 2026 08:33:06 +0100
Subject: [PATCH 13/25] Add abstraction points and empty unit test project

---
 Directory.Packages.props                      |  6 ++++
 README.md                                     |  6 ++--
 RemoteContainers.slnx                         |  1 +
 examples/Aspire.AppHost/appsettings.json      |  8 +++--
 .../Abstractions/FileSystem.cs                | 24 +++++++++++++
 .../Abstractions/IFileSystem.cs               | 24 +++++++++++++
 .../Abstractions/ISshForwardedPort.cs         | 26 ++++++++++++++
 .../Abstractions/SshForwardedPort.cs          | 34 +++++++++++++++++++
 .../AppConfiguration.cs                       | 10 ++++--
 .../{Models => Docker}/ContainerPorts.cs      |  2 +-
 .../{ => Docker}/DockerApiClient.cs           | 24 ++++++-------
 .../{ => Docker}/DockerCertificate.cs         | 26 +++++++-------
 .../Docker/IDockerApiClient.cs                | 22 ++++++++++++
 .../RemoteContainers.Aspire.csproj            | 10 ++++++
 .../Ssh/ISshConnection.cs                     | 26 ++++++++++++++
 .../Ssh/ISshTunnelManager.cs                  | 24 +++++++++++++
 .../SshConnection.cs}                         | 12 +++----
 .../{ => Ssh}/SshTunnelManager.cs             | 29 ++++++++--------
 .../SshTunnelExtensions.cs                    |  7 ++--
 .../SshTunnelLifecycleHook.cs                 |  4 +--
 .../RemoteContainers.Aspire.UnitTest.csproj   | 32 +++++++++++++++++
 .../UnitTest1.cs                              | 10 ++++++
 22 files changed, 310 insertions(+), 57 deletions(-)
 create mode 100644 src/RemoteContainers.Aspire/Abstractions/FileSystem.cs
 create mode 100644 src/RemoteContainers.Aspire/Abstractions/IFileSystem.cs
 create mode 100644 src/RemoteContainers.Aspire/Abstractions/ISshForwardedPort.cs
 create mode 100644 src/RemoteContainers.Aspire/Abstractions/SshForwardedPort.cs
 rename src/RemoteContainers.Aspire/{Models => Docker}/ContainerPorts.cs (94%)
 rename src/RemoteContainers.Aspire/{ => Docker}/DockerApiClient.cs (90%)
 rename src/RemoteContainers.Aspire/{ => Docker}/DockerCertificate.cs (87%)
 create mode 100644 src/RemoteContainers.Aspire/Docker/IDockerApiClient.cs
 create mode 100644 src/RemoteContainers.Aspire/Ssh/ISshConnection.cs
 create mode 100644 src/RemoteContainers.Aspire/Ssh/ISshTunnelManager.cs
 rename src/RemoteContainers.Aspire/{SshTunnelClient.cs => Ssh/SshConnection.cs} (89%)
 rename src/RemoteContainers.Aspire/{ => Ssh}/SshTunnelManager.cs (83%)
 create mode 100644 test/RemoteContainers.Aspire.UnitTest/RemoteContainers.Aspire.UnitTest.csproj
 create mode 100644 test/RemoteContainers.Aspire.UnitTest/UnitTest1.cs

diff --git a/Directory.Packages.props b/Directory.Packages.props
index 0462473..490061e 100644
--- a/Directory.Packages.props
+++ b/Directory.Packages.props
@@ -11,6 +11,12 @@
     <PackageVersion Include="Microsoft.Extensions.Http.Resilience" Version="10.3.0" />
     <PackageVersion Include="SSH.NET" Version="2025.1.0" />
     <PackageVersion Include="StyleCop.Analyzers" Version="1.2.0-beta.556" />
+    <PackageVersion Include="coverlet.collector" Version="6.0.4" />
+    <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />
+    <PackageVersion Include="xunit" Version="2.9.3" />
+    <PackageVersion Include="xunit.analyzers" Version="1.25.0" />
+    <PackageVersion Include="xunit.runner.visualstudio" Version="3.1.4" />
+    <PackageVersion Include="NSubstitute" Version="5.3.0" />
   </ItemGroup>
 
 </Project>
diff --git a/README.md b/README.md
index 05cbda3..b138df0 100644
--- a/README.md
+++ b/README.md
@@ -84,8 +84,10 @@ These can be set via any .NET configuration source (environment variables, `apps
 
 | Key | Default | Description |
 |---|---|---|
-| `SSH_HOST` | Hostname from `DOCKER_HOST` | Override the SSH connection target if it differs from the Docker API host. |
-| `SSH_USER` | Current OS username | Override the SSH username. |
+| `RemoteContainers:SshHost` | Hostname from `DOCKER_HOST` | Override the SSH connection target if it differs from the Docker API host. |
+| `RemoteContainers:SshUser` | Current OS username | Override the SSH username. |
+| `RemoteContainers:ContainerStartTimeout` | `00:05:00` | How long to wait for a container's ports to become available before giving up. Expressed as a `TimeSpan` string (e.g. `00:05:00`). |
+| `RemoteContainers:ContainerPollInterval` | `00:00:05` | How often to poll the Docker API while waiting for a container's ports. Expressed as a `TimeSpan` string (e.g. `00:00:05`). |
 
 ### SSH Key Authentication
 
diff --git a/RemoteContainers.slnx b/RemoteContainers.slnx
index 0f6318f..9b7d007 100644
--- a/RemoteContainers.slnx
+++ b/RemoteContainers.slnx
@@ -3,4 +3,5 @@
     <Project Path="examples/Aspire.AppHost/Aspire.AppHost.csproj" />
   </Folder>
   <Project Path="src/RemoteContainers.Aspire/RemoteContainers.Aspire.csproj" />
+  <Project Path="test/RemoteContainers.Aspire.UnitTest/RemoteContainers.Aspire.UnitTest.csproj" />
 </Solution>
diff --git a/examples/Aspire.AppHost/appsettings.json b/examples/Aspire.AppHost/appsettings.json
index 5d4dcfe..6376795 100644
--- a/examples/Aspire.AppHost/appsettings.json
+++ b/examples/Aspire.AppHost/appsettings.json
@@ -6,6 +6,10 @@
       "Aspire.Hosting.Dcp": "Warning"
     }
   },
-  "SSH_HOST": "",
-  "SSH_USER": ""
+  "RemoteContainers": {
+    "SshHost": "",
+    "SshUser": "",
+    "ContainerStartTimeout": "00:05:00",
+    "ContainerPollInterval": "00:00:05"
+  }
 }
diff --git a/src/RemoteContainers.Aspire/Abstractions/FileSystem.cs b/src/RemoteContainers.Aspire/Abstractions/FileSystem.cs
new file mode 100644
index 0000000..4691372
--- /dev/null
+++ b/src/RemoteContainers.Aspire/Abstractions/FileSystem.cs
@@ -0,0 +1,24 @@
+// <copyright file="FileSystem.cs" company="Henrik Jensen">
+// Copyright 2026 Henrik Jensen
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+namespace Hj.RemoteContainers.Aspire.Abstractions;
+
+internal sealed class FileSystem : IFileSystem
+{
+  public bool FileExists(string path) => File.Exists(path);
+
+  public string ReadAllText(string path) => File.ReadAllText(path);
+}
diff --git a/src/RemoteContainers.Aspire/Abstractions/IFileSystem.cs b/src/RemoteContainers.Aspire/Abstractions/IFileSystem.cs
new file mode 100644
index 0000000..4f1f21c
--- /dev/null
+++ b/src/RemoteContainers.Aspire/Abstractions/IFileSystem.cs
@@ -0,0 +1,24 @@
+// <copyright file="IFileSystem.cs" company="Henrik Jensen">
+// Copyright 2026 Henrik Jensen
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+namespace Hj.RemoteContainers.Aspire.Abstractions;
+
+internal interface IFileSystem
+{
+  bool FileExists(string path);
+
+  string ReadAllText(string path);
+}
diff --git a/src/RemoteContainers.Aspire/Abstractions/ISshForwardedPort.cs b/src/RemoteContainers.Aspire/Abstractions/ISshForwardedPort.cs
new file mode 100644
index 0000000..8d3e4e7
--- /dev/null
+++ b/src/RemoteContainers.Aspire/Abstractions/ISshForwardedPort.cs
@@ -0,0 +1,26 @@
+// <copyright file="ISshForwardedPort.cs" company="Henrik Jensen">
+// Copyright 2026 Henrik Jensen
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+namespace Hj.RemoteContainers.Aspire.Abstractions;
+
+internal interface ISshForwardedPort : IDisposable
+{
+  uint Port { get; }
+
+  uint? BoundPort { get; }
+
+  void Stop();
+}
diff --git a/src/RemoteContainers.Aspire/Abstractions/SshForwardedPort.cs b/src/RemoteContainers.Aspire/Abstractions/SshForwardedPort.cs
new file mode 100644
index 0000000..a3e3f33
--- /dev/null
+++ b/src/RemoteContainers.Aspire/Abstractions/SshForwardedPort.cs
@@ -0,0 +1,34 @@
+// <copyright file="SshForwardedPort.cs" company="Henrik Jensen">
+// Copyright 2026 Henrik Jensen
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+using Renci.SshNet;
+
+namespace Hj.RemoteContainers.Aspire.Abstractions;
+
+internal sealed class SshForwardedPort : ISshForwardedPort
+{
+  private readonly ForwardedPortLocal _forwardedPort;
+
+  internal SshForwardedPort(ForwardedPortLocal forwardedPort) => _forwardedPort = forwardedPort;
+
+  public uint Port => _forwardedPort.Port;
+
+  public uint? BoundPort => _forwardedPort.BoundPort;
+
+  public void Stop() => _forwardedPort.Stop();
+
+  public void Dispose() => _forwardedPort.Dispose();
+}
diff --git a/src/RemoteContainers.Aspire/AppConfiguration.cs b/src/RemoteContainers.Aspire/AppConfiguration.cs
index 25f5aa5..2f8c3d8 100644
--- a/src/RemoteContainers.Aspire/AppConfiguration.cs
+++ b/src/RemoteContainers.Aspire/AppConfiguration.cs
@@ -35,13 +35,19 @@ public AppConfiguration(IConfiguration configuration, string environmentUserName
     _environmentVariables = environmentVariables;
   }
 
+  public TimeSpan ContainerStartTimeout =>
+    _configuration.GetValue<TimeSpan?>("RemoteContainers:ContainerStartTimeout") ?? TimeSpan.FromMinutes(5);
+
+  public TimeSpan ContainerPollInterval =>
+    _configuration.GetValue<TimeSpan?>("RemoteContainers:ContainerPollInterval") ?? TimeSpan.FromSeconds(5);
+
   public string SshKeyPath => Path.Combine(_environmentUserProfilePath, ".ssh");
 
   public string SshHost
   {
     get
     {
-      var sshHost = _configuration["SSH_HOST"];
+      var sshHost = _configuration["RemoteContainers:SshHost"];
       return string.IsNullOrWhiteSpace(sshHost)
         ? (DockerHost?.Host ?? throw new InvalidOperationException("No SSH host found."))
         : sshHost;
@@ -52,7 +58,7 @@ public string SshUser
   {
     get
     {
-      var sshUser = _configuration["SSH_USER"];
+      var sshUser = _configuration["RemoteContainers:SshUser"];
       return string.IsNullOrWhiteSpace(sshUser)
         ? _environmentUserName
         : sshUser;
diff --git a/src/RemoteContainers.Aspire/Models/ContainerPorts.cs b/src/RemoteContainers.Aspire/Docker/ContainerPorts.cs
similarity index 94%
rename from src/RemoteContainers.Aspire/Models/ContainerPorts.cs
rename to src/RemoteContainers.Aspire/Docker/ContainerPorts.cs
index 75f86e7..2c9eadc 100644
--- a/src/RemoteContainers.Aspire/Models/ContainerPorts.cs
+++ b/src/RemoteContainers.Aspire/Docker/ContainerPorts.cs
@@ -14,7 +14,7 @@
 // limitations under the License.
 // </copyright>
 
-namespace Hj.RemoteContainers.Aspire.Models;
+namespace Hj.RemoteContainers.Aspire.Docker;
 
 internal sealed record ContainerPorts
 {
diff --git a/src/RemoteContainers.Aspire/DockerApiClient.cs b/src/RemoteContainers.Aspire/Docker/DockerApiClient.cs
similarity index 90%
rename from src/RemoteContainers.Aspire/DockerApiClient.cs
rename to src/RemoteContainers.Aspire/Docker/DockerApiClient.cs
index c0ccadf..7852ab5 100644
--- a/src/RemoteContainers.Aspire/DockerApiClient.cs
+++ b/src/RemoteContainers.Aspire/Docker/DockerApiClient.cs
@@ -15,26 +15,24 @@
 // </copyright>
 
 using System.Text.Json;
-using Hj.RemoteContainers.Aspire.Models;
 using Microsoft.Extensions.Logging;
 
-namespace Hj.RemoteContainers.Aspire;
+namespace Hj.RemoteContainers.Aspire.Docker;
 
 /// <summary>
 /// Queries the Docker REST API to resolve container port bindings.
 /// </summary>
-internal sealed class DockerApiClient
+internal sealed class DockerApiClient : IDockerApiClient
 {
-  private static readonly TimeSpan _containerStartTimeout = TimeSpan.FromMinutes(5);
-  private static readonly TimeSpan _containerPollInterval = TimeSpan.FromSeconds(5);
-
   private readonly ILogger<DockerApiClient> _logger;
   private readonly HttpClient _httpClient;
+  private readonly AppConfiguration _appConfiguration;
 
-  public DockerApiClient(ILogger<DockerApiClient> logger, HttpClient httpClient)
+  public DockerApiClient(ILogger<DockerApiClient> logger, HttpClient httpClient, AppConfiguration appConfiguration)
   {
     _logger = logger;
     _httpClient = httpClient;
+    _appConfiguration = appConfiguration;
   }
 
   /// <summary>
@@ -59,7 +57,9 @@ public DockerApiClient(ILogger<DockerApiClient> logger, HttpClient httpClient)
   /// </returns>
   public async Task<List<uint>?> GetAllContainerHostPortsAsync(string resourceName, CancellationToken cancellationToken)
   {
-    var deadline = DateTime.UtcNow + _containerStartTimeout;
+    var startTimeout = _appConfiguration.ContainerStartTimeout;
+    var pollInterval = _appConfiguration.ContainerPollInterval;
+    var deadline = DateTime.UtcNow + startTimeout;
     string? lastSeenId = null;
     var isFirstPoll = true;
 
@@ -75,7 +75,7 @@ public DockerApiClient(ILogger<DockerApiClient> logger, HttpClient httpClient)
             // Found on the very first attempt — might be a stale container from a previous Aspire run. Record the ID and re-poll to confirm.
             lastSeenId = result.Id;
             isFirstPoll = false;
-            await Task.Delay(_containerPollInterval, cancellationToken);
+            await Task.Delay(pollInterval, cancellationToken);
             continue;
           }
 
@@ -92,7 +92,7 @@ public DockerApiClient(ILogger<DockerApiClient> logger, HttpClient httpClient)
 
           // Container ID changed between polls — track the new one and re-confirm.
           lastSeenId = result.Id;
-          await Task.Delay(_containerPollInterval, cancellationToken);
+          await Task.Delay(pollInterval, cancellationToken);
           continue;
         }
 
@@ -111,7 +111,7 @@ public DockerApiClient(ILogger<DockerApiClient> logger, HttpClient httpClient)
         isFirstPoll = false;
       }
 
-      await Task.Delay(_containerPollInterval, cancellationToken);
+      await Task.Delay(pollInterval, cancellationToken);
     }
 
     if (_logger.IsEnabled(LogLevel.Warning))
@@ -119,7 +119,7 @@ public DockerApiClient(ILogger<DockerApiClient> logger, HttpClient httpClient)
       _logger.LogWarning(
         "Container {ResourceName} not found in Docker after {Timeout}s — no SSH tunnels created",
         resourceName,
-        _containerStartTimeout.TotalSeconds);
+        startTimeout.TotalSeconds);
     }
 
     return null;
diff --git a/src/RemoteContainers.Aspire/DockerCertificate.cs b/src/RemoteContainers.Aspire/Docker/DockerCertificate.cs
similarity index 87%
rename from src/RemoteContainers.Aspire/DockerCertificate.cs
rename to src/RemoteContainers.Aspire/Docker/DockerCertificate.cs
index 9b7aff4..ace123f 100644
--- a/src/RemoteContainers.Aspire/DockerCertificate.cs
+++ b/src/RemoteContainers.Aspire/Docker/DockerCertificate.cs
@@ -18,21 +18,23 @@
 using System.Security.Cryptography.X509Certificates;
 using Microsoft.Extensions.Logging;
 
-namespace Hj.RemoteContainers.Aspire;
+namespace Hj.RemoteContainers.Aspire.Docker;
 
 internal sealed class DockerCertificate : IDisposable
 {
   private readonly ILogger<DockerCertificate> _logger;
   private readonly AppConfiguration _appConfiguration;
+  private readonly IFileSystem _fileSystem;
 
   private X509Certificate2? _caCert;
   private X509Certificate2? _clientCert;
   private bool _disposedValue;
 
-  public DockerCertificate(ILogger<DockerCertificate> logger, AppConfiguration appConfiguration)
+  public DockerCertificate(ILogger<DockerCertificate> logger, AppConfiguration appConfiguration, IFileSystem fileSystem)
   {
     _logger = logger;
     _appConfiguration = appConfiguration;
+    _fileSystem = fileSystem;
   }
 
   [SuppressMessage("Reliability", "CA2000:Dispose objects before losing scope", Justification = "Disposed by caller")]
@@ -83,11 +85,18 @@ public void Dispose()
     GC.SuppressFinalize(this);
   }
 
+  private static X509Certificate2 Clone(X509Certificate2 cert)
+  {
+    var keyStorageFlags = X509KeyStorageFlags.Exportable | X509KeyStorageFlags.PersistKeySet;
+    var pfxBytes = cert.Export(X509ContentType.Pkcs12, string.Empty);
+    return X509CertificateLoader.LoadPkcs12(pfxBytes, string.Empty, keyStorageFlags);
+  }
+
   [SuppressMessage("Reliability", "CA2000:Dispose objects before losing scope", Justification = "Disposed by caller")]
-  private static bool TryCreateCertificate(string certPath, string? keyPath, [NotNullWhen(true)] out X509Certificate2? cert)
+  private bool TryCreateCertificate(string certPath, string? keyPath, [NotNullWhen(true)] out X509Certificate2? cert)
   {
-    var certPem = File.Exists(certPath) ? File.ReadAllText(certPath) : null;
-    var keyPem = File.Exists(keyPath) ? File.ReadAllText(keyPath) : null;
+    var certPem = _fileSystem.FileExists(certPath) ? _fileSystem.ReadAllText(certPath) : null;
+    var keyPem = keyPath is not null && _fileSystem.FileExists(keyPath) ? _fileSystem.ReadAllText(keyPath) : null;
 
     if (keyPem is null)
     {
@@ -99,13 +108,6 @@ private static bool TryCreateCertificate(string certPath, string? keyPath, [NotN
     return cert is not null;
   }
 
-  private static X509Certificate2 Clone(X509Certificate2 cert)
-  {
-    var keyStorageFlags = X509KeyStorageFlags.Exportable | X509KeyStorageFlags.PersistKeySet;
-    var pfxBytes = cert.Export(X509ContentType.Pkcs12, string.Empty);
-    return X509CertificateLoader.LoadPkcs12(pfxBytes, string.Empty, keyStorageFlags);
-  }
-
   private void Dispose(bool disposing)
   {
     if (!_disposedValue)
diff --git a/src/RemoteContainers.Aspire/Docker/IDockerApiClient.cs b/src/RemoteContainers.Aspire/Docker/IDockerApiClient.cs
new file mode 100644
index 0000000..dd0884e
--- /dev/null
+++ b/src/RemoteContainers.Aspire/Docker/IDockerApiClient.cs
@@ -0,0 +1,22 @@
+// <copyright file="IDockerApiClient.cs" company="Henrik Jensen">
+// Copyright 2026 Henrik Jensen
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+namespace Hj.RemoteContainers.Aspire.Docker;
+
+internal interface IDockerApiClient
+{
+  Task<List<uint>?> GetAllContainerHostPortsAsync(string resourceName, CancellationToken cancellationToken);
+}
diff --git a/src/RemoteContainers.Aspire/RemoteContainers.Aspire.csproj b/src/RemoteContainers.Aspire/RemoteContainers.Aspire.csproj
index 5eb7ab9..e5867fc 100644
--- a/src/RemoteContainers.Aspire/RemoteContainers.Aspire.csproj
+++ b/src/RemoteContainers.Aspire/RemoteContainers.Aspire.csproj
@@ -21,6 +21,12 @@
     <None Include="..\..\LICENSE" Pack="true" PackagePath="" />
   </ItemGroup>
 
+  <ItemGroup>
+    <Using Include="Hj.RemoteContainers.Aspire.Abstractions" />
+    <Using Include="Hj.RemoteContainers.Aspire.Docker" />
+    <Using Include="Hj.RemoteContainers.Aspire.Ssh" />
+  </ItemGroup>
+
   <ItemGroup>
     <PackageReference Include="Aspire.Hosting" />
     <PackageReference Include="Microsoft.Extensions.Http.Resilience" />
@@ -31,4 +37,8 @@
     <AdditionalFiles Include="..\..\stylecop.json" />
   </ItemGroup>
 
+  <ItemGroup>
+    <Folder Include="Docker/" />
+  </ItemGroup>
+
 </Project>
diff --git a/src/RemoteContainers.Aspire/Ssh/ISshConnection.cs b/src/RemoteContainers.Aspire/Ssh/ISshConnection.cs
new file mode 100644
index 0000000..f5d6599
--- /dev/null
+++ b/src/RemoteContainers.Aspire/Ssh/ISshConnection.cs
@@ -0,0 +1,26 @@
+// <copyright file="ISshConnection.cs" company="Henrik Jensen">
+// Copyright 2026 Henrik Jensen
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+namespace Hj.RemoteContainers.Aspire.Ssh;
+
+internal interface ISshConnection : IDisposable
+{
+  bool IsConnected { get; }
+
+  void Connect();
+
+  ISshForwardedPort ForwardPort(uint port);
+}
diff --git a/src/RemoteContainers.Aspire/Ssh/ISshTunnelManager.cs b/src/RemoteContainers.Aspire/Ssh/ISshTunnelManager.cs
new file mode 100644
index 0000000..78ffb9a
--- /dev/null
+++ b/src/RemoteContainers.Aspire/Ssh/ISshTunnelManager.cs
@@ -0,0 +1,24 @@
+// <copyright file="ISshTunnelManager.cs" company="Henrik Jensen">
+// Copyright 2026 Henrik Jensen
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+namespace Hj.RemoteContainers.Aspire.Ssh;
+
+internal interface ISshTunnelManager
+{
+  Task AddAllContainerPortForwardsAsync(string resourceName, CancellationToken cancellationToken);
+
+  void RemoveAllContainerPortForwards(string resourceName);
+}
diff --git a/src/RemoteContainers.Aspire/SshTunnelClient.cs b/src/RemoteContainers.Aspire/Ssh/SshConnection.cs
similarity index 89%
rename from src/RemoteContainers.Aspire/SshTunnelClient.cs
rename to src/RemoteContainers.Aspire/Ssh/SshConnection.cs
index c86e3d3..d05b33c 100644
--- a/src/RemoteContainers.Aspire/SshTunnelClient.cs
+++ b/src/RemoteContainers.Aspire/Ssh/SshConnection.cs
@@ -1,4 +1,4 @@
-// <copyright file="SshTunnelClient.cs" company="Henrik Jensen">
+// <copyright file="SshConnection.cs" company="Henrik Jensen">
 // Copyright 2026 Henrik Jensen
 //
 // Licensed under the Apache License, Version 2.0 (the "License")
@@ -17,9 +17,9 @@
 using System.Diagnostics.CodeAnalysis;
 using Renci.SshNet;
 
-namespace Hj.RemoteContainers.Aspire;
+namespace Hj.RemoteContainers.Aspire.Ssh;
 
-internal sealed class SshTunnelClient : IDisposable
+internal sealed class SshConnection : ISshConnection
 {
   private readonly AppConfiguration _appConfiguration;
 
@@ -28,7 +28,7 @@ internal sealed class SshTunnelClient : IDisposable
 
   private bool _disposedValue;
 
-  public SshTunnelClient(AppConfiguration appConfiguration) => _appConfiguration = appConfiguration;
+  public SshConnection(AppConfiguration appConfiguration) => _appConfiguration = appConfiguration;
 
   [MemberNotNullWhen(true, nameof(_sshClient))]
   public bool IsConnected => _sshClient?.IsConnected ?? false;
@@ -66,7 +66,7 @@ public void Dispose()
   }
 
   [SuppressMessage("Reliability", "CA2000:Dispose objects before losing scope", Justification = "See Dispose()")]
-  public ForwardedPortLocal ForwardPort(uint port)
+  public ISshForwardedPort ForwardPort(uint port)
   {
     if (!IsConnected)
     {
@@ -86,7 +86,7 @@ public ForwardedPortLocal ForwardPort(uint port)
       throw;
     }
 
-    return forwardedPort;
+    return new SshForwardedPort(forwardedPort);
   }
 
   private static List<PrivateKeyFile> LoadSshKeyFiles(string keyDir)
diff --git a/src/RemoteContainers.Aspire/SshTunnelManager.cs b/src/RemoteContainers.Aspire/Ssh/SshTunnelManager.cs
similarity index 83%
rename from src/RemoteContainers.Aspire/SshTunnelManager.cs
rename to src/RemoteContainers.Aspire/Ssh/SshTunnelManager.cs
index f02fa5c..a1ee770 100644
--- a/src/RemoteContainers.Aspire/SshTunnelManager.cs
+++ b/src/RemoteContainers.Aspire/Ssh/SshTunnelManager.cs
@@ -17,33 +17,32 @@
 using System.Collections.Concurrent;
 using System.Diagnostics.CodeAnalysis;
 using Microsoft.Extensions.Logging;
-using Renci.SshNet;
 
-namespace Hj.RemoteContainers.Aspire;
+namespace Hj.RemoteContainers.Aspire.Ssh;
 
 /// <summary>
 /// Manages SSH port forwarding tunnels for remote Docker container access.
 /// </summary>
-internal sealed class SshTunnelManager : IDisposable
+internal sealed class SshTunnelManager : ISshTunnelManager, IDisposable
 {
   private readonly ILogger<SshTunnelManager> _logger;
-  private readonly DockerApiClient _dockerApiClient;
-  private readonly Lazy<SshTunnelClient> _sshTunnelClient;
+  private readonly IDockerApiClient _dockerApiClient;
+  private readonly Lazy<ISshConnection> _sshConnection;
 
-  private readonly ConcurrentDictionary<string, ConcurrentBag<ForwardedPortLocal>> _forwardedPortsByResource = new();
+  private readonly ConcurrentDictionary<string, ConcurrentBag<ISshForwardedPort>> _forwardedPortsByResource = new();
   private bool _disposedValue;
 
   public SshTunnelManager(
     ILogger<SshTunnelManager> logger,
-    SshTunnelClient sshTunnelClient,
-    DockerApiClient dockerApiClient)
+    ISshConnection sshConnection,
+    IDockerApiClient dockerApiClient)
   {
     _logger = logger;
     _dockerApiClient = dockerApiClient;
-    _sshTunnelClient = new Lazy<SshTunnelClient>(() =>
+    _sshConnection = new Lazy<ISshConnection>(() =>
     {
-      sshTunnelClient.Connect();
-      return sshTunnelClient;
+      sshConnection.Connect();
+      return sshConnection;
     });
   }
 
@@ -56,7 +55,7 @@ public SshTunnelManager(
   [SuppressMessage("Reliability", "CA2000:Dispose objects before losing scope", Justification = "See Dispose()")]
   public async Task AddAllContainerPortForwardsAsync(string resourceName, CancellationToken cancellationToken)
   {
-    if (!_sshTunnelClient.Value.IsConnected)
+    if (!_sshConnection.Value.IsConnected)
     {
       return;
     }
@@ -71,7 +70,7 @@ public async Task AddAllContainerPortForwardsAsync(string resourceName, Cancella
 
     foreach (var port in portMappings)
     {
-      var forwardedPort = _sshTunnelClient.Value.ForwardPort(port);
+      var forwardedPort = _sshConnection.Value.ForwardPort(port);
       resourcePorts.Add(forwardedPort);
 
       if (_logger.IsEnabled(LogLevel.Information))
@@ -131,9 +130,9 @@ private void Dispose(bool disposing)
           RemoveAllContainerPortForwards(resourceName);
         }
 
-        if (_sshTunnelClient.IsValueCreated)
+        if (_sshConnection.IsValueCreated)
         {
-          _sshTunnelClient.Value.Dispose();
+          _sshConnection.Value.Dispose();
         }
       }
 
diff --git a/src/RemoteContainers.Aspire/SshTunnelExtensions.cs b/src/RemoteContainers.Aspire/SshTunnelExtensions.cs
index 12f75b2..9eeb3fc 100644
--- a/src/RemoteContainers.Aspire/SshTunnelExtensions.cs
+++ b/src/RemoteContainers.Aspire/SshTunnelExtensions.cs
@@ -45,7 +45,7 @@ public static IDistributedApplicationBuilder AddSshTunneling(this IDistributedAp
       return builder;
     }
 
-    services.AddHttpClient<DockerApiClient>(httpClient =>
+    services.AddHttpClient<IDockerApiClient, DockerApiClient>(httpClient =>
       {
         httpClient.BaseAddress = appConfiguration.DockerHost.Uri;
       })
@@ -54,9 +54,10 @@ public static IDistributedApplicationBuilder AddSshTunneling(this IDistributedAp
 
     services
       .AddSingleton(appConfiguration)
+      .AddSingleton<IFileSystem, FileSystem>()
       .AddSingleton<DockerCertificate>()
-      .AddSingleton<SshTunnelClient>()
-      .AddSingleton<SshTunnelManager>()
+      .AddSingleton<ISshConnection, SshConnection>()
+      .AddSingleton<ISshTunnelManager, SshTunnelManager>()
       .AddEventingSubscriber<SshTunnelLifecycleHook>();
 
     return builder;
diff --git a/src/RemoteContainers.Aspire/SshTunnelLifecycleHook.cs b/src/RemoteContainers.Aspire/SshTunnelLifecycleHook.cs
index 09475af..87a54f6 100644
--- a/src/RemoteContainers.Aspire/SshTunnelLifecycleHook.cs
+++ b/src/RemoteContainers.Aspire/SshTunnelLifecycleHook.cs
@@ -25,9 +25,9 @@ namespace Hj.RemoteContainers.Aspire;
 internal sealed class SshTunnelLifecycleHook : IDistributedApplicationEventingSubscriber
 {
   private readonly ILogger<SshTunnelLifecycleHook> _logger;
-  private readonly SshTunnelManager _tunnelManager;
+  private readonly ISshTunnelManager _tunnelManager;
 
-  public SshTunnelLifecycleHook(ILogger<SshTunnelLifecycleHook> logger, SshTunnelManager tunnelManager)
+  public SshTunnelLifecycleHook(ILogger<SshTunnelLifecycleHook> logger, ISshTunnelManager tunnelManager)
   {
     _logger = logger;
     _tunnelManager = tunnelManager;
diff --git a/test/RemoteContainers.Aspire.UnitTest/RemoteContainers.Aspire.UnitTest.csproj b/test/RemoteContainers.Aspire.UnitTest/RemoteContainers.Aspire.UnitTest.csproj
new file mode 100644
index 0000000..fd4eda3
--- /dev/null
+++ b/test/RemoteContainers.Aspire.UnitTest/RemoteContainers.Aspire.UnitTest.csproj
@@ -0,0 +1,32 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <IsPackable>false</IsPackable>
+    <GenerateDocumentationFile>false</GenerateDocumentationFile>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <Using Include="Xunit" />
+    <Using Include="NSubstitute" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="NSubstitute" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" />
+    <PackageReference Include="xunit" />
+    <PackageReference Include="xunit.analyzers">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
+    <PackageReference Include="xunit.runner.visualstudio">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
+    <PackageReference Include="coverlet.collector">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
+  </ItemGroup>
+
+</Project>
diff --git a/test/RemoteContainers.Aspire.UnitTest/UnitTest1.cs b/test/RemoteContainers.Aspire.UnitTest/UnitTest1.cs
new file mode 100644
index 0000000..eb4b04d
--- /dev/null
+++ b/test/RemoteContainers.Aspire.UnitTest/UnitTest1.cs
@@ -0,0 +1,10 @@
+namespace Hj.RemoteContainers.Aspire.UnitTest;
+
+public class UnitTest1
+{
+  [Fact]
+  public void Test1()
+  {
+    // to do
+  }
+}

From 4e16ba98ca03c101536c2b79952b876b5bd49417 Mon Sep 17 00:00:00 2001
From: Henrik Jensen <1175002+henrikhimself@users.noreply.github.com>
Date: Thu, 12 Mar 2026 07:58:10 +0100
Subject: [PATCH 14/25] Address code review comments. Add DockerMessageHandler

---
 .../Abstractions/ISshForwardedPort.cs         |  2 -
 .../Abstractions/SshForwardedPort.cs          |  2 -
 .../Docker/DockerCertificate.cs               |  6 +-
 .../Docker/DockerMessageHandler.cs            | 64 +++++++++++++++++++
 .../Ssh/SshTunnelManager.cs                   |  6 +-
 .../SshTunnelExtensions.cs                    | 27 +-------
 6 files changed, 72 insertions(+), 35 deletions(-)
 create mode 100644 src/RemoteContainers.Aspire/Docker/DockerMessageHandler.cs

diff --git a/src/RemoteContainers.Aspire/Abstractions/ISshForwardedPort.cs b/src/RemoteContainers.Aspire/Abstractions/ISshForwardedPort.cs
index 8d3e4e7..8cefaf7 100644
--- a/src/RemoteContainers.Aspire/Abstractions/ISshForwardedPort.cs
+++ b/src/RemoteContainers.Aspire/Abstractions/ISshForwardedPort.cs
@@ -20,7 +20,5 @@ internal interface ISshForwardedPort : IDisposable
 {
   uint Port { get; }
 
-  uint? BoundPort { get; }
-
   void Stop();
 }
diff --git a/src/RemoteContainers.Aspire/Abstractions/SshForwardedPort.cs b/src/RemoteContainers.Aspire/Abstractions/SshForwardedPort.cs
index a3e3f33..fa16756 100644
--- a/src/RemoteContainers.Aspire/Abstractions/SshForwardedPort.cs
+++ b/src/RemoteContainers.Aspire/Abstractions/SshForwardedPort.cs
@@ -26,8 +26,6 @@ internal sealed class SshForwardedPort : ISshForwardedPort
 
   public uint Port => _forwardedPort.Port;
 
-  public uint? BoundPort => _forwardedPort.BoundPort;
-
   public void Stop() => _forwardedPort.Stop();
 
   public void Dispose() => _forwardedPort.Dispose();
diff --git a/src/RemoteContainers.Aspire/Docker/DockerCertificate.cs b/src/RemoteContainers.Aspire/Docker/DockerCertificate.cs
index ace123f..2802dae 100644
--- a/src/RemoteContainers.Aspire/Docker/DockerCertificate.cs
+++ b/src/RemoteContainers.Aspire/Docker/DockerCertificate.cs
@@ -55,7 +55,7 @@ public bool TryGetCertificate([NotNullWhen(true)] out X509Certificate2? caCert,
     {
       if (_logger.IsEnabled(LogLevel.Error))
       {
-        _logger.LogError("Failed to get CA");
+        _logger.LogError("Failed to load CA using path '{DockerCertPath}'", dockerCertPath);
       }
 
       return false;
@@ -66,7 +66,7 @@ public bool TryGetCertificate([NotNullWhen(true)] out X509Certificate2? caCert,
     {
       if (_logger.IsEnabled(LogLevel.Error))
       {
-        _logger.LogError("Failed to get client certificate");
+        _logger.LogError("Failed to load client certificate using path '{DockerCertPath}'", dockerCertPath);
       }
 
       _caCert.Dispose();
@@ -87,7 +87,7 @@ public void Dispose()
 
   private static X509Certificate2 Clone(X509Certificate2 cert)
   {
-    var keyStorageFlags = X509KeyStorageFlags.Exportable | X509KeyStorageFlags.PersistKeySet;
+    var keyStorageFlags = X509KeyStorageFlags.Exportable;
     var pfxBytes = cert.Export(X509ContentType.Pkcs12, string.Empty);
     return X509CertificateLoader.LoadPkcs12(pfxBytes, string.Empty, keyStorageFlags);
   }
diff --git a/src/RemoteContainers.Aspire/Docker/DockerMessageHandler.cs b/src/RemoteContainers.Aspire/Docker/DockerMessageHandler.cs
new file mode 100644
index 0000000..dcd885d
--- /dev/null
+++ b/src/RemoteContainers.Aspire/Docker/DockerMessageHandler.cs
@@ -0,0 +1,64 @@
+// <copyright file="DockerMessageHandler.cs" company="Henrik Jensen">
+// Copyright 2026 Henrik Jensen
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+using System.Security.Cryptography.X509Certificates;
+
+namespace Hj.RemoteContainers.Aspire.Docker;
+
+internal sealed class DockerMessageHandler : HttpClientHandler, IDisposable
+{
+  private readonly DockerCertificate _dockerCertificate;
+
+  private X509Certificate2? _caCert;
+  private X509Certificate2? _clientCert;
+
+  private volatile bool _disposed;
+
+  public DockerMessageHandler(DockerCertificate dockerCertificate) => _dockerCertificate = dockerCertificate;
+
+  public HttpMessageHandler Init()
+  {
+    if (_dockerCertificate.TryGetCertificate(out _caCert, out _clientCert))
+    {
+      ClientCertificates.Add(_clientCert);
+      ServerCertificateCustomValidationCallback = (_, serverCert, chain, _) =>
+      {
+        if (serverCert is null || chain is null)
+        {
+          return false;
+        }
+
+        chain.ChainPolicy.CustomTrustStore.Add(_caCert);
+        chain.ChainPolicy.TrustMode = X509ChainTrustMode.CustomRootTrust;
+        return chain.Build(serverCert);
+      };
+    }
+
+    return this;
+  }
+
+  protected override void Dispose(bool disposing)
+  {
+    if (disposing && !_disposed)
+    {
+      _disposed = true;
+      _caCert?.Dispose();
+      _clientCert?.Dispose();
+    }
+
+    base.Dispose(disposing);
+  }
+}
diff --git a/src/RemoteContainers.Aspire/Ssh/SshTunnelManager.cs b/src/RemoteContainers.Aspire/Ssh/SshTunnelManager.cs
index a1ee770..0756609 100644
--- a/src/RemoteContainers.Aspire/Ssh/SshTunnelManager.cs
+++ b/src/RemoteContainers.Aspire/Ssh/SshTunnelManager.cs
@@ -66,7 +66,7 @@ public async Task AddAllContainerPortForwardsAsync(string resourceName, Cancella
       return;
     }
 
-    var resourcePorts = _forwardedPortsByResource.GetOrAdd(resourceName, _ => []);
+    var resourcePorts = _forwardedPortsByResource.GetOrAdd(resourceName, _ => new ConcurrentBag<ISshForwardedPort>());
 
     foreach (var port in portMappings)
     {
@@ -100,14 +100,14 @@ public void RemoveAllContainerPortForwards(string resourceName)
 
         if (_logger.IsEnabled(LogLevel.Information))
         {
-          _logger.LogInformation("SSH tunnel removed for {ResourceName} port {Port}", resourceName, forwardedPort.BoundPort);
+          _logger.LogInformation("SSH tunnel removed for {ResourceName} port {Port}", resourceName, forwardedPort.Port);
         }
       }
       catch (Exception ex)
       {
         if (_logger.IsEnabled(LogLevel.Warning))
         {
-          _logger.LogWarning(ex, "Failed to clean up SSH tunnel for {ResourceName} port {Port}", resourceName, forwardedPort.BoundPort);
+          _logger.LogWarning(ex, "Failed to clean up SSH tunnel for {ResourceName} port {Port}", resourceName, forwardedPort.Port);
         }
       }
     }
diff --git a/src/RemoteContainers.Aspire/SshTunnelExtensions.cs b/src/RemoteContainers.Aspire/SshTunnelExtensions.cs
index 9eeb3fc..02e880c 100644
--- a/src/RemoteContainers.Aspire/SshTunnelExtensions.cs
+++ b/src/RemoteContainers.Aspire/SshTunnelExtensions.cs
@@ -14,7 +14,6 @@
 // limitations under the License.
 // </copyright>
 
-using System.Security.Cryptography.X509Certificates;
 using Aspire.Hosting;
 using Aspire.Hosting.Lifecycle;
 using Microsoft.Extensions.DependencyInjection;
@@ -49,40 +48,18 @@ public static IDistributedApplicationBuilder AddSshTunneling(this IDistributedAp
       {
         httpClient.BaseAddress = appConfiguration.DockerHost.Uri;
       })
-      .ConfigurePrimaryHttpMessageHandler(CreateHttpMessageHandler)
+      .ConfigurePrimaryHttpMessageHandler(sp => sp.GetRequiredService<DockerMessageHandler>().Init())
       .AddStandardResilienceHandler();
 
     services
       .AddSingleton(appConfiguration)
       .AddSingleton<IFileSystem, FileSystem>()
       .AddSingleton<DockerCertificate>()
+      .AddTransient<DockerMessageHandler>()
       .AddSingleton<ISshConnection, SshConnection>()
       .AddSingleton<ISshTunnelManager, SshTunnelManager>()
       .AddEventingSubscriber<SshTunnelLifecycleHook>();
 
     return builder;
   }
-
-  private static HttpMessageHandler CreateHttpMessageHandler(IServiceProvider sp)
-  {
-    var handler = new HttpClientHandler();
-    var dockerCert = sp.GetRequiredService<DockerCertificate>();
-    if (dockerCert.TryGetCertificate(out var caCert, out var clientCert))
-    {
-      handler.ClientCertificates.Add(clientCert);
-      handler.ServerCertificateCustomValidationCallback = (_, serverCert, chain, _) =>
-      {
-        if (serverCert is null || chain is null)
-        {
-          return false;
-        }
-
-        chain.ChainPolicy.CustomTrustStore.Add(caCert);
-        chain.ChainPolicy.TrustMode = X509ChainTrustMode.CustomRootTrust;
-        return chain.Build(serverCert);
-      };
-    }
-
-    return handler;
-  }
 }

From b717a752d459696e72fe03f58560b348b7776f99 Mon Sep 17 00:00:00 2001
From: Henrik Jensen <1175002+henrikhimself@users.noreply.github.com>
Date: Fri, 13 Mar 2026 08:44:00 +0100
Subject: [PATCH 15/25] Add unit tests

---
 .../Docker/DockerCertificate.cs               |   2 +-
 .../Docker/DockerMessageHandler.cs            |   4 +-
 .../Docker/IDockerCertificate.cs              |  25 ++
 .../RemoteContainers.Aspire.csproj            |  12 +-
 .../Ssh/SshConnection.cs                      |   1 +
 .../SshTunnelExtensions.cs                    |   4 +-
 test/.editorconfig                            |   9 +
 .../AppConfigurationTests.cs                  | 370 ++++++++++++++++++
 .../DockerApiClientTests.cs                   | 258 ++++++++++++
 .../DockerCertificateTests.cs                 | 227 +++++++++++
 .../DockerMessageHandlerTests.cs              | 184 +++++++++
 .../RemoteContainers.Aspire.UnitTest.csproj   |  10 +-
 .../SshTunnelLifecycleHookTests.cs            | 228 +++++++++++
 .../SshTunnelManagerTests.cs                  | 235 +++++++++++
 .../UnitTest1.cs                              |  10 -
 15 files changed, 1563 insertions(+), 16 deletions(-)
 create mode 100644 src/RemoteContainers.Aspire/Docker/IDockerCertificate.cs
 create mode 100644 test/.editorconfig
 create mode 100644 test/RemoteContainers.Aspire.UnitTest/AppConfigurationTests.cs
 create mode 100644 test/RemoteContainers.Aspire.UnitTest/DockerApiClientTests.cs
 create mode 100644 test/RemoteContainers.Aspire.UnitTest/DockerCertificateTests.cs
 create mode 100644 test/RemoteContainers.Aspire.UnitTest/DockerMessageHandlerTests.cs
 create mode 100644 test/RemoteContainers.Aspire.UnitTest/SshTunnelLifecycleHookTests.cs
 create mode 100644 test/RemoteContainers.Aspire.UnitTest/SshTunnelManagerTests.cs
 delete mode 100644 test/RemoteContainers.Aspire.UnitTest/UnitTest1.cs

diff --git a/src/RemoteContainers.Aspire/Docker/DockerCertificate.cs b/src/RemoteContainers.Aspire/Docker/DockerCertificate.cs
index 2802dae..608df14 100644
--- a/src/RemoteContainers.Aspire/Docker/DockerCertificate.cs
+++ b/src/RemoteContainers.Aspire/Docker/DockerCertificate.cs
@@ -20,7 +20,7 @@
 
 namespace Hj.RemoteContainers.Aspire.Docker;
 
-internal sealed class DockerCertificate : IDisposable
+internal sealed class DockerCertificate : IDockerCertificate, IDisposable
 {
   private readonly ILogger<DockerCertificate> _logger;
   private readonly AppConfiguration _appConfiguration;
diff --git a/src/RemoteContainers.Aspire/Docker/DockerMessageHandler.cs b/src/RemoteContainers.Aspire/Docker/DockerMessageHandler.cs
index dcd885d..0237035 100644
--- a/src/RemoteContainers.Aspire/Docker/DockerMessageHandler.cs
+++ b/src/RemoteContainers.Aspire/Docker/DockerMessageHandler.cs
@@ -20,14 +20,14 @@ namespace Hj.RemoteContainers.Aspire.Docker;
 
 internal sealed class DockerMessageHandler : HttpClientHandler, IDisposable
 {
-  private readonly DockerCertificate _dockerCertificate;
+  private readonly IDockerCertificate _dockerCertificate;
 
   private X509Certificate2? _caCert;
   private X509Certificate2? _clientCert;
 
   private volatile bool _disposed;
 
-  public DockerMessageHandler(DockerCertificate dockerCertificate) => _dockerCertificate = dockerCertificate;
+  public DockerMessageHandler(IDockerCertificate dockerCertificate) => _dockerCertificate = dockerCertificate;
 
   public HttpMessageHandler Init()
   {
diff --git a/src/RemoteContainers.Aspire/Docker/IDockerCertificate.cs b/src/RemoteContainers.Aspire/Docker/IDockerCertificate.cs
new file mode 100644
index 0000000..8d76e42
--- /dev/null
+++ b/src/RemoteContainers.Aspire/Docker/IDockerCertificate.cs
@@ -0,0 +1,25 @@
+// <copyright file="IDockerCertificate.cs" company="Henrik Jensen">
+// Copyright 2026 Henrik Jensen
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+using System.Diagnostics.CodeAnalysis;
+using System.Security.Cryptography.X509Certificates;
+
+namespace Hj.RemoteContainers.Aspire.Docker;
+
+internal interface IDockerCertificate
+{
+  bool TryGetCertificate([NotNullWhen(true)] out X509Certificate2? caCert, [NotNullWhen(true)] out X509Certificate2? clientCert);
+}
diff --git a/src/RemoteContainers.Aspire/RemoteContainers.Aspire.csproj b/src/RemoteContainers.Aspire/RemoteContainers.Aspire.csproj
index e5867fc..b149442 100644
--- a/src/RemoteContainers.Aspire/RemoteContainers.Aspire.csproj
+++ b/src/RemoteContainers.Aspire/RemoteContainers.Aspire.csproj
@@ -2,12 +2,13 @@
 
   <PropertyGroup>
     <TargetFramework>net10.0</TargetFramework>
+    <EnableNETAnalyzers>true</EnableNETAnalyzers>
     <AnalysisMode>Recommended</AnalysisMode>
     <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <IsPackable>true</IsPackable>
     <IncludeSymbols>true</IncludeSymbols>
     <SymbolPackageFormat>snupkg</SymbolPackageFormat>
-    <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <PackageId>HenrikJensen.RemoteContainers.Aspire</PackageId>
     <Description>Use Aspire with a remote Docker/Podman engine via SSH tunneling.</Description>
     <PackageTags>aspire;docker;podman;ssh;tunneling;remote;containers</PackageTags>
@@ -33,6 +34,15 @@
     <PackageReference Include="SSH.NET" />
   </ItemGroup>
 
+  <ItemGroup>
+    <AssemblyAttribute Include="System.Runtime.CompilerServices.InternalsVisibleToAttribute">
+      <_Parameter1>RemoteContainers.Aspire.UnitTest</_Parameter1>
+    </AssemblyAttribute>
+    <AssemblyAttribute Include="System.Runtime.CompilerServices.InternalsVisibleToAttribute">
+      <_Parameter1>DynamicProxyGenAssembly2</_Parameter1>
+    </AssemblyAttribute>
+  </ItemGroup>
+
   <ItemGroup>
     <AdditionalFiles Include="..\..\stylecop.json" />
   </ItemGroup>
diff --git a/src/RemoteContainers.Aspire/Ssh/SshConnection.cs b/src/RemoteContainers.Aspire/Ssh/SshConnection.cs
index d05b33c..066145f 100644
--- a/src/RemoteContainers.Aspire/Ssh/SshConnection.cs
+++ b/src/RemoteContainers.Aspire/Ssh/SshConnection.cs
@@ -19,6 +19,7 @@
 
 namespace Hj.RemoteContainers.Aspire.Ssh;
 
+[ExcludeFromCodeCoverage(Justification = "External dependencies")]
 internal sealed class SshConnection : ISshConnection
 {
   private readonly AppConfiguration _appConfiguration;
diff --git a/src/RemoteContainers.Aspire/SshTunnelExtensions.cs b/src/RemoteContainers.Aspire/SshTunnelExtensions.cs
index 02e880c..9dca6e9 100644
--- a/src/RemoteContainers.Aspire/SshTunnelExtensions.cs
+++ b/src/RemoteContainers.Aspire/SshTunnelExtensions.cs
@@ -14,6 +14,7 @@
 // limitations under the License.
 // </copyright>
 
+using System.Diagnostics.CodeAnalysis;
 using Aspire.Hosting;
 using Aspire.Hosting.Lifecycle;
 using Microsoft.Extensions.DependencyInjection;
@@ -29,6 +30,7 @@ public static class SshTunnelExtensions
   /// </summary>
   /// <param name="builder">An application builder instance.</param>
   /// <returns>The application builder instance.</returns>
+  [ExcludeFromCodeCoverage(Justification = "Initialization code")]
   public static IDistributedApplicationBuilder AddSshTunneling(this IDistributedApplicationBuilder builder)
   {
     var services = builder.Services;
@@ -54,7 +56,7 @@ public static IDistributedApplicationBuilder AddSshTunneling(this IDistributedAp
     services
       .AddSingleton(appConfiguration)
       .AddSingleton<IFileSystem, FileSystem>()
-      .AddSingleton<DockerCertificate>()
+      .AddSingleton<IDockerCertificate, DockerCertificate>()
       .AddTransient<DockerMessageHandler>()
       .AddSingleton<ISshConnection, SshConnection>()
       .AddSingleton<ISshTunnelManager, SshTunnelManager>()
diff --git a/test/.editorconfig b/test/.editorconfig
new file mode 100644
index 0000000..ccb35c2
--- /dev/null
+++ b/test/.editorconfig
@@ -0,0 +1,9 @@
+[*.cs]
+# CA1707: Test method names intentionally use underscores (Subject_Scenario_Expectation convention)
+dotnet_diagnostic.CA1707.severity = none
+
+# CA2000: Dispose objects before losing scope - suppressed in test code where IDisposable mocks are
+#         intentionally passed to the SUT which owns their lifetime, or disposal is being verified
+dotnet_diagnostic.CA2000.severity = none
+# IDE1006: Test method names intentionally do not include the Async suffix
+dotnet_diagnostic.IDE1006.severity = none
diff --git a/test/RemoteContainers.Aspire.UnitTest/AppConfigurationTests.cs b/test/RemoteContainers.Aspire.UnitTest/AppConfigurationTests.cs
new file mode 100644
index 0000000..6d7cfc1
--- /dev/null
+++ b/test/RemoteContainers.Aspire.UnitTest/AppConfigurationTests.cs
@@ -0,0 +1,370 @@
+using System.Collections;
+using Microsoft.Extensions.Configuration;
+
+namespace Hj.RemoteContainers.Aspire.UnitTest;
+
+public sealed class AppConfigurationTests
+{
+  [Fact]
+  public void ContainerStartTimeout_WhenNotConfigured_ReturnsFiveMinutes()
+  {
+    // Arrange
+    var sut = Fixture.Create().Build();
+
+    // Act
+    var result = sut.ContainerStartTimeout;
+
+    // Assert
+    Assert.Equal(TimeSpan.FromMinutes(5), result);
+  }
+
+  [Fact]
+  public void ContainerStartTimeout_WhenConfigured_ReturnsConfiguredValue()
+  {
+    // Arrange
+    var sut = Fixture.Create()
+        .WithConfig("RemoteContainers:ContainerStartTimeout", "00:02:30")
+        .Build();
+
+    // Act
+    var result = sut.ContainerStartTimeout;
+
+    // Assert
+    Assert.Equal(TimeSpan.FromMinutes(2.5), result);
+  }
+
+  [Fact]
+  public void ContainerPollInterval_WhenNotConfigured_ReturnsFiveSeconds()
+  {
+    // Arrange
+    var sut = Fixture.Create().Build();
+
+    // Act
+    var result = sut.ContainerPollInterval;
+
+    // Assert
+    Assert.Equal(TimeSpan.FromSeconds(5), result);
+  }
+
+  [Fact]
+  public void ContainerPollInterval_WhenConfigured_ReturnsConfiguredValue()
+  {
+    // Arrange
+    var sut = Fixture.Create()
+        .WithConfig("RemoteContainers:ContainerPollInterval", "00:00:01")
+        .Build();
+
+    // Act
+    var result = sut.ContainerPollInterval;
+
+    // Assert
+    Assert.Equal(TimeSpan.FromSeconds(1), result);
+  }
+
+  [Fact]
+  public void SshKeyPath_ReturnsDotSshUnderUserProfile()
+  {
+    // Arrange
+    var sut = Fixture.Create()
+        .WithUserProfilePath("/home/user")
+        .Build();
+
+    // Act
+    var result = sut.SshKeyPath;
+
+    // Assert
+    Assert.Equal("/home/user/.ssh", result);
+  }
+
+  [Fact]
+  public void SshUser_WhenConfigured_ReturnsConfiguredValue()
+  {
+    // Arrange
+    var sut = Fixture.Create()
+        .WithConfig("RemoteContainers:SshUser", "deploy")
+        .Build();
+
+    // Act
+    var result = sut.SshUser;
+
+    // Assert
+    Assert.Equal("deploy", result);
+  }
+
+  [Fact]
+  public void SshUser_WhenNotConfigured_ReturnsEnvironmentUserName()
+  {
+    // Arrange
+    var sut = Fixture.Create()
+        .WithUserName("system-user")
+        .Build();
+
+    // Act
+    var result = sut.SshUser;
+
+    // Assert
+    Assert.Equal("system-user", result);
+  }
+
+  [Fact]
+  public void SshUser_WhenConfiguredWithWhitespace_ReturnsEnvironmentUserName()
+  {
+    // Arrange
+    var sut = Fixture.Create()
+        .WithConfig("RemoteContainers:SshUser", "   ")
+        .WithUserName("system-user")
+        .Build();
+
+    // Act
+    var result = sut.SshUser;
+
+    // Assert
+    Assert.Equal("system-user", result);
+  }
+
+  [Fact]
+  public void SshHost_WhenConfigured_ReturnsConfiguredValue()
+  {
+    // Arrange
+    var sut = Fixture.Create()
+        .WithConfig("RemoteContainers:SshHost", "my-server")
+        .Build();
+
+    // Act
+    var result = sut.SshHost;
+
+    // Assert
+    Assert.Equal("my-server", result);
+  }
+
+  [Fact]
+  public void SshHost_WhenNotConfigured_FallsBackToDockerHostname()
+  {
+    // Arrange
+    var sut = Fixture.Create()
+        .WithEnvVar("DOCKER_HOST", "tcp://remote-host:2376")
+        .Build();
+
+    // Act
+    var result = sut.SshHost;
+
+    // Assert
+    Assert.Equal("remote-host", result);
+  }
+
+  [Fact]
+  public void SshHost_WhenNotConfiguredAndNoDockerHost_Throws()
+  {
+    // Arrange
+    var sut = Fixture.Create().Build();
+
+    // Act & Assert
+    Assert.Throws<InvalidOperationException>(() => sut.SshHost);
+  }
+
+  [Fact]
+  public void SshHost_WhenConfiguredWithWhitespace_FallsBackToDockerHostname()
+  {
+    // Arrange
+    var sut = Fixture.Create()
+        .WithConfig("RemoteContainers:SshHost", "   ")
+        .WithEnvVar("DOCKER_HOST", "tcp://remote-host:2376")
+        .Build();
+
+    // Act
+    var result = sut.SshHost;
+
+    // Assert
+    Assert.Equal("remote-host", result);
+  }
+
+  [Fact]
+  public void HasDockerHost_WhenDockerHostIsTcp_ReturnsTrue()
+  {
+    // Arrange
+    var sut = Fixture.Create()
+        .WithEnvVar("DOCKER_HOST", "tcp://remote-host:2376")
+        .Build();
+
+    // Act
+    var result = sut.HasDockerHost;
+
+    // Assert
+    Assert.True(result);
+  }
+
+  [Fact]
+  public void HasDockerHost_WhenDockerHostIsNotTcp_ReturnsFalse()
+  {
+    // Arrange
+    var sut = Fixture.Create()
+        .WithEnvVar("DOCKER_HOST", "unix:///var/run/docker.sock")
+        .Build();
+
+    // Act
+    var result = sut.HasDockerHost;
+
+    // Assert
+    Assert.False(result);
+  }
+
+  [Fact]
+  public void HasDockerHost_WhenDockerHostIsNotSet_ReturnsFalse()
+  {
+    // Arrange
+    var sut = Fixture.Create().Build();
+
+    // Act
+    var result = sut.HasDockerHost;
+
+    // Assert
+    Assert.False(result);
+  }
+
+  [Fact]
+  public void DockerHost_WhenTlsEnabled_UsesHttpsScheme()
+  {
+    // Arrange
+    var sut = Fixture.Create()
+        .WithEnvVar("DOCKER_HOST", "tcp://remote-host:2376")
+        .WithEnvVar("DOCKER_TLS_VERIFY", "1")
+        .WithEnvVar("DOCKER_CERT_PATH", "/certs")
+        .Build();
+
+    // Act
+    var result = sut.DockerHost;
+
+    // Assert
+    Assert.Equal("https", result?.Scheme);
+  }
+
+  [Fact]
+  public void DockerHost_WhenTlsNotEnabled_UsesHttpScheme()
+  {
+    // Arrange
+    var sut = Fixture.Create()
+        .WithEnvVar("DOCKER_HOST", "tcp://remote-host:2375")
+        .Build();
+
+    // Act
+    var result = sut.DockerHost;
+
+    // Assert
+    Assert.Equal("http", result?.Scheme);
+  }
+
+  [Fact]
+  public void DockerHost_WhenDockerHostNotSet_ReturnsNull()
+  {
+    // Arrange
+    var sut = Fixture.Create().Build();
+
+    // Act
+    var result = sut.DockerHost;
+
+    // Assert
+    Assert.Null(result);
+  }
+
+  [Fact]
+  public void IsDockerTls_WhenVerifyAndCertPathSet_ReturnsTrue()
+  {
+    // Arrange
+    var sut = Fixture.Create()
+        .WithEnvVar("DOCKER_TLS_VERIFY", "1")
+        .WithEnvVar("DOCKER_CERT_PATH", "/certs")
+        .Build();
+
+    // Act
+    var result = sut.IsDockerTls;
+
+    // Assert
+    Assert.True(result);
+  }
+
+  [Fact]
+  public void IsDockerTls_WhenVerifySetButNoCertPath_ReturnsFalse()
+  {
+    // Arrange
+    var sut = Fixture.Create()
+        .WithEnvVar("DOCKER_TLS_VERIFY", "1")
+        .Build();
+
+    // Act
+    var result = sut.IsDockerTls;
+
+    // Assert
+    Assert.False(result);
+  }
+
+  [Fact]
+  public void IsDockerTls_WhenCertPathSetButVerifyNotOne_ReturnsFalse()
+  {
+    // Arrange
+    var sut = Fixture.Create()
+        .WithEnvVar("DOCKER_CERT_PATH", "/certs")
+        .Build();
+
+    // Act
+    var result = sut.IsDockerTls;
+
+    // Assert
+    Assert.False(result);
+  }
+
+  [Fact]
+  public void DockerCertPath_WhenSet_ReturnsValue()
+  {
+    // Arrange
+    var sut = Fixture.Create()
+        .WithEnvVar("DOCKER_CERT_PATH", "/certs/client")
+        .Build();
+
+    // Act
+    var result = sut.DockerCertPath;
+
+    // Assert
+    Assert.Equal("/certs/client", result);
+  }
+
+  [Fact]
+  public void DockerCertPath_WhenNotSet_ReturnsNull()
+  {
+    // Arrange
+    var sut = Fixture.Create().Build();
+
+    // Act
+    var result = sut.DockerCertPath;
+
+    // Assert
+    Assert.Null(result);
+  }
+
+  private sealed record Fixture(
+    Dictionary<string, string?> ConfigValues,
+    Hashtable EnvVars,
+    string UserName,
+    string UserProfilePath)
+  {
+    public static Fixture Create() => new([], [], "test-user", "/home/test-user");
+
+    public Fixture WithConfig(string key, string value) =>
+      this with { ConfigValues = new Dictionary<string, string?>(ConfigValues) { [key] = value } };
+
+    public Fixture WithEnvVar(string key, string value) =>
+      this with { EnvVars = new Hashtable(EnvVars) { [key] = value } };
+
+    public Fixture WithUserName(string userName) => this with { UserName = userName };
+
+    public Fixture WithUserProfilePath(string path) => this with { UserProfilePath = path };
+
+    public AppConfiguration Build()
+    {
+      var config = new ConfigurationBuilder()
+          .AddInMemoryCollection(ConfigValues)
+          .Build();
+
+      return new AppConfiguration(config, UserName, UserProfilePath, EnvVars);
+    }
+  }
+}
diff --git a/test/RemoteContainers.Aspire.UnitTest/DockerApiClientTests.cs b/test/RemoteContainers.Aspire.UnitTest/DockerApiClientTests.cs
new file mode 100644
index 0000000..af2e6be
--- /dev/null
+++ b/test/RemoteContainers.Aspire.UnitTest/DockerApiClientTests.cs
@@ -0,0 +1,258 @@
+using System.Collections;
+using System.Net;
+using System.Text;
+using Hj.RemoteContainers.Aspire.Docker;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.Logging;
+
+namespace Hj.RemoteContainers.Aspire.UnitTest;
+
+public sealed class DockerApiClientTests
+{
+  [Fact]
+  public async Task GetAllContainerHostPortsAsync_WhenContainerFoundOnFirstPoll_ReturnsPortsAfterStabilisation()
+  {
+    // Arrange
+    var f = Fixture.Create(
+      ContainerJson("abc", ["/my-resource"], [8080u]),
+      ContainerJson("abc", ["/my-resource"], [8080u]));
+
+    // Act
+    var result = await f.Sut.GetAllContainerHostPortsAsync("my-resource", CancellationToken.None);
+
+    // Assert
+    Assert.Equal([8080u], result);
+  }
+
+  [Fact]
+  public async Task GetAllContainerHostPortsAsync_WhenContainerNotFoundThenFound_ReturnsPortsImmediately()
+  {
+    // Arrange
+    var f = Fixture.Create(
+      EmptyContainersJson(),
+      ContainerJson("abc", ["/my-resource"], [8080u]));
+
+    // Act
+    var result = await f.Sut.GetAllContainerHostPortsAsync("my-resource", CancellationToken.None);
+
+    // Assert
+    Assert.Equal([8080u], result);
+  }
+
+  [Fact]
+  public async Task GetAllContainerHostPortsAsync_WhenContainerIdChangesBetweenPolls_WaitsForStabilisation()
+  {
+    // Arrange — first poll sees stale container, second sees new ID, third confirms new ID
+    var f = Fixture.Create(
+      ContainerJson("stale-id", ["/my-resource"], [9090u]),
+      ContainerJson("new-id", ["/my-resource"], [8080u]),
+      ContainerJson("new-id", ["/my-resource"], [8080u]));
+
+    // Act
+    var result = await f.Sut.GetAllContainerHostPortsAsync("my-resource", CancellationToken.None);
+
+    // Assert
+    Assert.Equal([8080u], result);
+  }
+
+  [Fact]
+  public async Task GetAllContainerHostPortsAsync_WhenTimeoutExpires_ReturnsNull()
+  {
+    // Arrange — tiny timeout so the test completes quickly
+    var f = Fixture.Create(
+      timeout: TimeSpan.FromMilliseconds(50),
+      pollInterval: TimeSpan.FromMilliseconds(1),
+      responses: Enumerable.Repeat(EmptyContainersJson(), 200).ToArray());
+
+    // Act
+    var result = await f.Sut.GetAllContainerHostPortsAsync("my-resource", CancellationToken.None);
+
+    // Assert
+    Assert.Null(result);
+  }
+
+  [Fact]
+  public async Task GetAllContainerHostPortsAsync_WhenHttpRequestFails_RetriesAndEventuallyReturnsPorts()
+  {
+    // Arrange — null signals the handler to throw HttpRequestException
+    var f = Fixture.Create(
+      null,
+      ContainerJson("abc", ["/my-resource"], [8080u]));
+
+    // Act
+    var result = await f.Sut.GetAllContainerHostPortsAsync("my-resource", CancellationToken.None);
+
+    // Assert
+    Assert.Equal([8080u], result);
+  }
+
+  [Fact]
+  public async Task GetAllContainerHostPortsAsync_WhenNameHasLeadingSlash_MatchesResourceName()
+  {
+    // Arrange
+    var f = Fixture.Create(
+      EmptyContainersJson(),
+      ContainerJson("abc", ["/my-resource"], [8080u]));
+
+    // Act
+    var result = await f.Sut.GetAllContainerHostPortsAsync("my-resource", CancellationToken.None);
+
+    // Assert
+    Assert.NotNull(result);
+  }
+
+  [Fact]
+  public async Task GetAllContainerHostPortsAsync_WhenNameMatchesByPrefix_ReturnsPorts()
+  {
+    // Arrange — Docker name includes an instance suffix after the resource name
+    var f = Fixture.Create(
+      EmptyContainersJson(),
+      ContainerJson("abc", ["/my-resource-abc123def456"], [8080u]));
+
+    // Act
+    var result = await f.Sut.GetAllContainerHostPortsAsync("my-resource", CancellationToken.None);
+
+    // Assert
+    Assert.NotNull(result);
+  }
+
+  [Fact]
+  public async Task GetAllContainerHostPortsAsync_WhenNameMatchingIsCaseInsensitive_ReturnsPorts()
+  {
+    // Arrange
+    var f = Fixture.Create(
+      EmptyContainersJson(),
+      ContainerJson("abc", ["/MY-RESOURCE"], [8080u]));
+
+    // Act
+    var result = await f.Sut.GetAllContainerHostPortsAsync("my-resource", CancellationToken.None);
+
+    // Assert
+    Assert.NotNull(result);
+  }
+
+  [Fact]
+  public async Task GetAllContainerHostPortsAsync_WhenContainerHasMultiplePorts_ReturnsAllPorts()
+  {
+    // Arrange
+    var f = Fixture.Create(
+      EmptyContainersJson(),
+      ContainerJson("abc", ["/my-resource"], [8080u, 5432u, 443u]));
+
+    // Act
+    var result = await f.Sut.GetAllContainerHostPortsAsync("my-resource", CancellationToken.None);
+
+    // Assert
+    Assert.NotNull(result);
+    Assert.Equal(3, result.Count);
+    Assert.Contains(8080u, result);
+    Assert.Contains(5432u, result);
+    Assert.Contains(443u, result);
+  }
+
+  [Fact]
+  public async Task GetAllContainerHostPortsAsync_WhenContainerHasDuplicatePorts_DeduplicatesPorts()
+  {
+    // Arrange
+    var f = Fixture.Create(
+      EmptyContainersJson(),
+      ContainerJson("abc", ["/my-resource"], [8080u, 8080u]));
+
+    // Act
+    var result = await f.Sut.GetAllContainerHostPortsAsync("my-resource", CancellationToken.None);
+
+    // Assert
+    Assert.Equal([8080u], result);
+  }
+
+  [Fact]
+  public async Task GetAllContainerHostPortsAsync_WhenContainerNameDoesNotMatch_TimesOutAndReturnsNull()
+  {
+    // Arrange
+    var f = Fixture.Create(
+      timeout: TimeSpan.FromMilliseconds(50),
+      pollInterval: TimeSpan.FromMilliseconds(1),
+      responses: Enumerable.Repeat(ContainerJson("abc", ["/other-resource"], [8080u]), 200).ToArray());
+
+    // Act
+    var result = await f.Sut.GetAllContainerHostPortsAsync("my-resource", CancellationToken.None);
+
+    // Assert
+    Assert.Null(result);
+  }
+
+  [Fact]
+  public async Task GetAllContainerHostPortsAsync_WhenContainerHasZeroPorts_SkipsContainerAndTimesOut()
+  {
+    // Arrange
+    var f = Fixture.Create(
+      timeout: TimeSpan.FromMilliseconds(50),
+      pollInterval: TimeSpan.FromMilliseconds(1),
+      responses: Enumerable.Repeat(ContainerJsonNoPorts("abc", "/my-resource"), 200).ToArray());
+
+    // Act
+    var result = await f.Sut.GetAllContainerHostPortsAsync("my-resource", CancellationToken.None);
+
+    // Assert
+    Assert.Null(result);
+  }
+
+  private static string ContainerJson(string id, string[] names, uint[] publicPorts)
+  {
+    var namesJson = string.Join(",", names.Select(n => $"\"{n}\""));
+    var portsJson = string.Join(",", publicPorts.Select(p => $"{{\"PublicPort\":{p}}}"));
+
+    return $"[{{\"Id\":\"{id}\",\"Names\":[{namesJson}],\"Ports\":[{portsJson}]}}]";
+  }
+
+  private static string ContainerJsonNoPorts(string id, string name) =>
+    $"[{{\"Id\":\"{id}\",\"Names\":[\"{name}\"],\"Ports\":[]}}]";
+
+  private static string EmptyContainersJson() => "[]";
+
+  private sealed record Fixture(DockerApiClient Sut)
+  {
+    public static Fixture Create(params string?[] responses) =>
+      Create(timeout: null, pollInterval: null, responses: responses);
+
+    public static Fixture Create(
+      TimeSpan? timeout = null,
+      TimeSpan? pollInterval = null,
+      params string?[] responses)
+    {
+      var handler = new FakeHttpHandler(responses);
+      var httpClient = new HttpClient(handler) { BaseAddress = new Uri("http://docker/") };
+
+      var configValues = new Dictionary<string, string?>
+      {
+        ["RemoteContainers:ContainerStartTimeout"] = (timeout ?? TimeSpan.FromSeconds(5)).ToString(),
+        ["RemoteContainers:ContainerPollInterval"] = (pollInterval ?? TimeSpan.FromMilliseconds(5)).ToString(),
+      };
+      var config = new ConfigurationBuilder().AddInMemoryCollection(configValues).Build();
+      var appConfig = new AppConfiguration(config, "user", "/home/user", new Hashtable());
+      var logger = Substitute.For<ILogger<DockerApiClient>>();
+
+      return new Fixture(new DockerApiClient(logger, httpClient, appConfig));
+    }
+  }
+
+  private sealed class FakeHttpHandler(params string?[] responses) : HttpMessageHandler
+  {
+    private readonly Queue<string?> _responses = new(responses);
+
+    protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
+    {
+      var response = _responses.Count > 0 ? _responses.Dequeue() : "[]";
+
+      if (response is null)
+      {
+        throw new HttpRequestException("Simulated network error");
+      }
+
+      return Task.FromResult(new HttpResponseMessage(HttpStatusCode.OK)
+      {
+        Content = new StringContent(response, Encoding.UTF8, "application/json"),
+      });
+    }
+  }
+}
diff --git a/test/RemoteContainers.Aspire.UnitTest/DockerCertificateTests.cs b/test/RemoteContainers.Aspire.UnitTest/DockerCertificateTests.cs
new file mode 100644
index 0000000..468ad02
--- /dev/null
+++ b/test/RemoteContainers.Aspire.UnitTest/DockerCertificateTests.cs
@@ -0,0 +1,227 @@
+using System.Collections;
+using System.Security.Cryptography;
+using System.Security.Cryptography.X509Certificates;
+using Hj.RemoteContainers.Aspire.Abstractions;
+using Hj.RemoteContainers.Aspire.Docker;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.Logging;
+
+namespace Hj.RemoteContainers.Aspire.UnitTest;
+
+public sealed class DockerCertificateTests
+{
+  [Fact]
+  public void TryGetCertificate_WhenTlsNotEnabled_ReturnsFalse()
+  {
+    // Arrange
+    var f = Fixture.Create(tlsEnabled: false);
+
+    // Act
+    var result = f.Sut.TryGetCertificate(out var caCert, out var clientCert);
+
+    // Assert
+    Assert.False(result);
+    Assert.Null(caCert);
+    Assert.Null(clientCert);
+  }
+
+  [Fact]
+  public void TryGetCertificate_WhenCaCertFileNotFound_ReturnsFalse()
+  {
+    // Arrange
+    var f = Fixture.Create();
+    f.FileSystem.FileExists(Arg.Is<string>(p => p.EndsWith("ca.pem"))).Returns(false);
+
+    // Act
+    var result = f.Sut.TryGetCertificate(out var caCert, out var clientCert);
+
+    // Assert
+    Assert.False(result);
+    Assert.Null(caCert);
+    Assert.Null(clientCert);
+  }
+
+  [Fact]
+  public void TryGetCertificate_WhenCaCertFileEmpty_ReturnsFalse()
+  {
+    // Arrange
+    var f = Fixture.Create();
+    f.FileSystem.FileExists(Arg.Is<string>(p => p.EndsWith("ca.pem"))).Returns(true);
+    f.FileSystem.ReadAllText(Arg.Is<string>(p => p.EndsWith("ca.pem"))).Returns(string.Empty);
+
+    // Act
+    var result = f.Sut.TryGetCertificate(out var caCert, out var clientCert);
+
+    // Assert
+    Assert.False(result);
+    Assert.Null(caCert);
+    Assert.Null(clientCert);
+  }
+
+  [Fact]
+  public void TryGetCertificate_WhenClientCertFileNotFound_ReturnsFalse()
+  {
+    // Arrange
+    var f = Fixture.Create();
+    var (caCertPem, _) = GenerateTestCertificate("CN=ca");
+    f.FileSystem.FileExists(Arg.Is<string>(p => p.EndsWith("ca.pem"))).Returns(true);
+    f.FileSystem.ReadAllText(Arg.Is<string>(p => p.EndsWith("ca.pem"))).Returns(caCertPem);
+    f.FileSystem.FileExists(Arg.Is<string>(p => p.EndsWith("cert.pem"))).Returns(false);
+
+    // Act
+    var result = f.Sut.TryGetCertificate(out var caCert, out var clientCert);
+
+    // Assert
+    Assert.False(result);
+    Assert.Null(caCert);
+    Assert.Null(clientCert);
+  }
+
+  [Fact]
+  public void TryGetCertificate_WhenClientCertFileEmpty_ReturnsFalse()
+  {
+    // Arrange
+    var f = Fixture.Create();
+    var (caCertPem, _) = GenerateTestCertificate("CN=ca");
+    f.FileSystem.FileExists(Arg.Is<string>(p => p.EndsWith("ca.pem"))).Returns(true);
+    f.FileSystem.ReadAllText(Arg.Is<string>(p => p.EndsWith("ca.pem"))).Returns(caCertPem);
+    f.FileSystem.FileExists(Arg.Is<string>(p => p.EndsWith("cert.pem"))).Returns(true);
+    f.FileSystem.ReadAllText(Arg.Is<string>(p => p.EndsWith("cert.pem"))).Returns(string.Empty);
+    f.FileSystem.FileExists(Arg.Is<string>(p => p.EndsWith("key.pem"))).Returns(true);
+
+    // Act
+    var result = f.Sut.TryGetCertificate(out var caCert, out var clientCert);
+
+    // Assert
+    Assert.False(result);
+    Assert.Null(caCert);
+    Assert.Null(clientCert);
+  }
+
+  [Fact]
+  public void TryGetCertificate_WhenAllCertsPresent_ReturnsTrueWithCertificates()
+  {
+    // Arrange
+    var f = Fixture.Create();
+    var (caCertPem, _) = GenerateTestCertificate("CN=ca");
+    var (clientCertPem, clientKeyPem) = GenerateTestCertificate("CN=client");
+    SetupAllCertFiles(f.FileSystem, caCertPem, clientCertPem, clientKeyPem);
+
+    // Act
+    var result = f.Sut.TryGetCertificate(out var caCert, out var clientCert);
+
+    // Assert
+    using (caCert)
+    using (clientCert)
+    {
+      Assert.True(result);
+      Assert.NotNull(caCert);
+      Assert.NotNull(clientCert);
+    }
+  }
+
+  [Fact]
+  public void TryGetCertificate_WhenCalledTwice_ReturnsDifferentCertificateInstances()
+  {
+    // Arrange
+    var f = Fixture.Create();
+    var (caCertPem, _) = GenerateTestCertificate("CN=ca");
+    var (clientCertPem, clientKeyPem) = GenerateTestCertificate("CN=client");
+    SetupAllCertFiles(f.FileSystem, caCertPem, clientCertPem, clientKeyPem);
+    f.Sut.TryGetCertificate(out var firstCaCert, out var firstClientCert);
+
+    // Act
+    var result = f.Sut.TryGetCertificate(out var secondCaCert, out var secondClientCert);
+
+    // Assert
+    using (firstCaCert)
+    using (firstClientCert)
+    using (secondCaCert)
+    using (secondClientCert)
+    {
+      Assert.True(result);
+      Assert.NotSame(firstCaCert, secondCaCert);
+      Assert.NotSame(firstClientCert, secondClientCert);
+    }
+  }
+
+  [Fact]
+  public void TryGetCertificate_WhenCalledTwice_DoesNotReloadCertsFromFileSystem()
+  {
+    // Arrange
+    var f = Fixture.Create();
+    var (caCertPem, _) = GenerateTestCertificate("CN=ca");
+    var (clientCertPem, clientKeyPem) = GenerateTestCertificate("CN=client");
+    SetupAllCertFiles(f.FileSystem, caCertPem, clientCertPem, clientKeyPem);
+    f.Sut.TryGetCertificate(out var firstCaCert, out var firstClientCert);
+    firstCaCert?.Dispose();
+    firstClientCert?.Dispose();
+
+    // Act
+    f.Sut.TryGetCertificate(out var secondCaCert, out var secondClientCert);
+    secondCaCert?.Dispose();
+    secondClientCert?.Dispose();
+
+    // Assert
+    f.FileSystem.Received(1).ReadAllText(Arg.Is<string>(p => p.EndsWith("ca.pem")));
+    f.FileSystem.Received(1).ReadAllText(Arg.Is<string>(p => p.EndsWith("cert.pem")));
+  }
+
+  [Fact]
+  public void Dispose_WhenCalledTwice_DoesNotThrow()
+  {
+    // Arrange
+    var f = Fixture.Create();
+
+    // Act
+    var exception = Record.Exception(() =>
+    {
+      f.Sut.Dispose();
+      f.Sut.Dispose();
+    });
+
+    // Assert
+    Assert.Null(exception);
+  }
+
+  private static (string CertPem, string KeyPem) GenerateTestCertificate(string subject)
+  {
+    using var key = ECDsa.Create(ECCurve.NamedCurves.nistP256);
+    var request = new CertificateRequest(subject, key, HashAlgorithmName.SHA256);
+    using var cert = request.CreateSelfSigned(DateTimeOffset.UtcNow.AddDays(-1), DateTimeOffset.UtcNow.AddDays(1));
+
+    return (cert.ExportCertificatePem(), key.ExportECPrivateKeyPem());
+  }
+
+  private static void SetupAllCertFiles(IFileSystem fileSystem, string caCertPem, string clientCertPem, string clientKeyPem)
+  {
+    fileSystem.FileExists(Arg.Is<string>(p => p.EndsWith("ca.pem"))).Returns(true);
+    fileSystem.ReadAllText(Arg.Is<string>(p => p.EndsWith("ca.pem"))).Returns(caCertPem);
+    fileSystem.FileExists(Arg.Is<string>(p => p.EndsWith("cert.pem"))).Returns(true);
+    fileSystem.ReadAllText(Arg.Is<string>(p => p.EndsWith("cert.pem"))).Returns(clientCertPem);
+    fileSystem.FileExists(Arg.Is<string>(p => p.EndsWith("key.pem"))).Returns(true);
+    fileSystem.ReadAllText(Arg.Is<string>(p => p.EndsWith("key.pem"))).Returns(clientKeyPem);
+  }
+
+  private sealed record Fixture(DockerCertificate Sut, IFileSystem FileSystem)
+  {
+    public static Fixture Create(bool tlsEnabled = true)
+    {
+      var fileSystem = Substitute.For<IFileSystem>();
+      var logger = Substitute.For<ILogger<DockerCertificate>>();
+
+      var envVars = new Hashtable();
+      if (tlsEnabled)
+      {
+        envVars["DOCKER_TLS_VERIFY"] = "1";
+        envVars["DOCKER_CERT_PATH"] = "/certs";
+        envVars["DOCKER_HOST"] = "tcp://remote:2376";
+      }
+
+      var config = new ConfigurationBuilder().Build();
+      var appConfig = new AppConfiguration(config, "user", "/home/user", envVars);
+
+      return new Fixture(new DockerCertificate(logger, appConfig, fileSystem), fileSystem);
+    }
+  }
+}
diff --git a/test/RemoteContainers.Aspire.UnitTest/DockerMessageHandlerTests.cs b/test/RemoteContainers.Aspire.UnitTest/DockerMessageHandlerTests.cs
new file mode 100644
index 0000000..c4c5dd3
--- /dev/null
+++ b/test/RemoteContainers.Aspire.UnitTest/DockerMessageHandlerTests.cs
@@ -0,0 +1,184 @@
+using System.Net.Security;
+using System.Security.Cryptography;
+using System.Security.Cryptography.X509Certificates;
+using Hj.RemoteContainers.Aspire.Docker;
+
+namespace Hj.RemoteContainers.Aspire.UnitTest;
+
+public sealed class DockerMessageHandlerTests
+{
+  [Fact]
+  public void Init_WhenTlsNotEnabled_ReturnsHandlerWithNoClientCertificates()
+  {
+    // Arrange
+    var f = Fixture.Create(withCertificate: false);
+
+    // Act
+    f.Sut.Init();
+
+    // Assert
+    Assert.Empty(f.Sut.ClientCertificates);
+  }
+
+  [Fact]
+  public void Init_WhenTlsNotEnabled_ReturnsHandlerWithNoValidationCallback()
+  {
+    // Arrange
+    var f = Fixture.Create(withCertificate: false);
+
+    // Act
+    f.Sut.Init();
+
+    // Assert
+    Assert.Null(f.Sut.ServerCertificateCustomValidationCallback);
+  }
+
+  [Fact]
+  public void Init_WhenCertificateConfigured_AddsClientCertificate()
+  {
+    // Arrange
+    using var caCert = GenerateTestCertificate("CN=ca");
+    using var clientCert = GenerateTestCertificate("CN=client");
+    var f = Fixture.Create(withCertificate: true, caCert, clientCert);
+
+    // Act
+    f.Sut.Init();
+
+    // Assert
+    Assert.Single(f.Sut.ClientCertificates);
+  }
+
+  [Fact]
+  public void Init_WhenCertificateConfigured_SetsServerCertificateCustomValidationCallback()
+  {
+    // Arrange
+    using var caCert = GenerateTestCertificate("CN=ca");
+    using var clientCert = GenerateTestCertificate("CN=client");
+    var f = Fixture.Create(withCertificate: true, caCert, clientCert);
+
+    // Act
+    f.Sut.Init();
+
+    // Assert
+    Assert.NotNull(f.Sut.ServerCertificateCustomValidationCallback);
+  }
+
+  [Fact]
+  public void Init_ReturnsThisInstance()
+  {
+    // Arrange
+    var f = Fixture.Create(withCertificate: false);
+
+    // Act
+    var result = f.Sut.Init();
+
+    // Assert
+    Assert.Same(f.Sut, result);
+  }
+
+  [Fact]
+  public void ServerCertificateValidation_WhenServerCertIsNull_ReturnsFalse()
+  {
+    // Arrange
+    using var caCert = GenerateTestCertificate("CN=ca");
+    using var clientCert = GenerateTestCertificate("CN=client");
+    var f = Fixture.Create(withCertificate: true, caCert, clientCert);
+    f.Sut.Init();
+    var callback = f.Sut.ServerCertificateCustomValidationCallback!;
+    using var chain = new X509Chain();
+
+    // Act
+    var result = callback(null!, null, chain, SslPolicyErrors.None);
+
+    // Assert
+    Assert.False(result);
+  }
+
+  [Fact]
+  public void ServerCertificateValidation_WhenChainIsNull_ReturnsFalse()
+  {
+    // Arrange
+    using var caCert = GenerateTestCertificate("CN=ca");
+    using var clientCert = GenerateTestCertificate("CN=client");
+    var f = Fixture.Create(withCertificate: true, caCert, clientCert);
+    f.Sut.Init();
+    var callback = f.Sut.ServerCertificateCustomValidationCallback!;
+
+    // Act
+    var result = callback(null!, caCert, null, SslPolicyErrors.None);
+
+    // Assert
+    Assert.False(result);
+  }
+
+  [Fact]
+  public void ServerCertificateValidation_WhenChainBuildSucceeds_ReturnsTrue()
+  {
+    // Arrange — use the same self-signed cert as both CA and server cert
+    using var cert = GenerateTestCertificate("CN=server");
+    var f = Fixture.Create(withCertificate: true, cert, cert);
+    f.Sut.Init();
+    var callback = f.Sut.ServerCertificateCustomValidationCallback!;
+    using var serverCert = X509Certificate2.CreateFromPem(cert.ExportCertificatePem());
+    using var chain = new X509Chain();
+
+    // Act
+    var result = callback(null!, serverCert, chain, SslPolicyErrors.None);
+
+    // Assert
+    Assert.True(result);
+  }
+
+  [Fact]
+  public void Dispose_WhenCalledTwice_DoesNotThrow()
+  {
+    // Arrange
+    var f = Fixture.Create(withCertificate: false);
+
+    // Act & Assert
+    var exception = Record.Exception(() =>
+    {
+      f.Sut.Dispose();
+      f.Sut.Dispose();
+    });
+    Assert.Null(exception);
+  }
+
+  private static X509Certificate2 GenerateTestCertificate(string subject)
+  {
+    using var key = ECDsa.Create(ECCurve.NamedCurves.nistP256);
+    var request = new CertificateRequest(subject, key, HashAlgorithmName.SHA256);
+    return request.CreateSelfSigned(DateTimeOffset.UtcNow.AddDays(-1), DateTimeOffset.UtcNow.AddDays(1));
+  }
+
+  private sealed record Fixture(DockerMessageHandler Sut, IDockerCertificate Certificate)
+  {
+    public static Fixture Create(bool withCertificate, X509Certificate2? caCert = null, X509Certificate2? clientCert = null)
+    {
+      var certificate = Substitute.For<IDockerCertificate>();
+
+      if (withCertificate && caCert is not null && clientCert is not null)
+      {
+        var capturedCaCert = caCert;
+        var capturedClientCert = clientCert;
+
+        certificate
+          .TryGetCertificate(out Arg.Any<X509Certificate2?>(), out Arg.Any<X509Certificate2?>())
+          .Returns(x =>
+          {
+            x[0] = capturedCaCert;
+            x[1] = capturedClientCert;
+            return true;
+          });
+      }
+      else
+      {
+        certificate
+          .TryGetCertificate(out Arg.Any<X509Certificate2?>(), out Arg.Any<X509Certificate2?>())
+          .Returns(false);
+      }
+
+      return new Fixture(new DockerMessageHandler(certificate), certificate);
+    }
+  }
+}
diff --git a/test/RemoteContainers.Aspire.UnitTest/RemoteContainers.Aspire.UnitTest.csproj b/test/RemoteContainers.Aspire.UnitTest/RemoteContainers.Aspire.UnitTest.csproj
index fd4eda3..514e68d 100644
--- a/test/RemoteContainers.Aspire.UnitTest/RemoteContainers.Aspire.UnitTest.csproj
+++ b/test/RemoteContainers.Aspire.UnitTest/RemoteContainers.Aspire.UnitTest.csproj
@@ -3,7 +3,10 @@
   <PropertyGroup>
     <TargetFramework>net10.0</TargetFramework>
     <IsPackable>false</IsPackable>
-    <GenerateDocumentationFile>false</GenerateDocumentationFile>
+    <EnableNETAnalyzers>true</EnableNETAnalyzers>
+    <AnalysisMode>Recommended</AnalysisMode>
+    <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
   </PropertyGroup>
 
   <ItemGroup>
@@ -12,6 +15,11 @@
   </ItemGroup>
 
   <ItemGroup>
+    <ProjectReference Include="..\..\src\RemoteContainers.Aspire\RemoteContainers.Aspire.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Aspire.Hosting" />
     <PackageReference Include="NSubstitute" />
     <PackageReference Include="Microsoft.NET.Test.Sdk" />
     <PackageReference Include="xunit" />
diff --git a/test/RemoteContainers.Aspire.UnitTest/SshTunnelLifecycleHookTests.cs b/test/RemoteContainers.Aspire.UnitTest/SshTunnelLifecycleHookTests.cs
new file mode 100644
index 0000000..a6b3fbf
--- /dev/null
+++ b/test/RemoteContainers.Aspire.UnitTest/SshTunnelLifecycleHookTests.cs
@@ -0,0 +1,228 @@
+using Aspire.Hosting;
+using Aspire.Hosting.ApplicationModel;
+using Aspire.Hosting.Eventing;
+using Hj.RemoteContainers.Aspire.Ssh;
+using Microsoft.Extensions.Logging;
+using NSubstitute.ExceptionExtensions;
+
+namespace Hj.RemoteContainers.Aspire.UnitTest;
+
+public sealed class SshTunnelLifecycleHookTests
+{
+  private static readonly DistributedApplicationExecutionContext ExecutionContext = new(DistributedApplicationOperation.Run);
+
+  [Fact]
+  public async Task SubscribeAsync_RegistersAllThreeEventHandlers()
+  {
+    // Arrange
+    var f = Fixture.Create();
+
+    // Act
+    await f.Sut.SubscribeAsync(f.Eventing, ExecutionContext, CancellationToken.None);
+
+    // Assert
+    f.Eventing.Received(1).Subscribe(Arg.Any<Func<ResourceEndpointsAllocatedEvent, CancellationToken, Task>>());
+    f.Eventing.Received(1).Subscribe(Arg.Any<Func<ResourceReadyEvent, CancellationToken, Task>>());
+    f.Eventing.Received(1).Subscribe(Arg.Any<Func<ResourceStoppedEvent, CancellationToken, Task>>());
+  }
+
+  [Fact]
+  public async Task SetUpTunnel_ContainerResource_CallsAddAllContainerPortForwards()
+  {
+    // Arrange
+    var f = Fixture.Create();
+    var handler = f.CaptureHandler<ResourceEndpointsAllocatedEvent>();
+    await f.Sut.SubscribeAsync(f.Eventing, ExecutionContext, CancellationToken.None);
+
+    // Act
+    await handler(new ResourceEndpointsAllocatedEvent(CreateContainerResource("my-resource"), Substitute.For<IServiceProvider>()), CancellationToken.None);
+
+    // Assert
+    await f.TunnelManager.Received(1).AddAllContainerPortForwardsAsync("my-resource", Arg.Any<CancellationToken>());
+  }
+
+  [Fact]
+  public async Task SetUpTunnel_NonContainerResource_DoesNotCallTunnelManager()
+  {
+    // Arrange
+    var f = Fixture.Create();
+    var handler = f.CaptureHandler<ResourceEndpointsAllocatedEvent>();
+    await f.Sut.SubscribeAsync(f.Eventing, ExecutionContext, CancellationToken.None);
+
+    // Act
+    await handler(new ResourceEndpointsAllocatedEvent(CreateNonContainerResource("my-resource"), Substitute.For<IServiceProvider>()), CancellationToken.None);
+
+    // Assert
+    await f.TunnelManager.DidNotReceive().AddAllContainerPortForwardsAsync(Arg.Any<string>(), Arg.Any<CancellationToken>());
+  }
+
+  [Fact]
+  public async Task SetUpTunnel_WhenManagerThrows_ExceptionIsSwallowed()
+  {
+    // Arrange
+    var f = Fixture.Create();
+    var handler = f.CaptureHandler<ResourceEndpointsAllocatedEvent>();
+    f.TunnelManager.AddAllContainerPortForwardsAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
+        .ThrowsAsync(new InvalidOperationException("boom"));
+    await f.Sut.SubscribeAsync(f.Eventing, ExecutionContext, CancellationToken.None);
+
+    // Act
+    var exception = await Record.ExceptionAsync(
+        () => handler(new ResourceEndpointsAllocatedEvent(CreateContainerResource("my-resource"), Substitute.For<IServiceProvider>()), CancellationToken.None));
+
+    // Assert
+    Assert.Null(exception);
+  }
+
+  [Fact]
+  public async Task SetUpTunnelOnReady_ContainerResource_RemovesOldTunnelsThenAddsNew()
+  {
+    // Arrange
+    var f = Fixture.Create();
+    var handler = f.CaptureHandler<ResourceReadyEvent>();
+    await f.Sut.SubscribeAsync(f.Eventing, ExecutionContext, CancellationToken.None);
+
+    // Act
+    await handler(new ResourceReadyEvent(CreateContainerResource("my-resource"), Substitute.For<IServiceProvider>()), CancellationToken.None);
+
+    // Assert
+    Received.InOrder(() =>
+    {
+      f.TunnelManager.RemoveAllContainerPortForwards("my-resource");
+      _ = f.TunnelManager.AddAllContainerPortForwardsAsync("my-resource", Arg.Any<CancellationToken>());
+    });
+  }
+
+  [Fact]
+  public async Task SetUpTunnelOnReady_NonContainerResource_DoesNotCallTunnelManager()
+  {
+    // Arrange
+    var f = Fixture.Create();
+    var handler = f.CaptureHandler<ResourceReadyEvent>();
+    await f.Sut.SubscribeAsync(f.Eventing, ExecutionContext, CancellationToken.None);
+
+    // Act
+    await handler(new ResourceReadyEvent(CreateNonContainerResource("my-resource"), Substitute.For<IServiceProvider>()), CancellationToken.None);
+
+    // Assert
+    f.TunnelManager.DidNotReceive().RemoveAllContainerPortForwards(Arg.Any<string>());
+    await f.TunnelManager.DidNotReceive().AddAllContainerPortForwardsAsync(Arg.Any<string>(), Arg.Any<CancellationToken>());
+  }
+
+  [Fact]
+  public async Task SetUpTunnelOnReady_WhenManagerThrows_ExceptionIsSwallowed()
+  {
+    // Arrange
+    var f = Fixture.Create();
+    var handler = f.CaptureHandler<ResourceReadyEvent>();
+    f.TunnelManager.AddAllContainerPortForwardsAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
+        .ThrowsAsync(new InvalidOperationException("boom"));
+    await f.Sut.SubscribeAsync(f.Eventing, ExecutionContext, CancellationToken.None);
+
+    // Act
+    var exception = await Record.ExceptionAsync(
+        () => handler(new ResourceReadyEvent(CreateContainerResource("my-resource"), Substitute.For<IServiceProvider>()), CancellationToken.None));
+
+    // Assert
+    Assert.Null(exception);
+  }
+
+  [Fact]
+  public async Task TearDownTunnel_ContainerResource_CallsRemoveAllContainerPortForwards()
+  {
+    // Arrange
+    var f = Fixture.Create();
+    var handler = f.CaptureHandler<ResourceStoppedEvent>();
+    await f.Sut.SubscribeAsync(f.Eventing, ExecutionContext, CancellationToken.None);
+
+    // Act
+    await handler(CreateResourceStoppedEvent(CreateContainerResource("my-resource")), CancellationToken.None);
+
+    // Assert
+    f.TunnelManager.Received(1).RemoveAllContainerPortForwards("my-resource");
+  }
+
+  [Fact]
+  public async Task TearDownTunnel_NonContainerResource_DoesNotCallTunnelManager()
+  {
+    // Arrange
+    var f = Fixture.Create();
+    var handler = f.CaptureHandler<ResourceStoppedEvent>();
+    await f.Sut.SubscribeAsync(f.Eventing, ExecutionContext, CancellationToken.None);
+
+    // Act
+    await handler(CreateResourceStoppedEvent(CreateNonContainerResource("my-resource")), CancellationToken.None);
+
+    // Assert
+    f.TunnelManager.DidNotReceive().RemoveAllContainerPortForwards(Arg.Any<string>());
+  }
+
+  [Fact]
+  public async Task TearDownTunnel_WhenManagerThrows_ExceptionIsSwallowed()
+  {
+    // Arrange
+    var f = Fixture.Create();
+    var handler = f.CaptureHandler<ResourceStoppedEvent>();
+    f.TunnelManager.When(m => m.RemoveAllContainerPortForwards(Arg.Any<string>()))
+        .Throw(new InvalidOperationException("boom"));
+    await f.Sut.SubscribeAsync(f.Eventing, ExecutionContext, CancellationToken.None);
+
+    // Act
+    var exception = await Record.ExceptionAsync(
+        () => handler(CreateResourceStoppedEvent(CreateContainerResource("my-resource")), CancellationToken.None));
+
+    // Assert
+    Assert.Null(exception);
+  }
+
+  private static TestResource CreateContainerResource(string name)
+  {
+    var resource = new TestResource(name);
+    resource.Annotations.Add(new ContainerImageAnnotation { Image = "test-image" });
+
+    return resource;
+  }
+
+  private static TestResource CreateNonContainerResource(string name) => new TestResource(name);
+
+  private static ResourceStoppedEvent CreateResourceStoppedEvent(IResource resource)
+  {
+    var snapshot = new CustomResourceSnapshot { ResourceType = "Container", Properties = [] };
+    var resourceEvent = new ResourceEvent(resource, "resource-id", snapshot);
+
+    return new ResourceStoppedEvent(resource, Substitute.For<IServiceProvider>(), resourceEvent);
+  }
+
+  private sealed class TestResource(string name) : IResource
+  {
+    public string Name { get; } = name;
+
+    public ResourceAnnotationCollection Annotations { get; } = new();
+  }
+
+  private sealed record Fixture(
+      SshTunnelLifecycleHook Sut,
+      ISshTunnelManager TunnelManager,
+      IDistributedApplicationEventing Eventing)
+  {
+    public static Fixture Create()
+    {
+      var tunnelManager = Substitute.For<ISshTunnelManager>();
+      var logger = Substitute.For<ILogger<SshTunnelLifecycleHook>>();
+
+      return new Fixture(
+          new SshTunnelLifecycleHook(logger, tunnelManager),
+          tunnelManager,
+          Substitute.For<IDistributedApplicationEventing>());
+    }
+
+    public Func<T, CancellationToken, Task> CaptureHandler<T>()
+        where T : IDistributedApplicationEvent
+    {
+      Func<T, CancellationToken, Task>? handler = null;
+      Eventing.Subscribe(Arg.Do<Func<T, CancellationToken, Task>>(h => handler = h));
+
+      return (evt, ct) => handler!(evt, ct);
+    }
+  }
+}
diff --git a/test/RemoteContainers.Aspire.UnitTest/SshTunnelManagerTests.cs b/test/RemoteContainers.Aspire.UnitTest/SshTunnelManagerTests.cs
new file mode 100644
index 0000000..c67c4b3
--- /dev/null
+++ b/test/RemoteContainers.Aspire.UnitTest/SshTunnelManagerTests.cs
@@ -0,0 +1,235 @@
+using Hj.RemoteContainers.Aspire.Abstractions;
+using Hj.RemoteContainers.Aspire.Docker;
+using Hj.RemoteContainers.Aspire.Ssh;
+using Microsoft.Extensions.Logging;
+
+namespace Hj.RemoteContainers.Aspire.UnitTest;
+
+public sealed class SshTunnelManagerTests
+{
+  [Fact]
+  public async Task AddAllContainerPortForwardsAsync_WhenNotConnected_DoesNotForwardAnyPorts()
+  {
+    // Arrange
+    var f = Fixture.Create(connected: false);
+
+    // Act
+    await f.Sut.AddAllContainerPortForwardsAsync("my-resource", CancellationToken.None);
+
+    // Assert
+    f.SshConnection.DidNotReceive().ForwardPort(Arg.Any<uint>());
+  }
+
+  [Fact]
+  public async Task AddAllContainerPortForwardsAsync_WhenDockerApiReturnsNull_DoesNotForwardAnyPorts()
+  {
+    // Arrange
+    var f = Fixture.Create();
+    f.DockerApiClient
+      .GetAllContainerHostPortsAsync("my-resource", Arg.Any<CancellationToken>())
+      .Returns(Task.FromResult<List<uint>?>(null));
+
+    // Act
+    await f.Sut.AddAllContainerPortForwardsAsync("my-resource", CancellationToken.None);
+
+    // Assert
+    f.SshConnection.DidNotReceive().ForwardPort(Arg.Any<uint>());
+  }
+
+  [Fact]
+  public async Task AddAllContainerPortForwardsAsync_WhenDockerApiReturnsEmptyList_DoesNotForwardAnyPorts()
+  {
+    // Arrange
+    var f = Fixture.Create();
+    f.DockerApiClient
+      .GetAllContainerHostPortsAsync("my-resource", Arg.Any<CancellationToken>())
+      .Returns(Task.FromResult<List<uint>?>([]) );
+
+    // Act
+    await f.Sut.AddAllContainerPortForwardsAsync("my-resource", CancellationToken.None);
+
+    // Assert
+    f.SshConnection.DidNotReceive().ForwardPort(Arg.Any<uint>());
+  }
+
+  [Fact]
+  public async Task AddAllContainerPortForwardsAsync_WhenPortsAvailable_ForwardsEachPort()
+  {
+    // Arrange
+    var f = Fixture.Create();
+    var port1 = CreateForwardedPort(8080u);
+    var port2 = CreateForwardedPort(5432u);
+    f.SshConnection.ForwardPort(8080u).Returns(port1);
+    f.SshConnection.ForwardPort(5432u).Returns(port2);
+    f.DockerApiClient
+      .GetAllContainerHostPortsAsync("my-resource", Arg.Any<CancellationToken>())
+      .Returns(Task.FromResult<List<uint>?>([8080u, 5432u]));
+
+    // Act
+    await f.Sut.AddAllContainerPortForwardsAsync("my-resource", CancellationToken.None);
+
+    // Assert
+    f.SshConnection.Received(1).ForwardPort(8080u);
+    f.SshConnection.Received(1).ForwardPort(5432u);
+  }
+
+  [Fact]
+  public async Task AddAllContainerPortForwardsAsync_WhenCalledMultipleTimes_AccumulatesPorts()
+  {
+    // Arrange
+    var f = Fixture.Create();
+    f.SshConnection.ForwardPort(Arg.Any<uint>()).Returns(info => CreateForwardedPort(info.Arg<uint>()));
+    f.DockerApiClient
+      .GetAllContainerHostPortsAsync("my-resource", Arg.Any<CancellationToken>())
+      .Returns(
+        Task.FromResult<List<uint>?>([8080u]),
+        Task.FromResult<List<uint>?>([5432u]));
+
+    // Act
+    await f.Sut.AddAllContainerPortForwardsAsync("my-resource", CancellationToken.None);
+    await f.Sut.AddAllContainerPortForwardsAsync("my-resource", CancellationToken.None);
+
+    // Assert
+    f.SshConnection.Received(2).ForwardPort(Arg.Any<uint>());
+  }
+
+  [Fact]
+  public async Task RemoveAllContainerPortForwards_WhenPortsExist_StopsAndDisposesEachPort()
+  {
+    // Arrange
+    var f = Fixture.Create();
+    var port1 = CreateForwardedPort(8080u);
+    var port2 = CreateForwardedPort(5432u);
+    f.SshConnection.ForwardPort(8080u).Returns(port1);
+    f.SshConnection.ForwardPort(5432u).Returns(port2);
+    f.DockerApiClient
+      .GetAllContainerHostPortsAsync("my-resource", Arg.Any<CancellationToken>())
+      .Returns(Task.FromResult<List<uint>?>([8080u, 5432u]));
+    await f.Sut.AddAllContainerPortForwardsAsync("my-resource", CancellationToken.None);
+
+    // Act
+    f.Sut.RemoveAllContainerPortForwards("my-resource");
+
+    // Assert
+    port1.Received(1).Stop();
+    port1.Received(1).Dispose();
+    port2.Received(1).Stop();
+    port2.Received(1).Dispose();
+  }
+
+  [Fact]
+  public void RemoveAllContainerPortForwards_WhenResourceNotFound_DoesNotThrow()
+  {
+    // Arrange
+    var f = Fixture.Create();
+
+    // Act
+    var exception = Record.Exception(() => f.Sut.RemoveAllContainerPortForwards("unknown-resource"));
+
+    // Assert
+    Assert.Null(exception);
+  }
+
+  [Fact]
+  public async Task RemoveAllContainerPortForwards_WhenPortStopThrows_ExceptionIsSwallowed()
+  {
+    // Arrange
+    var f = Fixture.Create();
+    var port = CreateForwardedPort(8080u);
+    port.When(p => p.Stop()).Throw(new InvalidOperationException("stop failed"));
+    f.SshConnection.ForwardPort(8080u).Returns(port);
+    f.DockerApiClient
+      .GetAllContainerHostPortsAsync("my-resource", Arg.Any<CancellationToken>())
+      .Returns(Task.FromResult<List<uint>?>([8080u]));
+    await f.Sut.AddAllContainerPortForwardsAsync("my-resource", CancellationToken.None);
+
+    // Act
+    var exception = Record.Exception(() => f.Sut.RemoveAllContainerPortForwards("my-resource"));
+
+    // Assert
+    Assert.Null(exception);
+  }
+
+  [Fact]
+  public async Task Dispose_WhenPortsForwarded_StopsAndDisposesAllPortsAndSshConnection()
+  {
+    // Arrange
+    var f = Fixture.Create();
+    var port1 = CreateForwardedPort(8080u);
+    var port2 = CreateForwardedPort(5432u);
+    f.SshConnection.ForwardPort(8080u).Returns(port1);
+    f.SshConnection.ForwardPort(5432u).Returns(port2);
+    f.DockerApiClient
+      .GetAllContainerHostPortsAsync("my-resource", Arg.Any<CancellationToken>())
+      .Returns(Task.FromResult<List<uint>?>([8080u, 5432u]));
+    await f.Sut.AddAllContainerPortForwardsAsync("my-resource", CancellationToken.None);
+
+    // Act
+    f.Sut.Dispose();
+
+    // Assert
+    port1.Received(1).Stop();
+    port1.Received(1).Dispose();
+    port2.Received(1).Stop();
+    port2.Received(1).Dispose();
+    f.SshConnection.Received(1).Dispose();
+  }
+
+  [Fact]
+  public void Dispose_WhenSshConnectionNeverUsed_DoesNotDisposeSshConnection()
+  {
+    // Arrange
+    var f = Fixture.Create();
+
+    // Act
+    f.Sut.Dispose();
+
+    // Assert
+    f.SshConnection.DidNotReceive().Dispose();
+  }
+
+  [Fact]
+  public void Dispose_WhenCalledTwice_DoesNotThrow()
+  {
+    // Arrange
+    var f = Fixture.Create();
+
+    // Act
+    var exception = Record.Exception(() =>
+    {
+      f.Sut.Dispose();
+      f.Sut.Dispose();
+    });
+
+    // Assert
+    Assert.Null(exception);
+  }
+
+  private static ISshForwardedPort CreateForwardedPort(uint port)
+  {
+    var forwardedPort = Substitute.For<ISshForwardedPort>();
+    forwardedPort.Port.Returns(port);
+
+    return forwardedPort;
+  }
+
+  private sealed record Fixture(
+    SshTunnelManager Sut,
+    ISshConnection SshConnection,
+    IDockerApiClient DockerApiClient)
+  {
+    public static Fixture Create(bool connected = true)
+    {
+      var sshConnection = Substitute.For<ISshConnection>();
+      sshConnection.IsConnected.Returns(connected);
+
+      var dockerApiClient = Substitute.For<IDockerApiClient>();
+      var logger = Substitute.For<ILogger<SshTunnelManager>>();
+
+      return new Fixture(
+        new SshTunnelManager(logger, sshConnection, dockerApiClient),
+        sshConnection,
+        dockerApiClient);
+    }
+  }
+}
diff --git a/test/RemoteContainers.Aspire.UnitTest/UnitTest1.cs b/test/RemoteContainers.Aspire.UnitTest/UnitTest1.cs
deleted file mode 100644
index eb4b04d..0000000
--- a/test/RemoteContainers.Aspire.UnitTest/UnitTest1.cs
+++ /dev/null
@@ -1,10 +0,0 @@
-namespace Hj.RemoteContainers.Aspire.UnitTest;
-
-public class UnitTest1
-{
-  [Fact]
-  public void Test1()
-  {
-    // to do
-  }
-}

From 2edeedf8f01544b263078d2ec60d844496d0d3fd Mon Sep 17 00:00:00 2001
From: Henrik Jensen <1175002+henrikhimself@users.noreply.github.com>
Date: Sat, 14 Mar 2026 08:34:38 +0100
Subject: [PATCH 16/25] Address code review comments

---
 .vscode/settings.json                         | 34 +++++++++----------
 .../Ssh/SshTunnelManager.cs                   |  6 ++--
 2 files changed, 21 insertions(+), 19 deletions(-)

diff --git a/.vscode/settings.json b/.vscode/settings.json
index 83352cf..0bf3a56 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -1,19 +1,19 @@
 {
-    "dotnet.defaultSolution": "RemoteContainers.slnx",
-    "editor.minimap.enabled": false,
-    "files.exclude": {
-      "**/bin": true,
-      "**/obj": true
-    },
-    "git.enableCommitSigning": true,
-    "csharp.debug.symbolOptions.searchNuGetOrgSymbolServer": true,
-    "csharp.debug.symbolOptions.searchMicrosoftSymbolServer": true,
-    "csharp.debug.justMyCode": true,
-    "csharp.debug.requireExactSource": true,
-    "csharp.debug.suppressJITOptimizations": false,
-    "editor.inlayHints.enabled": "on",
-    "csharp.inlayHints.enableInlayHintsForImplicitVariableTypes": true,
-    "csharp.inlayHints.enableInlayHintsForTypes": true,
-    "dotnet.inlayHints.enableInlayHintsForIndexerParameters": true,
-    "dotnet.inlayHints.enableInlayHintsForLiteralParameters": true
+  "dotnet.defaultSolution": "RemoteContainers.slnx",
+  "editor.minimap.enabled": false,
+  "files.exclude": {
+    "**/bin": true,
+    "**/obj": true
+  },
+  "git.enableCommitSigning": true,
+  "csharp.debug.symbolOptions.searchNuGetOrgSymbolServer": true,
+  "csharp.debug.symbolOptions.searchMicrosoftSymbolServer": true,
+  "csharp.debug.justMyCode": true,
+  "csharp.debug.requireExactSource": true,
+  "csharp.debug.suppressJITOptimizations": false,
+  "editor.inlayHints.enabled": "on",
+  "csharp.inlayHints.enableInlayHintsForImplicitVariableTypes": true,
+  "csharp.inlayHints.enableInlayHintsForTypes": true,
+  "dotnet.inlayHints.enableInlayHintsForIndexerParameters": true,
+  "dotnet.inlayHints.enableInlayHintsForLiteralParameters": true
 }
diff --git a/src/RemoteContainers.Aspire/Ssh/SshTunnelManager.cs b/src/RemoteContainers.Aspire/Ssh/SshTunnelManager.cs
index 0756609..6695656 100644
--- a/src/RemoteContainers.Aspire/Ssh/SshTunnelManager.cs
+++ b/src/RemoteContainers.Aspire/Ssh/SshTunnelManager.cs
@@ -96,8 +96,6 @@ public void RemoveAllContainerPortForwards(string resourceName)
       try
       {
         forwardedPort.Stop();
-        forwardedPort.Dispose();
-
         if (_logger.IsEnabled(LogLevel.Information))
         {
           _logger.LogInformation("SSH tunnel removed for {ResourceName} port {Port}", resourceName, forwardedPort.Port);
@@ -110,6 +108,10 @@ public void RemoveAllContainerPortForwards(string resourceName)
           _logger.LogWarning(ex, "Failed to clean up SSH tunnel for {ResourceName} port {Port}", resourceName, forwardedPort.Port);
         }
       }
+      finally
+      {
+        forwardedPort.Dispose();
+      }
     }
   }
 

From ddba13f2820777960713538d8a8057064f95ecdd Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 14 Mar 2026 07:22:57 +0000
Subject: [PATCH 17/25] Initial plan


From 5874f6ffa4dc472332643ba8b14c2c2e382033c0 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 14 Mar 2026 07:26:51 +0000
Subject: [PATCH 18/25] Fix SSL policy error handling in DockerMessageHandler

Co-authored-by: henrikhimself <1175002+henrikhimself@users.noreply.github.com>
---
 src/RemoteContainers.Aspire/Docker/DockerMessageHandler.cs | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/src/RemoteContainers.Aspire/Docker/DockerMessageHandler.cs b/src/RemoteContainers.Aspire/Docker/DockerMessageHandler.cs
index 0237035..d2a3677 100644
--- a/src/RemoteContainers.Aspire/Docker/DockerMessageHandler.cs
+++ b/src/RemoteContainers.Aspire/Docker/DockerMessageHandler.cs
@@ -14,6 +14,7 @@
 // limitations under the License.
 // </copyright>
 
+using System.Net.Security;
 using System.Security.Cryptography.X509Certificates;
 
 namespace Hj.RemoteContainers.Aspire.Docker;
@@ -34,9 +35,9 @@ public HttpMessageHandler Init()
     if (_dockerCertificate.TryGetCertificate(out _caCert, out _clientCert))
     {
       ClientCertificates.Add(_clientCert);
-      ServerCertificateCustomValidationCallback = (_, serverCert, chain, _) =>
+      ServerCertificateCustomValidationCallback = (_, serverCert, chain, sslPolicyErrors) =>
       {
-        if (serverCert is null || chain is null)
+        if (serverCert is null || chain is null || (sslPolicyErrors & ~SslPolicyErrors.RemoteCertificateChainErrors) != SslPolicyErrors.None)
         {
           return false;
         }

From 39c7e275ed7c96d4a04826464e51c235bb3ea07b Mon Sep 17 00:00:00 2001
From: Henrik Jensen <1175002+henrikhimself@users.noreply.github.com>
Date: Sat, 14 Mar 2026 11:51:02 +0100
Subject: [PATCH 19/25] Add dashboard notification showing ssh tunnel status

---
 examples/Aspire.AppHost/Program.cs            |   7 +-
 .../Properties/launchSettings.json            |   2 +-
 examples/Aspire.AppHost/appsettings.json      |   2 +-
 .../Abstractions/FileSystem.cs                |   3 +
 .../Abstractions/SshForwardedPort.cs          |   2 +
 .../AppConfiguration.cs                       |   2 +-
 .../RemoteContainers.Aspire.csproj            |   2 +
 .../SshTunnelLifecycleHook.cs                 |  50 ++++---
 .../AppConfigurationTests.cs                  |   4 +-
 .../RemoteContainers.Aspire.UnitTest.csproj   |   2 +
 .../SshTunnelLifecycleHookTests.cs            | 137 ++++++++++--------
 11 files changed, 126 insertions(+), 87 deletions(-)

diff --git a/examples/Aspire.AppHost/Program.cs b/examples/Aspire.AppHost/Program.cs
index ffafc3c..56b591d 100644
--- a/examples/Aspire.AppHost/Program.cs
+++ b/examples/Aspire.AppHost/Program.cs
@@ -4,7 +4,10 @@
 
 builder.AddSshTunneling();
 
-_ = builder.AddContainer("whoami", "traefik/whoami:latest")
-    .WithHttpEndpoint(port: 8080, targetPort: 80);
+for (var i = 0; i < 3; i++)
+{
+  _ = builder.AddContainer("whoami-" + i, "traefik/whoami:latest")
+      .WithHttpEndpoint(port: 8080 + i, targetPort: 80);
+}
 
 await builder.Build().RunAsync();
diff --git a/examples/Aspire.AppHost/Properties/launchSettings.json b/examples/Aspire.AppHost/Properties/launchSettings.json
index 312548a..6c48947 100644
--- a/examples/Aspire.AppHost/Properties/launchSettings.json
+++ b/examples/Aspire.AppHost/Properties/launchSettings.json
@@ -12,7 +12,7 @@
         "ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL": "https://localhost:21021",
         "ASPIRE_DASHBOARD_MCP_ENDPOINT_URL": "https://localhost:23005",
         "ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "https://localhost:22264",
-        "DOCKER_HOST": "tcp://my-server:2376",
+        "DOCKER_HOST": "tcp://lyn.td:2376",
         "DOCKER_TLS_VERIFY": "1",
         "DOCKER_CERT_PATH": "/opt/certs/client"
       }
diff --git a/examples/Aspire.AppHost/appsettings.json b/examples/Aspire.AppHost/appsettings.json
index 6376795..bf0b46d 100644
--- a/examples/Aspire.AppHost/appsettings.json
+++ b/examples/Aspire.AppHost/appsettings.json
@@ -10,6 +10,6 @@
     "SshHost": "",
     "SshUser": "",
     "ContainerStartTimeout": "00:05:00",
-    "ContainerPollInterval": "00:00:05"
+    "ContainerPollInterval": "00:00:01"
   }
 }
diff --git a/src/RemoteContainers.Aspire/Abstractions/FileSystem.cs b/src/RemoteContainers.Aspire/Abstractions/FileSystem.cs
index 4691372..75c8cdc 100644
--- a/src/RemoteContainers.Aspire/Abstractions/FileSystem.cs
+++ b/src/RemoteContainers.Aspire/Abstractions/FileSystem.cs
@@ -14,8 +14,11 @@
 // limitations under the License.
 // </copyright>
 
+using System.Diagnostics.CodeAnalysis;
+
 namespace Hj.RemoteContainers.Aspire.Abstractions;
 
+[ExcludeFromCodeCoverage(Justification = "External dependencies")]
 internal sealed class FileSystem : IFileSystem
 {
   public bool FileExists(string path) => File.Exists(path);
diff --git a/src/RemoteContainers.Aspire/Abstractions/SshForwardedPort.cs b/src/RemoteContainers.Aspire/Abstractions/SshForwardedPort.cs
index fa16756..72d0a2c 100644
--- a/src/RemoteContainers.Aspire/Abstractions/SshForwardedPort.cs
+++ b/src/RemoteContainers.Aspire/Abstractions/SshForwardedPort.cs
@@ -14,10 +14,12 @@
 // limitations under the License.
 // </copyright>
 
+using System.Diagnostics.CodeAnalysis;
 using Renci.SshNet;
 
 namespace Hj.RemoteContainers.Aspire.Abstractions;
 
+[ExcludeFromCodeCoverage(Justification = "External dependencies")]
 internal sealed class SshForwardedPort : ISshForwardedPort
 {
   private readonly ForwardedPortLocal _forwardedPort;
diff --git a/src/RemoteContainers.Aspire/AppConfiguration.cs b/src/RemoteContainers.Aspire/AppConfiguration.cs
index 2f8c3d8..43e71dc 100644
--- a/src/RemoteContainers.Aspire/AppConfiguration.cs
+++ b/src/RemoteContainers.Aspire/AppConfiguration.cs
@@ -39,7 +39,7 @@ public AppConfiguration(IConfiguration configuration, string environmentUserName
     _configuration.GetValue<TimeSpan?>("RemoteContainers:ContainerStartTimeout") ?? TimeSpan.FromMinutes(5);
 
   public TimeSpan ContainerPollInterval =>
-    _configuration.GetValue<TimeSpan?>("RemoteContainers:ContainerPollInterval") ?? TimeSpan.FromSeconds(5);
+    _configuration.GetValue<TimeSpan?>("RemoteContainers:ContainerPollInterval") ?? TimeSpan.FromSeconds(1);
 
   public string SshKeyPath => Path.Combine(_environmentUserProfilePath, ".ssh");
 
diff --git a/src/RemoteContainers.Aspire/RemoteContainers.Aspire.csproj b/src/RemoteContainers.Aspire/RemoteContainers.Aspire.csproj
index b149442..393597c 100644
--- a/src/RemoteContainers.Aspire/RemoteContainers.Aspire.csproj
+++ b/src/RemoteContainers.Aspire/RemoteContainers.Aspire.csproj
@@ -15,6 +15,8 @@
     <PackageReadmeFile>README.md</PackageReadmeFile>
     <PackageLicenseFile>LICENSE</PackageLicenseFile>
     <Version>1.0.0-beta1</Version>
+    <!-- IInteractionService and related types are experimental in Aspire.Hosting 13.x -->
+    <NoWarn>$(NoWarn);ASPIREINTERACTION001</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>
diff --git a/src/RemoteContainers.Aspire/SshTunnelLifecycleHook.cs b/src/RemoteContainers.Aspire/SshTunnelLifecycleHook.cs
index 87a54f6..535e9c8 100644
--- a/src/RemoteContainers.Aspire/SshTunnelLifecycleHook.cs
+++ b/src/RemoteContainers.Aspire/SshTunnelLifecycleHook.cs
@@ -24,20 +24,23 @@ namespace Hj.RemoteContainers.Aspire;
 
 internal sealed class SshTunnelLifecycleHook : IDistributedApplicationEventingSubscriber
 {
+  private static readonly TimeSpan _notificationAutoDismissDelay = TimeSpan.FromSeconds(5);
+
   private readonly ILogger<SshTunnelLifecycleHook> _logger;
   private readonly ISshTunnelManager _tunnelManager;
+  private readonly IInteractionService _interactionService;
 
-  public SshTunnelLifecycleHook(ILogger<SshTunnelLifecycleHook> logger, ISshTunnelManager tunnelManager)
+  public SshTunnelLifecycleHook(ILogger<SshTunnelLifecycleHook> logger, ISshTunnelManager tunnelManager, IInteractionService interactionService)
   {
     _logger = logger;
     _tunnelManager = tunnelManager;
+    _interactionService = interactionService;
   }
 
   public Task SubscribeAsync(IDistributedApplicationEventing eventing, DistributedApplicationExecutionContext executionContext, CancellationToken cancellationToken)
   {
-    eventing.Subscribe<ResourceEndpointsAllocatedEvent>(SetUpTunnelAsync);
     eventing.Subscribe<ResourceReadyEvent>(SetUpTunnelOnReadyAsync);
-    eventing.Subscribe<ResourceStoppedEvent>(TearDownTunnel);
+    eventing.Subscribe<ResourceStoppedEvent>(TearDownTunnelAsync);
 
     return Task.CompletedTask;
   }
@@ -45,7 +48,7 @@ public Task SubscribeAsync(IDistributedApplicationEventing eventing, Distributed
   private static bool IsContainerResource(IResource resource) =>
     resource.Annotations.OfType<ContainerImageAnnotation>().Any();
 
-  private async Task SetUpTunnelAsync(ResourceEndpointsAllocatedEvent evt, CancellationToken cancellationToken)
+  private async Task SetUpTunnelOnReadyAsync(ResourceReadyEvent evt, CancellationToken cancellationToken)
   {
     if (!IsContainerResource(evt.Resource))
     {
@@ -54,18 +57,23 @@ private async Task SetUpTunnelAsync(ResourceEndpointsAllocatedEvent evt, Cancell
 
     try
     {
+      // Remove stale tunnels from the previous run of this resource before creating new ones.
+      _tunnelManager.RemoveAllContainerPortForwards(evt.Resource.Name);
       await _tunnelManager.AddAllContainerPortForwardsAsync(evt.Resource.Name, cancellationToken);
+      await PromptNotificationAsync($"Port forwarding started for {evt.Resource.Name}.", MessageIntent.Success, cancellationToken);
     }
     catch (Exception ex)
     {
       if (_logger.IsEnabled(LogLevel.Error))
       {
-        _logger.LogError(ex, "Failed to set up SSH tunnel for resource {ResourceName}", evt.Resource.Name);
+        _logger.LogError(ex, "Failed to re-establish SSH tunnel for resource {ResourceName}", evt.Resource.Name);
       }
+
+      await PromptNotificationAsync($"Port forward creation failed for {evt.Resource.Name}: {ex.Message}", MessageIntent.Error, cancellationToken);
     }
   }
 
-  private async Task SetUpTunnelOnReadyAsync(ResourceReadyEvent evt, CancellationToken cancellationToken)
+  private async Task TearDownTunnelAsync(ResourceStoppedEvent evt, CancellationToken cancellationToken)
   {
     if (!IsContainerResource(evt.Resource))
     {
@@ -74,38 +82,38 @@ private async Task SetUpTunnelOnReadyAsync(ResourceReadyEvent evt, CancellationT
 
     try
     {
-      // Remove stale tunnels from the previous run of this resource before creating new ones.
       _tunnelManager.RemoveAllContainerPortForwards(evt.Resource.Name);
-      await _tunnelManager.AddAllContainerPortForwardsAsync(evt.Resource.Name, cancellationToken);
     }
     catch (Exception ex)
     {
       if (_logger.IsEnabled(LogLevel.Error))
       {
-        _logger.LogError(ex, "Failed to re-establish SSH tunnel for resource {ResourceName}", evt.Resource.Name);
+        _logger.LogError(ex, "Failed to tear down SSH tunnel for resource {ResourceName}", evt.Resource.Name);
       }
+
+      await PromptNotificationAsync($"Port forwarding removal failed for {evt.Resource.Name}.", MessageIntent.Error, cancellationToken);
     }
   }
 
-  private Task TearDownTunnel(ResourceStoppedEvent evt, CancellationToken cancellationToken)
+  private async Task PromptNotificationAsync(string message, MessageIntent intent, CancellationToken cancellationToken)
   {
-    if (!IsContainerResource(evt.Resource))
+    if (!_interactionService.IsAvailable)
     {
-      return Task.CompletedTask;
+      return;
     }
 
-    try
+    var options = new NotificationInteractionOptions { Intent = intent };
+
+    if (intent == MessageIntent.Error)
     {
-      _tunnelManager.RemoveAllContainerPortForwards(evt.Resource.Name);
+      await _interactionService.PromptNotificationAsync("SSH Tunnel", message, options, cancellationToken);
     }
-    catch (Exception ex)
+    else
     {
-      if (_logger.IsEnabled(LogLevel.Error))
-      {
-        _logger.LogError(ex, "Failed to tear down SSH tunnel for resource {ResourceName}", evt.Resource.Name);
-      }
+      // Auto-dismiss non-error notifications after a short delay so they don't linger.
+      using var cts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
+      cts.CancelAfter(_notificationAutoDismissDelay);
+      await _interactionService.PromptNotificationAsync("SSH Tunnel", message, options, cts.Token);
     }
-
-    return Task.CompletedTask;
   }
 }
diff --git a/test/RemoteContainers.Aspire.UnitTest/AppConfigurationTests.cs b/test/RemoteContainers.Aspire.UnitTest/AppConfigurationTests.cs
index 6d7cfc1..388c4bd 100644
--- a/test/RemoteContainers.Aspire.UnitTest/AppConfigurationTests.cs
+++ b/test/RemoteContainers.Aspire.UnitTest/AppConfigurationTests.cs
@@ -34,7 +34,7 @@ public void ContainerStartTimeout_WhenConfigured_ReturnsConfiguredValue()
   }
 
   [Fact]
-  public void ContainerPollInterval_WhenNotConfigured_ReturnsFiveSeconds()
+  public void ContainerPollInterval_WhenNotConfigured_ReturnsOneSecond()
   {
     // Arrange
     var sut = Fixture.Create().Build();
@@ -43,7 +43,7 @@ public void ContainerPollInterval_WhenNotConfigured_ReturnsFiveSeconds()
     var result = sut.ContainerPollInterval;
 
     // Assert
-    Assert.Equal(TimeSpan.FromSeconds(5), result);
+    Assert.Equal(TimeSpan.FromSeconds(1), result);
   }
 
   [Fact]
diff --git a/test/RemoteContainers.Aspire.UnitTest/RemoteContainers.Aspire.UnitTest.csproj b/test/RemoteContainers.Aspire.UnitTest/RemoteContainers.Aspire.UnitTest.csproj
index 514e68d..c380af9 100644
--- a/test/RemoteContainers.Aspire.UnitTest/RemoteContainers.Aspire.UnitTest.csproj
+++ b/test/RemoteContainers.Aspire.UnitTest/RemoteContainers.Aspire.UnitTest.csproj
@@ -7,6 +7,8 @@
     <AnalysisMode>Recommended</AnalysisMode>
     <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    <!-- IInteractionService and related types are experimental in Aspire.Hosting 13.x -->
+    <NoWarn>$(NoWarn);ASPIREINTERACTION001</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>
diff --git a/test/RemoteContainers.Aspire.UnitTest/SshTunnelLifecycleHookTests.cs b/test/RemoteContainers.Aspire.UnitTest/SshTunnelLifecycleHookTests.cs
index a6b3fbf..f454a64 100644
--- a/test/RemoteContainers.Aspire.UnitTest/SshTunnelLifecycleHookTests.cs
+++ b/test/RemoteContainers.Aspire.UnitTest/SshTunnelLifecycleHookTests.cs
@@ -12,167 +12,182 @@ public sealed class SshTunnelLifecycleHookTests
   private static readonly DistributedApplicationExecutionContext ExecutionContext = new(DistributedApplicationOperation.Run);
 
   [Fact]
-  public async Task SubscribeAsync_RegistersAllThreeEventHandlers()
+  public async Task SetUpTunnelOnReady_ContainerResource_RemovesOldTunnelsThenAddsNew()
   {
     // Arrange
     var f = Fixture.Create();
+    var handler = f.CaptureHandler<ResourceReadyEvent>();
+    await f.Sut.SubscribeAsync(f.Eventing, ExecutionContext, CancellationToken.None);
 
     // Act
-    await f.Sut.SubscribeAsync(f.Eventing, ExecutionContext, CancellationToken.None);
+    await handler(new ResourceReadyEvent(CreateContainerResource("my-resource"), Substitute.For<IServiceProvider>()), CancellationToken.None);
 
     // Assert
-    f.Eventing.Received(1).Subscribe(Arg.Any<Func<ResourceEndpointsAllocatedEvent, CancellationToken, Task>>());
-    f.Eventing.Received(1).Subscribe(Arg.Any<Func<ResourceReadyEvent, CancellationToken, Task>>());
-    f.Eventing.Received(1).Subscribe(Arg.Any<Func<ResourceStoppedEvent, CancellationToken, Task>>());
+    Received.InOrder(() =>
+    {
+      f.TunnelManager.RemoveAllContainerPortForwards("my-resource");
+      _ = f.TunnelManager.AddAllContainerPortForwardsAsync("my-resource", Arg.Any<CancellationToken>());
+    });
   }
 
   [Fact]
-  public async Task SetUpTunnel_ContainerResource_CallsAddAllContainerPortForwards()
+  public async Task SetUpTunnelOnReady_NonContainerResource_DoesNotCallTunnelManager()
   {
     // Arrange
     var f = Fixture.Create();
-    var handler = f.CaptureHandler<ResourceEndpointsAllocatedEvent>();
+    var handler = f.CaptureHandler<ResourceReadyEvent>();
     await f.Sut.SubscribeAsync(f.Eventing, ExecutionContext, CancellationToken.None);
 
     // Act
-    await handler(new ResourceEndpointsAllocatedEvent(CreateContainerResource("my-resource"), Substitute.For<IServiceProvider>()), CancellationToken.None);
+    await handler(new ResourceReadyEvent(CreateNonContainerResource("my-resource"), Substitute.For<IServiceProvider>()), CancellationToken.None);
 
     // Assert
-    await f.TunnelManager.Received(1).AddAllContainerPortForwardsAsync("my-resource", Arg.Any<CancellationToken>());
+    f.TunnelManager.DidNotReceive().RemoveAllContainerPortForwards(Arg.Any<string>());
+    await f.TunnelManager.DidNotReceive().AddAllContainerPortForwardsAsync(Arg.Any<string>(), Arg.Any<CancellationToken>());
   }
 
   [Fact]
-  public async Task SetUpTunnel_NonContainerResource_DoesNotCallTunnelManager()
+  public async Task SetUpTunnelOnReady_WhenManagerThrows_ExceptionIsSwallowed()
   {
     // Arrange
     var f = Fixture.Create();
-    var handler = f.CaptureHandler<ResourceEndpointsAllocatedEvent>();
+    var handler = f.CaptureHandler<ResourceReadyEvent>();
+    f.TunnelManager.AddAllContainerPortForwardsAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
+        .ThrowsAsync(new InvalidOperationException("boom"));
     await f.Sut.SubscribeAsync(f.Eventing, ExecutionContext, CancellationToken.None);
 
     // Act
-    await handler(new ResourceEndpointsAllocatedEvent(CreateNonContainerResource("my-resource"), Substitute.For<IServiceProvider>()), CancellationToken.None);
+    var exception = await Record.ExceptionAsync(
+        () => handler(new ResourceReadyEvent(CreateContainerResource("my-resource"), Substitute.For<IServiceProvider>()), CancellationToken.None));
 
     // Assert
-    await f.TunnelManager.DidNotReceive().AddAllContainerPortForwardsAsync(Arg.Any<string>(), Arg.Any<CancellationToken>());
+    Assert.Null(exception);
   }
 
   [Fact]
-  public async Task SetUpTunnel_WhenManagerThrows_ExceptionIsSwallowed()
+  public async Task TearDownTunnelAsync_ContainerResource_CallsRemoveAllContainerPortForwards()
   {
     // Arrange
     var f = Fixture.Create();
-    var handler = f.CaptureHandler<ResourceEndpointsAllocatedEvent>();
-    f.TunnelManager.AddAllContainerPortForwardsAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
-        .ThrowsAsync(new InvalidOperationException("boom"));
+    var handler = f.CaptureHandler<ResourceStoppedEvent>();
     await f.Sut.SubscribeAsync(f.Eventing, ExecutionContext, CancellationToken.None);
 
     // Act
-    var exception = await Record.ExceptionAsync(
-        () => handler(new ResourceEndpointsAllocatedEvent(CreateContainerResource("my-resource"), Substitute.For<IServiceProvider>()), CancellationToken.None));
+    await handler(CreateResourceStoppedEvent(CreateContainerResource("my-resource")), CancellationToken.None);
 
     // Assert
-    Assert.Null(exception);
+    f.TunnelManager.Received(1).RemoveAllContainerPortForwards("my-resource");
   }
 
   [Fact]
-  public async Task SetUpTunnelOnReady_ContainerResource_RemovesOldTunnelsThenAddsNew()
+  public async Task TearDownTunnelAsync_NonContainerResource_DoesNotCallTunnelManager()
   {
     // Arrange
     var f = Fixture.Create();
-    var handler = f.CaptureHandler<ResourceReadyEvent>();
+    var handler = f.CaptureHandler<ResourceStoppedEvent>();
     await f.Sut.SubscribeAsync(f.Eventing, ExecutionContext, CancellationToken.None);
 
     // Act
-    await handler(new ResourceReadyEvent(CreateContainerResource("my-resource"), Substitute.For<IServiceProvider>()), CancellationToken.None);
+    await handler(CreateResourceStoppedEvent(CreateNonContainerResource("my-resource")), CancellationToken.None);
 
     // Assert
-    Received.InOrder(() =>
-    {
-      f.TunnelManager.RemoveAllContainerPortForwards("my-resource");
-      _ = f.TunnelManager.AddAllContainerPortForwardsAsync("my-resource", Arg.Any<CancellationToken>());
-    });
+    f.TunnelManager.DidNotReceive().RemoveAllContainerPortForwards(Arg.Any<string>());
   }
 
   [Fact]
-  public async Task SetUpTunnelOnReady_NonContainerResource_DoesNotCallTunnelManager()
+  public async Task TearDownTunnelAsync_WhenManagerThrows_ExceptionIsSwallowed()
   {
     // Arrange
     var f = Fixture.Create();
-    var handler = f.CaptureHandler<ResourceReadyEvent>();
+    var handler = f.CaptureHandler<ResourceStoppedEvent>();
+    f.TunnelManager.When(m => m.RemoveAllContainerPortForwards(Arg.Any<string>()))
+        .Throw(new InvalidOperationException("boom"));
     await f.Sut.SubscribeAsync(f.Eventing, ExecutionContext, CancellationToken.None);
 
     // Act
-    await handler(new ResourceReadyEvent(CreateNonContainerResource("my-resource"), Substitute.For<IServiceProvider>()), CancellationToken.None);
+    var exception = await Record.ExceptionAsync(
+        () => handler(CreateResourceStoppedEvent(CreateContainerResource("my-resource")), CancellationToken.None));
 
     // Assert
-    f.TunnelManager.DidNotReceive().RemoveAllContainerPortForwards(Arg.Any<string>());
-    await f.TunnelManager.DidNotReceive().AddAllContainerPortForwardsAsync(Arg.Any<string>(), Arg.Any<CancellationToken>());
+    Assert.Null(exception);
   }
 
   [Fact]
-  public async Task SetUpTunnelOnReady_WhenManagerThrows_ExceptionIsSwallowed()
+  public async Task SetUpTunnel_WhenContainerReady_SendsSuccessNotification()
   {
     // Arrange
     var f = Fixture.Create();
     var handler = f.CaptureHandler<ResourceReadyEvent>();
-    f.TunnelManager.AddAllContainerPortForwardsAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
-        .ThrowsAsync(new InvalidOperationException("boom"));
     await f.Sut.SubscribeAsync(f.Eventing, ExecutionContext, CancellationToken.None);
 
     // Act
-    var exception = await Record.ExceptionAsync(
-        () => handler(new ResourceReadyEvent(CreateContainerResource("my-resource"), Substitute.For<IServiceProvider>()), CancellationToken.None));
+    await handler(new ResourceReadyEvent(CreateContainerResource("my-resource"), Substitute.For<IServiceProvider>()), CancellationToken.None);
 
     // Assert
-    Assert.Null(exception);
+    _ = f.InteractionService.Received(1).PromptNotificationAsync(
+      Arg.Any<string>(),
+      Arg.Any<string>(),
+      Arg.Is<NotificationInteractionOptions?>(o => o!.Intent == MessageIntent.Success),
+      Arg.Any<CancellationToken>());
   }
 
   [Fact]
-  public async Task TearDownTunnel_ContainerResource_CallsRemoveAllContainerPortForwards()
+  public async Task SetUpTunnel_WhenAddPortForwardFails_SendsErrorNotification()
   {
     // Arrange
     var f = Fixture.Create();
-    var handler = f.CaptureHandler<ResourceStoppedEvent>();
+    var handler = f.CaptureHandler<ResourceReadyEvent>();
+    f.TunnelManager.AddAllContainerPortForwardsAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
+        .ThrowsAsync(new InvalidOperationException("connection refused"));
     await f.Sut.SubscribeAsync(f.Eventing, ExecutionContext, CancellationToken.None);
 
     // Act
-    await handler(CreateResourceStoppedEvent(CreateContainerResource("my-resource")), CancellationToken.None);
+    await handler(new ResourceReadyEvent(CreateContainerResource("my-resource"), Substitute.For<IServiceProvider>()), CancellationToken.None);
 
     // Assert
-    f.TunnelManager.Received(1).RemoveAllContainerPortForwards("my-resource");
+    _ = f.InteractionService.Received(1).PromptNotificationAsync(
+      Arg.Any<string>(),
+      Arg.Is<string>(m => m.Contains("connection refused")),
+      Arg.Is<NotificationInteractionOptions?>(o => o!.Intent == MessageIntent.Error),
+      Arg.Any<CancellationToken>());
   }
 
   [Fact]
-  public async Task TearDownTunnel_NonContainerResource_DoesNotCallTunnelManager()
+  public async Task SetUpTunnel_WhenInteractionServiceNotAvailable_DoesNotSendNotification()
   {
     // Arrange
-    var f = Fixture.Create();
-    var handler = f.CaptureHandler<ResourceStoppedEvent>();
+    var f = Fixture.Create(interactionAvailable: false);
+    var handler = f.CaptureHandler<ResourceReadyEvent>();
     await f.Sut.SubscribeAsync(f.Eventing, ExecutionContext, CancellationToken.None);
 
     // Act
-    await handler(CreateResourceStoppedEvent(CreateNonContainerResource("my-resource")), CancellationToken.None);
+    await handler(new ResourceReadyEvent(CreateContainerResource("my-resource"), Substitute.For<IServiceProvider>()), CancellationToken.None);
 
     // Assert
-    f.TunnelManager.DidNotReceive().RemoveAllContainerPortForwards(Arg.Any<string>());
+    _ = f.InteractionService.DidNotReceive().PromptNotificationAsync(
+      Arg.Any<string>(),
+      Arg.Any<string>(),
+      Arg.Any<NotificationInteractionOptions?>(),
+      Arg.Any<CancellationToken>());
   }
 
   [Fact]
-  public async Task TearDownTunnel_WhenManagerThrows_ExceptionIsSwallowed()
+  public async Task TearDownTunnelAsync_WhenInteractionServiceNotAvailable_DoesNotSendNotification()
   {
     // Arrange
-    var f = Fixture.Create();
+    var f = Fixture.Create(interactionAvailable: false);
     var handler = f.CaptureHandler<ResourceStoppedEvent>();
-    f.TunnelManager.When(m => m.RemoveAllContainerPortForwards(Arg.Any<string>()))
-        .Throw(new InvalidOperationException("boom"));
     await f.Sut.SubscribeAsync(f.Eventing, ExecutionContext, CancellationToken.None);
 
     // Act
-    var exception = await Record.ExceptionAsync(
-        () => handler(CreateResourceStoppedEvent(CreateContainerResource("my-resource")), CancellationToken.None));
+    await handler(CreateResourceStoppedEvent(CreateContainerResource("my-resource")), CancellationToken.None);
 
     // Assert
-    Assert.Null(exception);
+    _ = f.InteractionService.DidNotReceive().PromptNotificationAsync(
+      Arg.Any<string>(),
+      Arg.Any<string>(),
+      Arg.Any<NotificationInteractionOptions?>(),
+      Arg.Any<CancellationToken>());
   }
 
   private static TestResource CreateContainerResource(string name)
@@ -203,17 +218,21 @@ private sealed class TestResource(string name) : IResource
   private sealed record Fixture(
       SshTunnelLifecycleHook Sut,
       ISshTunnelManager TunnelManager,
-      IDistributedApplicationEventing Eventing)
+      IDistributedApplicationEventing Eventing,
+      IInteractionService InteractionService)
   {
-    public static Fixture Create()
+    public static Fixture Create(bool interactionAvailable = true)
     {
       var tunnelManager = Substitute.For<ISshTunnelManager>();
       var logger = Substitute.For<ILogger<SshTunnelLifecycleHook>>();
+      var interactionService = Substitute.For<IInteractionService>();
+      interactionService.IsAvailable.Returns(interactionAvailable);
 
       return new Fixture(
-          new SshTunnelLifecycleHook(logger, tunnelManager),
+          new SshTunnelLifecycleHook(logger, tunnelManager, interactionService),
           tunnelManager,
-          Substitute.For<IDistributedApplicationEventing>());
+          Substitute.For<IDistributedApplicationEventing>(),
+          interactionService);
     }
 
     public Func<T, CancellationToken, Task> CaptureHandler<T>()

From 0f7c40b1cb37d1384a92e8a6839594e10c41b050 Mon Sep 17 00:00:00 2001
From: Henrik Jensen <1175002+henrikhimself@users.noreply.github.com>
Date: Sat, 14 Mar 2026 13:06:20 +0100
Subject: [PATCH 20/25] Address code review comments

---
 .github/workflows/ci.yml                               | 2 ++
 examples/Aspire.AppHost/Properties/launchSettings.json | 2 +-
 src/RemoteContainers.Aspire/Docker/DockerApiClient.cs  | 4 ----
 src/RemoteContainers.Aspire/Ssh/SshConnection.cs       | 2 +-
 4 files changed, 4 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 7c196d6..cc399d5 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -15,3 +15,5 @@ jobs:
         dotnet-version: 10.0.x
     - name: Build
       run: dotnet build
+    - name: Test
+      run: dotnet test --no-build
diff --git a/examples/Aspire.AppHost/Properties/launchSettings.json b/examples/Aspire.AppHost/Properties/launchSettings.json
index 6c48947..312548a 100644
--- a/examples/Aspire.AppHost/Properties/launchSettings.json
+++ b/examples/Aspire.AppHost/Properties/launchSettings.json
@@ -12,7 +12,7 @@
         "ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL": "https://localhost:21021",
         "ASPIRE_DASHBOARD_MCP_ENDPOINT_URL": "https://localhost:23005",
         "ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "https://localhost:22264",
-        "DOCKER_HOST": "tcp://lyn.td:2376",
+        "DOCKER_HOST": "tcp://my-server:2376",
         "DOCKER_TLS_VERIFY": "1",
         "DOCKER_CERT_PATH": "/opt/certs/client"
       }
diff --git a/src/RemoteContainers.Aspire/Docker/DockerApiClient.cs b/src/RemoteContainers.Aspire/Docker/DockerApiClient.cs
index 7852ab5..462f033 100644
--- a/src/RemoteContainers.Aspire/Docker/DockerApiClient.cs
+++ b/src/RemoteContainers.Aspire/Docker/DockerApiClient.cs
@@ -41,10 +41,6 @@ public DockerApiClient(ILogger<DockerApiClient> logger, HttpClient httpClient, A
   /// </summary>
   /// <remarks>
   /// <para>
-  /// ResourceEndpointsAllocatedEvent fires before DCP actually starts containers on the remote Docker host, so an
-  /// immediate query would return an empty list. Polling handles this toctou.
-  /// </para>
-  /// <para>
   /// A stale container from a previous Aspire run may still be running when the event fires. To avoid tunnelling the wrong ports,
   /// the method requires the same container ID to appear on two consecutive polls before accepting the result. If DCP recycles
   /// the container between polls the ID changes and polling continues until the replacement stabilises.
diff --git a/src/RemoteContainers.Aspire/Ssh/SshConnection.cs b/src/RemoteContainers.Aspire/Ssh/SshConnection.cs
index 066145f..af8c5ef 100644
--- a/src/RemoteContainers.Aspire/Ssh/SshConnection.cs
+++ b/src/RemoteContainers.Aspire/Ssh/SshConnection.cs
@@ -45,7 +45,7 @@ public void Connect()
     _keyFiles = LoadSshKeyFiles(keyDir);
     if (_keyFiles.Count == 0)
     {
-      throw new InvalidOperationException("No SSH private keys found.");
+      throw new InvalidOperationException("No compatible SSH private keys found.");
     }
 
     _sshClient = new SshClient(_appConfiguration.SshHost, _appConfiguration.SshUser, [.. _keyFiles]);

From 302742d26009f7c0676912870b92e06ccdebeb29 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 14 Mar 2026 12:02:56 +0000
Subject: [PATCH 21/25] Initial plan


From 40f9516982c1cfe98e18178e0ec47f6321aa5c5e Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 14 Mar 2026 12:08:36 +0000
Subject: [PATCH 22/25] Fix: preserve stabilization state across transient
 HttpRequestException in DockerApiClient

Co-authored-by: henrikhimself <1175002+henrikhimself@users.noreply.github.com>
---
 src/RemoteContainers.Aspire/Docker/DockerApiClient.cs | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/RemoteContainers.Aspire/Docker/DockerApiClient.cs b/src/RemoteContainers.Aspire/Docker/DockerApiClient.cs
index 462f033..d399b3c 100644
--- a/src/RemoteContainers.Aspire/Docker/DockerApiClient.cs
+++ b/src/RemoteContainers.Aspire/Docker/DockerApiClient.cs
@@ -103,8 +103,10 @@ public DockerApiClient(ILogger<DockerApiClient> logger, HttpClient httpClient, A
           _logger.LogError(ex, "Docker API request failed for {ResourceName}; retrying…", resourceName);
         }
 
-        lastSeenId = null;
-        isFirstPoll = false;
+        // Do not reset lastSeenId or isFirstPoll — a transient error gives no information about the
+        // container state, so the existing stabilization state must be preserved. Resetting would
+        // set lastSeenId to null, causing the next successful find to be accepted immediately via the
+        // "appeared after an empty poll" path, which defeats the two-poll confirmation.
       }
 
       await Task.Delay(pollInterval, cancellationToken);

From 6250b312530aad7877b7350f15e8abd3b6d8fac0 Mon Sep 17 00:00:00 2001
From: Henrik Jensen <1175002+henrikhimself@users.noreply.github.com>
Date: Sat, 14 Mar 2026 13:16:49 +0100
Subject: [PATCH 23/25] Remove comment

---
 src/RemoteContainers.Aspire/Docker/DockerApiClient.cs | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/src/RemoteContainers.Aspire/Docker/DockerApiClient.cs b/src/RemoteContainers.Aspire/Docker/DockerApiClient.cs
index d399b3c..204f0a7 100644
--- a/src/RemoteContainers.Aspire/Docker/DockerApiClient.cs
+++ b/src/RemoteContainers.Aspire/Docker/DockerApiClient.cs
@@ -102,11 +102,6 @@ public DockerApiClient(ILogger<DockerApiClient> logger, HttpClient httpClient, A
         {
           _logger.LogError(ex, "Docker API request failed for {ResourceName}; retrying…", resourceName);
         }
-
-        // Do not reset lastSeenId or isFirstPoll — a transient error gives no information about the
-        // container state, so the existing stabilization state must be preserved. Resetting would
-        // set lastSeenId to null, causing the next successful find to be accepted immediately via the
-        // "appeared after an empty poll" path, which defeats the two-poll confirmation.
       }
 
       await Task.Delay(pollInterval, cancellationToken);

From 451785de8fe4ebd843ec8c1a97a2875f27eb332f Mon Sep 17 00:00:00 2001
From: Henrik Jensen <1175002+henrikhimself@users.noreply.github.com>
Date: Sat, 14 Mar 2026 13:19:50 +0100
Subject: [PATCH 24/25] Address code review comments

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index b138df0..501ce44 100644
--- a/README.md
+++ b/README.md
@@ -87,7 +87,7 @@ These can be set via any .NET configuration source (environment variables, `apps
 | `RemoteContainers:SshHost` | Hostname from `DOCKER_HOST` | Override the SSH connection target if it differs from the Docker API host. |
 | `RemoteContainers:SshUser` | Current OS username | Override the SSH username. |
 | `RemoteContainers:ContainerStartTimeout` | `00:05:00` | How long to wait for a container's ports to become available before giving up. Expressed as a `TimeSpan` string (e.g. `00:05:00`). |
-| `RemoteContainers:ContainerPollInterval` | `00:00:05` | How often to poll the Docker API while waiting for a container's ports. Expressed as a `TimeSpan` string (e.g. `00:00:05`). |
+| `RemoteContainers:ContainerPollInterval` | `00:00:01` | How often to poll the Docker API while waiting for a container's ports. Expressed as a `TimeSpan` string (e.g. `00:00:01`). |
 
 ### SSH Key Authentication
 

From f59d4a3e20ad108785bd7c576151b2aae1f00fb4 Mon Sep 17 00:00:00 2001
From: Henrik Jensen <1175002+henrikhimself@users.noreply.github.com>
Date: Sat, 14 Mar 2026 13:22:47 +0100
Subject: [PATCH 25/25] Remove a unit test

---
 .../DockerApiClientTests.cs                       | 15 ---------------
 1 file changed, 15 deletions(-)

diff --git a/test/RemoteContainers.Aspire.UnitTest/DockerApiClientTests.cs b/test/RemoteContainers.Aspire.UnitTest/DockerApiClientTests.cs
index af2e6be..517850a 100644
--- a/test/RemoteContainers.Aspire.UnitTest/DockerApiClientTests.cs
+++ b/test/RemoteContainers.Aspire.UnitTest/DockerApiClientTests.cs
@@ -71,21 +71,6 @@ public async Task GetAllContainerHostPortsAsync_WhenTimeoutExpires_ReturnsNull()
     Assert.Null(result);
   }
 
-  [Fact]
-  public async Task GetAllContainerHostPortsAsync_WhenHttpRequestFails_RetriesAndEventuallyReturnsPorts()
-  {
-    // Arrange — null signals the handler to throw HttpRequestException
-    var f = Fixture.Create(
-      null,
-      ContainerJson("abc", ["/my-resource"], [8080u]));
-
-    // Act
-    var result = await f.Sut.GetAllContainerHostPortsAsync("my-resource", CancellationToken.None);
-
-    // Assert
-    Assert.Equal([8080u], result);
-  }
-
   [Fact]
   public async Task GetAllContainerHostPortsAsync_WhenNameHasLeadingSlash_MatchesResourceName()
   {