Configure Settings Management with a JSON file

{{< summary-bar feature_name="Hardened Docker Desktop" >}}

Settings Management lets you configure and enforce Docker Desktop settings across your organization using an admin-settings.json file. This standardizes Docker Desktop environments and ensures consistent configurations for all users.

Prerequisites

Before you begin, make sure you have:

• Enforce sign-in for your organization
• A Docker Business subscription

Docker Desktop only applies settings from the admin-settings.json file when both authentication and Docker Business license checks succeed.

[!IMPORTANT]

Users must be signed in and part of a Docker Business organization. If either condition isn't met, the settings file is ignored.

Step one: Create the settings file

You can create the admin-settings.json file in two ways:

• Use the --admin-settings installer flag to auto-generate the file:
  • macOS installation guide
  • Windows installation guide
• Create it manually (UTF-8 without BOM) and place it in the following locations:
  • Mac: /Library/Application\ Support/com.docker.docker/admin-settings.json
  • Windows: C:\ProgramData\DockerDesktop\admin-settings.json
  • Linux: /usr/share/docker-desktop/admin-settings.json

[!IMPORTANT]

Place the file in a protected directory to prevent unauthorized changes. Use Mobile Device Management (MDM) tools like Jamf to distribute the file at scale across your organization.

Step two: Configure settings

[!TIP]

For a complete list of available settings, their supported platforms, and which configuration methods they work with, see the Settings reference.

The admin-settings.json file uses structured keys to define configurable settings and whether values are enforced.

Each setting supports a locked field that controls user permissions:

• When locked is set to true, users can't change that value in Docker Desktop, the CLI, or config files.
• When locked is set to false, the value acts like a default suggestion and users can still update it.

Settings where locked is set to false are ignored on existing installs if a user has already customized that value in settings-store.json, settings.json, or daemon.json.

Grouped settings

Docker Desktop groups some settings together with a single toggle that controls the entire section. These include:

• Enhanced Container Isolation (ECI): Uses a main toggle (enhancedContainerIsolation) that enables/disables the entire feature, with sub-settings for specific configurations
• Kubernetes: Uses a main toggle (kubernetes.enabled) with sub-settings for cluster configuration
• Docker Scout: Groups settings under the scout object

When configuring grouped settings:

1. Set the main toggle to enable the feature
2. Configure sub-settings within that group
3. When you lock the main toggle, users cannot modify any settings in that group

Example for enhancedContainerIsolation:

"enhancedContainerIsolation": {
  "locked": true,  // This locks the entire ECI section
  "value": true,   // This enables ECI
  "dockerSocketMount": {  // These are sub-settings
    "imageList": {
      "images": ["docker.io/testcontainers/ryuk:*"]
    }
  }
}

Example admin-settings.json file

The following sample is an admin-settings.json file with common enterprise settings configured. You can use this example as a template with the admin-settings.json configurations:

{
  "configurationFileVersion": 2,
  "exposeDockerAPIOnTCP2375": {
    "locked": true,
    "value": false
  },
  "proxy": {
    "locked": true,
    "mode": "system",
    "http": "",
    "https": "",
    "exclude": [],
    "windowsDockerdPort": 65000,
    "enableKerberosNtlm": false,
    "pac": "",
    "embeddedPac": ""
  },
  "containersProxy": {
    "locked": true,
    "mode": "manual",
    "http": "",
    "https": "",
    "exclude": [],
    "pac":"",
    "embeddedPac": "",
    "transparentPorts": ""
  },
  "enhancedContainerIsolation": {
    "locked": true,
    "value": true,
    "dockerSocketMount": {
      "imageList": {
        "images": [
          "docker.io/localstack/localstack:*",
          "docker.io/testcontainers/ryuk:*"
        ]
      },
      "commandList": {
        "type": "deny",
        "commands": ["push"]
      }
    }
  },
  "linuxVM": {
    "wslEngineEnabled": {
      "locked": false,
      "value": false
    },
    "dockerDaemonOptions": {
      "locked": false,
      "value":"{\"debug\": false}"
    },
    "vpnkitCIDR": {
      "locked": false,
      "value":"192.168.65.0/24"
    }
  },
  "kubernetes": {
     "locked": false,
     "enabled": false,
     "showSystemContainers": false,
     "imagesRepository": ""
  },
  "windowsContainers": {
    "dockerDaemonOptions": {
      "locked": false,
      "value":"{\"debug\": false}"
    }
  },
  "disableUpdate": {
    "locked": false,
    "value": false
  },
  "analyticsEnabled": {
    "locked": false,
    "value": true
  },
  "extensionsEnabled": {
    "locked": true,
    "value": false
  },
  "scout": {
    "locked": false,
    "sbomIndexing": true,
    "useBackgroundIndexing": true
  },
  "allowBetaFeatures": {
    "locked": false,
    "value": false
  },
  "blockDockerLoad": {
    "locked": false,
    "value": true
  },
  "filesharingAllowedDirectories": [
    {
      "path": "$HOME",
      "sharedByDefault": true
    },
    {
      "path":"$TMP",
      "sharedByDefault": false
    }
  ],
  "useVirtualizationFrameworkVirtioFS": {
    "locked": true,
    "value": true
  },
  "useVirtualizationFrameworkRosetta": {
    "locked": true,
    "value": true
  },
  "useGrpcfuse": {
    "locked": true,
    "value": true
  },
  "displayedOnboarding": {
    "locked": true,
    "value": true
  },
  "desktopTerminalEnabled": {
    "locked": false,
    "value": false
  },
  "enableInference": {
    "locked": false,
    "value": true
  },
  "enableInferenceTCP": {
    "locked": false,
    "value": true
  },
  "enableInferenceTCPPort": {
    "locked": true,
    "value": 12434
  },
  "enableInferenceCORS": {
    "locked": true,
    "value": ""
  },
  "enableInferenceGPUVariant": {
    "locked": true,
    "value": true
  },
  "portBindingBehavior": {
    "locked": true,
    "value": "default-port-binding"
  }
}

Step three: Apply the settings

Settings take effect after Docker Desktop restarts and the user signs in.

For new installations:

1. Launch Docker Desktop.
2. Sign in with your Docker account.

For existing installations:

1. Quit Docker Desktop completely.
2. Relaunch Docker Desktop.

[!IMPORTANT]

You must fully quit and reopen Docker Desktop. Restarting from the menu isn't sufficient.

admin-settings.json configurations

The following tables describe all available settings in the admin-settings.json file.

[!NOTE]

Some settings are platform-specific or require minimum Docker Desktop versions. Check the Version column for requirements.

General settings

Extensions

File sharing and emulation

Docker Scout

Proxy settings

Container proxy

Linux VM settings

Windows containers

[!NOTE]

This setting is not available to configure via the Docker Admin Console.

Kubernetes settings

[!NOTE]

When using imagesRepository with Enhanced Container Isolation (ECI), add these images to the ECI Docker socket mount image list:

[imagesRepository]/desktop-cloud-provider-kind: [imagesRepository]/desktop-containerd-registry-mirror:

These containers mount the Docker socket, so you must add them to the ECI images list. Otherwise, ECI blocks the mount and Kubernetes won't start.

Networking settings

For more information, see Networking.

AI settings

Beta features

[!IMPORTANT]

For Docker Desktop versions 4.41 and earlier, some of these settings lived under the Experimental features tab on the Features in development page.

Enhanced Container Isolation