Container proxy update

content/manuals/desktop/features/networking/_index.md

@@ -65,13 +65,9 @@ Host firewalls can permit or deny inbound connections by filtering on `com.docke
 
 ## Using Docker Desktop with a proxy
 
-Docker Desktop can use your system’s default proxy settings or custom settings that you configure with [Docker Desktop's proxy setting](/manuals/desktop/settings-and-maintenance/settings.md#proxies). All proxy traffic passes through `com.docker.backend.exe`.
+Docker Desktop can use your system’s default proxy settings or custom settings that you configure with [Docker Desktop’s proxy setting](/manuals/desktop/settings-and-maintenance/settings.md#proxies).
 
-When a proxy is enabled:
-
-- The backend process forwards the network requests, for example `docker pull`, through an internal proxy at `http.docker.internal:3128`.
-- The internal proxy then connects either directly to the internet or through your upstream proxy, depending on your configuration and adding authentication if necessary.
-- Docker Desktop then downloads the requested images or data through the proxy as usual.
+Docker Desktop routes traffic through two separate proxies. The Containers proxy governs all `docker image pull` operations, as well as running container traffic when air-gapped container enforcement is enabled. The Docker Desktop proxy governs host-level traffic - the Desktop application, Docker CLI, and extensions — and is a fallback for image pulls only when the Containers proxy is not explicitly configured.
 
 Note that:
 

content/manuals/desktop/settings-and-maintenance/settings.md

@@ -123,7 +123,7 @@ To prevent developers from accidentally changing the proxy settings, see
 
 #### Docker Desktop proxy
 
-Used for signing in to Docker, pulling and pushing images, fetching artifacts during image builds, and reporting error diagnostics.
+Used for Docker Desktop host-level traffic: signing in to Docker, the Desktop application, CLI, and extensions. Acts as a fallback for `docker image pull` only when [Containers proxy](#containers-proxy) is not configured.
 
 | Proxy mode | Description |
 |------------|-------------|
@@ -137,7 +137,7 @@ Used for signing in to Docker, pulling and pushing images, fetching artifacts du
 
 #### Containers proxy
 
-Used for outbound traffic from running containers.
+Used for `docker image pull` (always enforced - all `docker pull` and Compose pull operations go through this proxy) and for outbound traffic from running containers when air-gapped container enforcement is configured. If a PAC file is configured here, ensure it returns an appropriate proxy server for Docker registry endpoints, or image pulls will fail.
 
 | Proxy mode | Description |
 |------------|-------------|

content/manuals/enterprise/security/hardened-desktop/air-gapped-containers.md

@@ -23,16 +23,17 @@ Use air-gapped containers if:
 
 ## How air-gapped containers work
 
-Air-gapped containers operate by intercepting container network traffic and applying proxy rules:
+`containersProxy` governs two distinct traffic paths:
 
-1. Traffic interception: Docker Desktop intercepts all outgoing network connections from containers
-1. Port filtering: Only traffic on specified ports (`transparentPorts`) is subject to proxy rules
-1. Rule evaluation: PAC file rules or static proxy settings determine how to handle each connection
-1. Connection handling: Traffic is allowed directly, routed through a proxy, or blocked based on the rules
+- Image pulls (always enforced): Docker Desktop hardwires `http.docker.internal:3128` as the daemon's proxy in `daemon.json` at VM startup, so all `docker pull` and Compose pull operations always go through `containersProxy`, including any PAC file rules.
+- Running container outbound traffic (opt-in): Docker Desktop intercepts container TCP connections and applies proxy rules only for ports listed in `transparentPorts`. Without it, running container traffic bypasses `containersProxy` entirely.
 
-Some important considerations include:
+> [!IMPORTANT]
+>
+> If you configure a PAC file under `containersProxy`, the PAC file must return an appropriate proxy server to connect to the registries where your images are hosted.
+
+Other considerations:
 
-- The existing `proxy` setting continues to apply to Docker Desktop application traffic on the host
 - If PAC file download fails, containers block requests to target URLs
 - Hostname is available for ports 80 and 443, but only IP addresses for other ports
 
@@ -65,7 +66,7 @@ Add the container proxy to your [`admin-settings.json` file](/manuals/enterprise
 
 ### Configuration parameters
 
-The `containersProxy` setting controls network policies applied to container traffic:
+The `containersProxy` setting controls network policies applied to `docker image pull` and, when `transparentPorts` is configured, running container outbound traffic:
 
 | Parameter | Description | Value |
 |-----------|-------------|-------|

content/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md

@@ -309,6 +309,11 @@ The following tables describe all available settings in the `admin-settings.json
 
 ### Proxy settings
 
