From aaa12b9330f6b6b3455d3af62ad7a1083b04c8e9 Mon Sep 17 00:00:00 2001 From: aevesdocker Date: Thu, 9 Jul 2026 10:29:24 +0100 Subject: [PATCH 1/7] Desktop: containerProxy Signed-off-by: aevesdocker --- .../desktop/features/networking/_index.md | 9 ++++--- .../settings-and-maintenance/settings.md | 4 ++-- .../hardened-desktop/air-gapped-containers.md | 24 +++++++++++++++---- .../configure-json-file.md | 7 +++++- .../settings-management/settings-reference.md | 11 ++++++++- 5 files changed, 43 insertions(+), 12 deletions(-) diff --git a/content/manuals/desktop/features/networking/_index.md b/content/manuals/desktop/features/networking/_index.md index fa3d52d0f13b..cc01d5abc11b 100644 --- a/content/manuals/desktop/features/networking/_index.md +++ b/content/manuals/desktop/features/networking/_index.md @@ -65,12 +65,15 @@ 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). Docker Desktop has two distinct proxy paths: + +- **Containers proxy** (`containersProxy`): 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 go through the Containers proxy, including any PAC file rules. Running container outbound traffic also goes through this path when air-gapped container enforcement is enabled. +- **Docker Desktop proxy** (App Proxy): Governs Docker Desktop host-level traffic — the Desktop application, Docker CLI, and extensions — via `com.docker.backend.exe`. It acts as a fallback for daemon image pulls only when the Containers proxy is not explicitly configured. 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. +- Daemon image pulls are forwarded through `http.docker.internal:3128`, which enforces Containers proxy rules. +- The Containers 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. Note that: diff --git a/content/manuals/desktop/settings-and-maintenance/settings.md b/content/manuals/desktop/settings-and-maintenance/settings.md index 7f74e9f69bc8..939a21385479 100644 --- a/content/manuals/desktop/settings-and-maintenance/settings.md +++ b/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 Docker Desktop application, Docker CLI, extensions, and error diagnostics. It also acts as a fallback for daemon image pulls when **Containers proxy** is not explicitly configured. Once Containers proxy is set, this setting plays no role in daemon or container traffic. | 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 daemon image pulls (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, it must explicitly allow Docker registry endpoints or image pulls will fail. | Proxy mode | Description | |------------|-------------| diff --git a/content/manuals/enterprise/security/hardened-desktop/air-gapped-containers.md b/content/manuals/enterprise/security/hardened-desktop/air-gapped-containers.md index 70393db82b0a..2e4c926e27be 100644 --- a/content/manuals/enterprise/security/hardened-desktop/air-gapped-containers.md +++ b/content/manuals/enterprise/security/hardened-desktop/air-gapped-containers.md @@ -23,16 +23,30 @@ 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 +**Daemon image pulls (always enforced)** + +Docker Desktop always injects `http.docker.internal:3128` as the daemon's proxy into `daemon.json` at VM startup. All `docker pull` and Compose pull operations are always routed through `containersProxy` — including any PAC file rules — regardless of whether `transparentPorts` is configured. The App Proxy (`proxy` setting) does not govern daemon image pulls; it only serves as a fallback for the daemon when `containersProxy` is not explicitly configured. + +**Running container outbound traffic (opt-in)** + +Air-gapped container enforcement for running container TCP traffic operates by intercepting container network connections and applying proxy rules: + +1. Traffic interception: Docker Desktop intercepts outgoing network connections from running 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 -Some important considerations include: +Without `transparentPorts` configured, running container traffic bypasses `containersProxy` entirely and connects directly. + +> [!IMPORTANT] +> +> If you configure a PAC file under `containersProxy`, it must explicitly allow Docker registry endpoints (such as `registry-1.docker.io`, `auth.docker.io`, and `production.cloudflare.docker.com`) or all `docker pull` and Compose pull operations will fail. This applies even if you have not configured `transparentPorts`, because daemon image pulls always go through `containersProxy`. + +Some additional considerations: -- The existing `proxy` setting continues to apply to Docker Desktop application traffic on the host +- The `proxy` setting continues to apply to Docker Desktop application traffic, Docker CLI, and extensions 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 +79,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 daemon image pulls and, when `transparentPorts` is configured, running container outbound traffic: | Parameter | Description | Value | |-----------|-------------|-------| diff --git a/content/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md b/content/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md index 92d55ac7d988..ea0d1709c3d6 100644 --- a/content/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md +++ b/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`**: Always governs daemon image pulls via `http.docker.internal:3128`, which Docker Desktop hardwires into `daemon.json` at VM startup. All `docker 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 daemon image pulls (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. | | diff --git a/content/manuals/enterprise/security/hardened-desktop/settings-management/settings-reference.md b/content/manuals/enterprise/security/hardened-desktop/settings-management/settings-reference.md index eb703caa9fd3..1e1fea62b911 100644 --- a/content/manuals/enterprise/security/hardened-desktop/settings-management/settings-reference.md +++ b/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 explicitly allow Docker registry endpoints (such as `registry-1.docker.io`, `auth.docker.io`, and `production.cloudflare.docker.com`) or all image pulls will fail. This is expected behavior — the PAC file applies to daemon image pulls unconditionally. + +The `proxy` (App 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, the App Proxy plays no role in daemon or container traffic. | Property | Value | |---|---| From 553dbcdf8d2785deb5984fbd4cc3667514f41356 Mon Sep 17 00:00:00 2001 From: aevesdocker Date: Thu, 9 Jul 2026 10:37:48 +0100 Subject: [PATCH 2/7] tweaks Signed-off-by: aevesdocker --- .../desktop/features/networking/_index.md | 9 ++++---- .../settings-and-maintenance/settings.md | 2 +- .../hardened-desktop/air-gapped-containers.md | 21 ++++--------------- 3 files changed, 9 insertions(+), 23 deletions(-) diff --git a/content/manuals/desktop/features/networking/_index.md b/content/manuals/desktop/features/networking/_index.md index cc01d5abc11b..c2a6008f666c 100644 --- a/content/manuals/desktop/features/networking/_index.md +++ b/content/manuals/desktop/features/networking/_index.md @@ -65,15 +65,14 @@ 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). Docker Desktop has two distinct proxy paths: +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). -- **Containers proxy** (`containersProxy`): 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 go through the Containers proxy, including any PAC file rules. Running container outbound traffic also goes through this path when air-gapped container enforcement is enabled. -- **Docker Desktop proxy** (App Proxy): Governs Docker Desktop host-level traffic — the Desktop application, Docker CLI, and extensions — via `com.docker.backend.exe`. It acts as a fallback for daemon image pulls only when the Containers proxy is not explicitly configured. +Docker Desktop routes traffic through two separate proxies. The **Containers proxy** governs all daemon image pulls via `http.docker.internal:3128`, which Docker Desktop hardwires into `daemon.json` at startup, 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 daemon pulls only when the Containers proxy is not explicitly configured. When a proxy is enabled: -- Daemon image pulls are forwarded through `http.docker.internal:3128`, which enforces Containers proxy rules. -- The Containers proxy then connects either directly to the internet or through your upstream proxy, depending on your configuration and adding authentication if necessary. +- The backend process forwards network requests through the proxy, for example for `docker pull`. +- The proxy connects either directly to the internet or through your upstream proxy, depending on your configuration, adding authentication if necessary. - Docker Desktop then downloads the requested images or data through the proxy as usual. Note that: diff --git a/content/manuals/desktop/settings-and-maintenance/settings.md b/content/manuals/desktop/settings-and-maintenance/settings.md index 939a21385479..65b017ae3b1d 100644 --- a/content/manuals/desktop/settings-and-maintenance/settings.md +++ b/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 Docker Desktop host-level traffic: signing in to Docker, the Docker Desktop application, Docker CLI, extensions, and error diagnostics. It also acts as a fallback for daemon image pulls when **Containers proxy** is not explicitly configured. Once Containers proxy is set, this setting plays no role in daemon or container traffic. +Used for Docker Desktop host-level traffic: signing in to Docker, the Desktop application, CLI, and extensions. Acts as a fallback for daemon image pulls only when **Containers proxy** is not configured. | Proxy mode | Description | |------------|-------------| diff --git a/content/manuals/enterprise/security/hardened-desktop/air-gapped-containers.md b/content/manuals/enterprise/security/hardened-desktop/air-gapped-containers.md index 2e4c926e27be..0ef28e1ad306 100644 --- a/content/manuals/enterprise/security/hardened-desktop/air-gapped-containers.md +++ b/content/manuals/enterprise/security/hardened-desktop/air-gapped-containers.md @@ -25,28 +25,15 @@ Use air-gapped containers if: `containersProxy` governs two distinct traffic paths: -**Daemon image pulls (always enforced)** - -Docker Desktop always injects `http.docker.internal:3128` as the daemon's proxy into `daemon.json` at VM startup. All `docker pull` and Compose pull operations are always routed through `containersProxy` — including any PAC file rules — regardless of whether `transparentPorts` is configured. The App Proxy (`proxy` setting) does not govern daemon image pulls; it only serves as a fallback for the daemon when `containersProxy` is not explicitly configured. - -**Running container outbound traffic (opt-in)** - -Air-gapped container enforcement for running container TCP traffic operates by intercepting container network connections and applying proxy rules: - -1. Traffic interception: Docker Desktop intercepts outgoing network connections from running 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 - -Without `transparentPorts` configured, running container traffic bypasses `containersProxy` entirely and connects directly. +- **Daemon 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. > [!IMPORTANT] > -> If you configure a PAC file under `containersProxy`, it must explicitly allow Docker registry endpoints (such as `registry-1.docker.io`, `auth.docker.io`, and `production.cloudflare.docker.com`) or all `docker pull` and Compose pull operations will fail. This applies even if you have not configured `transparentPorts`, because daemon image pulls always go through `containersProxy`. +> If you configure a PAC file under `containersProxy`, it must explicitly allow Docker registry endpoints (such as `registry-1.docker.io` and `auth.docker.io`) or all image pulls will fail — including `docker pull` and Compose pulls — because daemon image pulls always go through `containersProxy`. -Some additional considerations: +Other considerations: -- The `proxy` setting continues to apply to Docker Desktop application traffic, Docker CLI, and extensions 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 From 6b3fdf9ef0638532cbf74fcce012dd19e77b4a88 Mon Sep 17 00:00:00 2001 From: aevesdocker Date: Thu, 9 Jul 2026 10:48:45 +0100 Subject: [PATCH 3/7] edits --- .../manuals/desktop/settings-and-maintenance/settings.md | 2 +- .../security/hardened-desktop/air-gapped-containers.md | 4 ++-- .../settings-management/configure-json-file.md | 4 ++-- .../settings-management/settings-reference.md | 8 ++++---- 4 files changed, 9 insertions(+), 9 deletions(-) diff --git a/content/manuals/desktop/settings-and-maintenance/settings.md b/content/manuals/desktop/settings-and-maintenance/settings.md index 65b017ae3b1d..a34df35843a9 100644 --- a/content/manuals/desktop/settings-and-maintenance/settings.md +++ b/content/manuals/desktop/settings-and-maintenance/settings.md @@ -137,7 +137,7 @@ Used for Docker Desktop host-level traffic: signing in to Docker, the Desktop ap #### Containers proxy -Used for daemon image pulls (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, it must explicitly allow Docker registry endpoints or image pulls will fail. +Used for daemon image pulls (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, it must explicitly allow Docker registry endpoints or image pulls fail. | Proxy mode | Description | |------------|-------------| diff --git a/content/manuals/enterprise/security/hardened-desktop/air-gapped-containers.md b/content/manuals/enterprise/security/hardened-desktop/air-gapped-containers.md index 0ef28e1ad306..5b0b4389c0c5 100644 --- a/content/manuals/enterprise/security/hardened-desktop/air-gapped-containers.md +++ b/content/manuals/enterprise/security/hardened-desktop/air-gapped-containers.md @@ -25,8 +25,8 @@ Use air-gapped containers if: `containersProxy` governs two distinct traffic paths: -- **Daemon 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. +- Daemon 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. > [!IMPORTANT] > diff --git a/content/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md b/content/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md index ea0d1709c3d6..e79cebae6b46 100644 --- a/content/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md +++ b/content/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md @@ -311,8 +311,8 @@ The following tables describe all available settings in the `admin-settings.json 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`**: Always governs daemon image pulls via `http.docker.internal:3128`, which Docker Desktop hardwires into `daemon.json` at VM startup. All `docker pull` and Compose pull operations go through `containersProxy`, including any PAC file rules. It also governs running container outbound traffic when `transparentPorts` is configured. +- `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 daemon image pulls via `http.docker.internal:3128`, which Docker Desktop hardwires into `daemon.json` at VM startup. All `docker 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 | | :------------------- | ------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | diff --git a/content/manuals/enterprise/security/hardened-desktop/settings-management/settings-reference.md b/content/manuals/enterprise/security/hardened-desktop/settings-management/settings-reference.md index 1e1fea62b911..b38636e80125 100644 --- a/content/manuals/enterprise/security/hardened-desktop/settings-management/settings-reference.md +++ b/content/manuals/enterprise/security/hardened-desktop/settings-management/settings-reference.md @@ -402,14 +402,14 @@ Defines network addresses that containers should bypass when using proxy setting 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. +- 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 explicitly allow Docker registry endpoints (such as `registry-1.docker.io`, `auth.docker.io`, and `production.cloudflare.docker.com`) or all image pulls will fail. This is expected behavior — the PAC file applies to daemon image pulls unconditionally. +> If you configure a PAC file under `containersProxy`, the PAC file must explicitly allow Docker registry endpoints (such as `registry-1.docker.io`, `auth.docker.io`, and `production.cloudflare.docker.com`) or all image pulls fail. This is expected behavior - the PAC file applies to daemon image pulls unconditionally. -The `proxy` (App 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, the App Proxy plays no role in daemon or container traffic. +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 | |---|---| From fd3be1224c2eb4e4ec9548e68a90ce651980939b Mon Sep 17 00:00:00 2001 From: aevesdocker Date: Thu, 9 Jul 2026 14:35:38 +0100 Subject: [PATCH 4/7] sme review --- content/manuals/desktop/features/networking/_index.md | 8 +------- .../manuals/desktop/settings-and-maintenance/settings.md | 4 ++-- .../security/hardened-desktop/air-gapped-containers.md | 4 ++-- .../settings-management/configure-json-file.md | 4 ++-- .../settings-management/settings-reference.md | 2 +- 5 files changed, 8 insertions(+), 14 deletions(-) diff --git a/content/manuals/desktop/features/networking/_index.md b/content/manuals/desktop/features/networking/_index.md index c2a6008f666c..2746c41d79e9 100644 --- a/content/manuals/desktop/features/networking/_index.md +++ b/content/manuals/desktop/features/networking/_index.md @@ -67,13 +67,7 @@ Host firewalls can permit or deny inbound connections by filtering on `com.docke 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). -Docker Desktop routes traffic through two separate proxies. The **Containers proxy** governs all daemon image pulls via `http.docker.internal:3128`, which Docker Desktop hardwires into `daemon.json` at startup, 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 daemon pulls only when the Containers proxy is not explicitly configured. - -When a proxy is enabled: - -- The backend process forwards network requests through the proxy, for example for `docker pull`. -- The proxy connects either directly to the internet or through your upstream proxy, depending on your configuration, 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: diff --git a/content/manuals/desktop/settings-and-maintenance/settings.md b/content/manuals/desktop/settings-and-maintenance/settings.md index a34df35843a9..ffc00c881d39 100644 --- a/content/manuals/desktop/settings-and-maintenance/settings.md +++ b/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 Docker Desktop host-level traffic: signing in to Docker, the Desktop application, CLI, and extensions. Acts as a fallback for daemon image pulls only when **Containers proxy** is not configured. +Used for Docker Desktop host-level traffic: signing in to Docker, the Desktop application, CLI, and extensions. Acts as a fallback for docker image pulls only when [Containers proxy](#containers-proxy) is not configured. | Proxy mode | Description | |------------|-------------| @@ -137,7 +137,7 @@ Used for Docker Desktop host-level traffic: signing in to Docker, the Desktop ap #### Containers proxy -Used for daemon image pulls (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, it must explicitly allow Docker registry endpoints or image pulls fail. +Used for docker image pulls (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 | |------------|-------------| diff --git a/content/manuals/enterprise/security/hardened-desktop/air-gapped-containers.md b/content/manuals/enterprise/security/hardened-desktop/air-gapped-containers.md index 5b0b4389c0c5..0abbaf4a4825 100644 --- a/content/manuals/enterprise/security/hardened-desktop/air-gapped-containers.md +++ b/content/manuals/enterprise/security/hardened-desktop/air-gapped-containers.md @@ -30,7 +30,7 @@ Use air-gapped containers if: > [!IMPORTANT] > -> If you configure a PAC file under `containersProxy`, it must explicitly allow Docker registry endpoints (such as `registry-1.docker.io` and `auth.docker.io`) or all image pulls will fail — including `docker pull` and Compose pulls — because daemon image pulls always go through `containersProxy`. +> If you configure a PAC file under `containersProxy`, ensure it returns an appropriate proxy server for Docker registry endpoints (such as `registry-1.docker.io` and `auth.docker.io`). If the PAC file does not handle these endpoints, all image pulls will fail — including `docker pull` and Compose pulls — because docker image pulls always go through `containersProxy`. Other considerations: @@ -66,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 daemon image pulls and, when `transparentPorts` is configured, running container outbound traffic: +The `containersProxy` setting controls network policies applied to docker image pulls and, when `transparentPorts` is configured, running container outbound traffic: | Parameter | Description | Value | |-----------|-------------|-------| diff --git a/content/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md b/content/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md index e79cebae6b46..f30df0099df3 100644 --- a/content/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md +++ b/content/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md @@ -312,7 +312,7 @@ The following tables describe all available settings in the `admin-settings.json 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 daemon image pulls via `http.docker.internal:3128`, which Docker Desktop hardwires into `daemon.json` at VM startup. All `docker pull` and Compose pull operations go through `containersProxy`, including any PAC file rules. It also governs running container outbound traffic when `transparentPorts` is configured. +- [`containersProxy`](#container-proxy): Always governs docker image pulls. All `docker 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 | | :------------------- | ------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | @@ -337,7 +337,7 @@ Docker Desktop has two distinct proxy settings with different scopes: | Parameter | OS | Description | Version | | :---------------- | --- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | -| `containersProxy` | | Configures the proxy for daemon image pulls (always enforced) and running container outbound traffic (enforced when `transparentPorts` is set). For more information see [Air-Gapped Containers](../air-gapped-containers.md). | | +| `containersProxy` | | Configures the proxy for docker image pulls (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. | | diff --git a/content/manuals/enterprise/security/hardened-desktop/settings-management/settings-reference.md b/content/manuals/enterprise/security/hardened-desktop/settings-management/settings-reference.md index b38636e80125..a8a852e7d226 100644 --- a/content/manuals/enterprise/security/hardened-desktop/settings-management/settings-reference.md +++ b/content/manuals/enterprise/security/hardened-desktop/settings-management/settings-reference.md @@ -407,7 +407,7 @@ Configures an HTTP/HTTPS proxy that governs two distinct traffic paths: > [!IMPORTANT] > -> If you configure a PAC file under `containersProxy`, the PAC file must explicitly allow Docker registry endpoints (such as `registry-1.docker.io`, `auth.docker.io`, and `production.cloudflare.docker.com`) or all image pulls fail. This is expected behavior - the PAC file applies to daemon image pulls unconditionally. +> If you configure a PAC file under `containersProxy`, ensure it returns an appropriate proxy server for Docker registry endpoints. If the PAC file does not handle these endpoints, all image pulls will fail because docker image pulls always go through `containersProxy`. 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. From 156cceaf20b2352af2de32ef8429f97ea3d09870 Mon Sep 17 00:00:00 2001 From: aevesdocker Date: Thu, 9 Jul 2026 14:43:03 +0100 Subject: [PATCH 5/7] edits --- content/manuals/desktop/features/networking/_index.md | 2 +- content/manuals/desktop/settings-and-maintenance/settings.md | 2 +- .../security/hardened-desktop/air-gapped-containers.md | 4 ++-- .../settings-management/settings-reference.md | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/content/manuals/desktop/features/networking/_index.md b/content/manuals/desktop/features/networking/_index.md index 2746c41d79e9..4f69cc9800fb 100644 --- a/content/manuals/desktop/features/networking/_index.md +++ b/content/manuals/desktop/features/networking/_index.md @@ -67,7 +67,7 @@ Host firewalls can permit or deny inbound connections by filtering on `com.docke 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). -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. +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: diff --git a/content/manuals/desktop/settings-and-maintenance/settings.md b/content/manuals/desktop/settings-and-maintenance/settings.md index ffc00c881d39..d78cfbc6813f 100644 --- a/content/manuals/desktop/settings-and-maintenance/settings.md +++ b/content/manuals/desktop/settings-and-maintenance/settings.md @@ -137,7 +137,7 @@ Used for Docker Desktop host-level traffic: signing in to Docker, the Desktop ap #### Containers proxy -Used for docker image pulls (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. +Used for `docker image pulls` (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 | |------------|-------------| diff --git a/content/manuals/enterprise/security/hardened-desktop/air-gapped-containers.md b/content/manuals/enterprise/security/hardened-desktop/air-gapped-containers.md index 0abbaf4a4825..699a414a75f1 100644 --- a/content/manuals/enterprise/security/hardened-desktop/air-gapped-containers.md +++ b/content/manuals/enterprise/security/hardened-desktop/air-gapped-containers.md @@ -25,12 +25,12 @@ Use air-gapped containers if: `containersProxy` governs two distinct traffic paths: -- Daemon 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. +- 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. > [!IMPORTANT] > -> If you configure a PAC file under `containersProxy`, ensure it returns an appropriate proxy server for Docker registry endpoints (such as `registry-1.docker.io` and `auth.docker.io`). If the PAC file does not handle these endpoints, all image pulls will fail — including `docker pull` and Compose pulls — because docker image pulls always go through `containersProxy`. +> 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: diff --git a/content/manuals/enterprise/security/hardened-desktop/settings-management/settings-reference.md b/content/manuals/enterprise/security/hardened-desktop/settings-management/settings-reference.md index a8a852e7d226..08a741de3973 100644 --- a/content/manuals/enterprise/security/hardened-desktop/settings-management/settings-reference.md +++ b/content/manuals/enterprise/security/hardened-desktop/settings-management/settings-reference.md @@ -407,7 +407,7 @@ Configures an HTTP/HTTPS proxy that governs two distinct traffic paths: > [!IMPORTANT] > -> If you configure a PAC file under `containersProxy`, ensure it returns an appropriate proxy server for Docker registry endpoints. If the PAC file does not handle these endpoints, all image pulls will fail because docker image pulls always go through `containersProxy`. +> 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. From e7953408b754b6dc971ff3e3576be57a45bf3f68 Mon Sep 17 00:00:00 2001 From: aevesdocker Date: Thu, 9 Jul 2026 14:52:33 +0100 Subject: [PATCH 6/7] vale --- content/manuals/desktop/settings-and-maintenance/settings.md | 2 +- .../security/hardened-desktop/air-gapped-containers.md | 2 +- .../settings-management/configure-json-file.md | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/content/manuals/desktop/settings-and-maintenance/settings.md b/content/manuals/desktop/settings-and-maintenance/settings.md index d78cfbc6813f..e1bc9661d40e 100644 --- a/content/manuals/desktop/settings-and-maintenance/settings.md +++ b/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 Docker Desktop host-level traffic: signing in to Docker, the Desktop application, CLI, and extensions. Acts as a fallback for docker image pulls only when [Containers proxy](#containers-proxy) is not configured. +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 | |------------|-------------| diff --git a/content/manuals/enterprise/security/hardened-desktop/air-gapped-containers.md b/content/manuals/enterprise/security/hardened-desktop/air-gapped-containers.md index 699a414a75f1..36eb900d1e10 100644 --- a/content/manuals/enterprise/security/hardened-desktop/air-gapped-containers.md +++ b/content/manuals/enterprise/security/hardened-desktop/air-gapped-containers.md @@ -66,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 docker image pulls and, when `transparentPorts` is configured, running container outbound traffic: +The `containersProxy` setting controls network policies applied to `docker image pull` and, when `transparentPorts` is configured, running container outbound traffic: | Parameter | Description | Value | |-----------|-------------|-------| diff --git a/content/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md b/content/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md index f30df0099df3..06a018c865d3 100644 --- a/content/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md +++ b/content/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md @@ -312,7 +312,7 @@ The following tables describe all available settings in the `admin-settings.json 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 pulls. All `docker pull` and Compose pull operations go through `containersProxy`, including any PAC file rules. It also governs running container outbound traffic when `transparentPorts` is configured. +- [`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 | | :------------------- | ------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | @@ -337,7 +337,7 @@ Docker Desktop has two distinct proxy settings with different scopes: | Parameter | OS | Description | Version | | :---------------- | --- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | -| `containersProxy` | | Configures the proxy for docker image pulls (always enforced) and running container outbound traffic (enforced when `transparentPorts` is set). 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. | | From ef7fe10becddf70c8e15d706e2cbdc9eec2eac7a Mon Sep 17 00:00:00 2001 From: aevesdocker Date: Thu, 9 Jul 2026 15:00:25 +0100 Subject: [PATCH 7/7] edit --- content/manuals/desktop/settings-and-maintenance/settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/manuals/desktop/settings-and-maintenance/settings.md b/content/manuals/desktop/settings-and-maintenance/settings.md index e1bc9661d40e..71b9c2951f08 100644 --- a/content/manuals/desktop/settings-and-maintenance/settings.md +++ b/content/manuals/desktop/settings-and-maintenance/settings.md @@ -137,7 +137,7 @@ Used for Docker Desktop host-level traffic: signing in to Docker, the Desktop ap #### Containers proxy -Used for `docker image pulls` (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. +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 | |------------|-------------|