+Docker Desktop has two distinct proxy settings with different scopes:
+
+- `proxy` (App Proxy): Governs Docker Desktop host-level traffic — the Desktop application, Docker CLI, and extensions. It also serves as a fallback for the daemon when `containersProxy` is not explicitly configured. Once `containersProxy` is set, `proxy` plays no role in daemon or container traffic.
+- [`containersProxy`](#container-proxy): Always governs `docker image pull`. All `docker image pull` and Compose pull operations go through `containersProxy`, including any PAC file rules. It also governs running container outbound traffic when `transparentPorts` is configured.
+
 | Parameter            | OS           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Version                                |
 | :------------------- | ------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
 | `proxy`              |              | If `mode` is set to `system` instead of `manual`, Docker Desktop gets the proxy values from the system and ignores any values set for `http`, `https` and `exclude`. Change `mode` to `manual` to manually configure proxy servers. If the proxy port is custom, specify it in the `http` or `https` property, for example `"https": "http://myotherproxy.com:4321"`. The `exclude` property specifies a comma-separated list of hosts and domains to bypass the proxy. |                                        |
@@ -332,7 +337,7 @@ The following tables describe all available settings in the `admin-settings.json
 
 | Parameter         | OS  | Description                                                                                                                                                                                                                                         | Version                                |
 | :---------------- | --- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
-| `containersProxy` |     | Creates air-gapped containers. For more information see [Air-Gapped Containers](../air-gapped-containers.md).                                                                                                                                       |  |
+| `containersProxy` |     | Configures the proxy for `docker image pull` (always enforced) and running container outbound traffic (enforced when `transparentPorts` is set). For more information see [Air-Gapped Containers](../air-gapped-containers.md). |  |
 | `pac`             |     | Specifies a PAC file URL. For example, `"pac": "http://containerproxy/proxy.pac"`.                                                                                                                                                                  |                                        |
 | `embeddedPac`     |     | Specifies an embedded PAC (Proxy Auto-config) script. For example, `"embeddedPac": "function FindProxyForURL(url, host) { return \"PROXY 192.168.92.1:2003\"; }"`. This setting takes precedence over HTTP, HTTPS, Proxy bypass and PAC server URL. |  |
 

content/manuals/enterprise/security/hardened-desktop/settings-management/settings-reference.md

@@ -400,7 +400,16 @@ Defines network addresses that containers should bypass when using proxy setting
 
 ### Air-gapped container proxy
 
-Configures an HTTP/HTTPS proxy for containers in air-gapped environments, providing controlled network access in offline or restricted network environments.
+Configures an HTTP/HTTPS proxy that governs two distinct traffic paths:
+
+- Daemon image pulls (always enforced): Docker Desktop always injects `http.docker.internal:3128` as the daemon's proxy in `daemon.json` at VM startup. All `docker pull` and Compose pull operations are routed through `containersProxy`, including any PAC file rules. This applies regardless of whether `transparentPorts` is configured.
+- Running container outbound traffic (opt-in): Container TCP traffic is only subject to `containersProxy` rules when `transparentPorts` is configured. Without it, running containers connect directly and PAC file rules do not apply to their outbound traffic.
+
+> [!IMPORTANT]
+>
+> If you configure a PAC file under `containersProxy`, the PAC file must return an appropriate proxy server to connect to the registries where your images are hosted.
+
+The [`proxy`](#proxy) setting governs Docker Desktop host-level traffic: the Desktop application, Docker CLI, and extensions. It serves as a fallback for the daemon only when `containersProxy` is not explicitly configured. Once `containersProxy` is set, `proxy` plays no role in daemon or container traffic.
 
 | Property | Value |
 |---|---|