Configuring a managed user environment
In enterprise environments, administrators can enforce specific configuration values that users are unable to override. This capability allows them to manage configurations, such as proxy servers, telemetry policies, and security policies, ensuring users operate within a controlled environment. Administrators can review and edit the configurations in the user settings file before applying the changes globally to all enterprise users.
How it works
Podman Desktop supports three types of configuration:
- User configuration: Values that users can change in
settings.jsonor through the UI. - Managed defaults: Administrator-provided values in
default-settings.jsonthat supply initial settings. - Locked configuration: Keys in
locked.jsonthat must use managed values instead of user values.
On macOS, Podman Desktop also reads managed preference plists from /Library/Managed Preferences at startup.
The device plist supplies managed defaults and locks. The per-user plist supplies user values.
The JSON files remain supported alongside these plists.
For MDM setup, examples, and precedence rules, see Manage macOS settings with MDM.
Default settings
At startup, Podman Desktop copies managed defaults into the user configuration for keys without a user value.
On macOS, device plist values override default-settings.json values for the same key before this copy.
- Existing user values remain unchanged.
- Users can change these initial values unless the key is locked.
- The settings writer omits values that match the registered schema default from
settings.json.
This allows administrators to pre-configure settings for new users while respecting existing user preferences.
Locked settings
Keys in locked.json use managed values on every configuration read.
On macOS, the device plist can also supply a locked array. Podman Desktop combines both lock lists.
- The value comes from the managed defaults, including device plist overrides on macOS.
- The setting displays a lock icon or a Managed label in the UI.
- User values do not override the managed value.
Each locked key requires a value in the managed defaults. A lock without a managed value does not enforce a value.
Use locked settings when you need to enforce compliance, such as proxy servers or telemetry policies.
Configuration priority
Podman Desktop resolves configuration values in this order:
- Locked key with a managed value: Return the managed value.
- User value: Return the user configuration value, including defaults copied at startup.
- Built-in default: Use the default from the setting definition.
On macOS, per-user plist values override settings.json at startup. They cannot override locked managed values.
File locations
- Linux
- macOS
- Windows
User configuration
- Location:
~/.local/share/containers/podman-desktop/configuration/settings.json - Permissions: User read/write
- Purpose: Normal user settings configured through the UI
Managed defaults
- Location:
/usr/share/podman-desktop/default-settings.json - Permissions: Root only
- Purpose: Administrator-enforced configuration values
Locked configuration
- Location:
/usr/share/podman-desktop/locked.json - Permissions: Root only
- Purpose: List of configuration keys that are locked by an administrator
macOS also supports device and per-user managed preference plists. See macOS preference locations for their paths and roles.
User configuration
- Location:
~/.local/share/containers/podman-desktop/configuration/settings.json - Permissions: User read/write
- Purpose: Normal user settings configured through the UI
Managed defaults
- Location:
/Library/Application Support/io.podman_desktop.PodmanDesktop/default-settings.json - Permissions: Administrator only
- Purpose: Administrator-enforced configuration values
Locked configuration
- Location:
/Library/Application Support/io.podman_desktop.PodmanDesktop/locked.json - Permissions: Administrator only
- Purpose: List of configuration keys that are locked by an administrator
User configuration
- Location:
%USERPROFILE%\.local\share\containers\podman-desktop\configuration\settings.json - Permissions: User read/write
- Purpose: Normal user settings configured through the UI
Managed defaults
- Location:
%PROGRAMDATA%\Podman Desktop\default-settings.json - Permissions: Administrator only
- Purpose: Administrator-enforced configuration values
Locked configuration
- Location:
%PROGRAMDATA%\Podman Desktop\locked.json - Permissions: Administrator only
- Purpose: List of configuration keys that are locked by an administrator
Example: Enforcing corporate proxy and telemetry settings
This example demonstrates how an administrator can lock the proxy and telemetry configuration to enforce corporate policy.
Procedure
- Create a managed defaults file with corporate settings.
- Create a locked configuration file to enforce the corporate settings.
- Deploy both files to the appropriate system location.
- Restart Podman Desktop, the managed values will override user-configured values and enforce compliance.
User Configuration
The user has configured a local proxy in their settings:
{
"proxy.http": "https://127.0.0.1:8081",
"telemetry.enabled": true
}
Managed Defaults Configuration
The administrator creates a managed defaults file with corporate settings:
- Linux
- macOS
- Windows
{
"proxy.http": "http://corp-proxy.example.com:8080",
"telemetry.enabled": false
}
{
"proxy.http": "http://corp-proxy.example.com:8080",
"telemetry.enabled": false
}
{
"proxy.http": "http://corp-proxy.example.com:8080",
"telemetry.enabled": false
}
Locked Configuration
The administrator creates a locked configuration file to enforce these settings:
- Linux
- macOS
- Windows
{
"locked": ["proxy.http", "telemetry.enabled"]
}
{
"locked": ["proxy.http", "telemetry.enabled"]
}
{
"locked": ["proxy.http", "telemetry.enabled"]
}
Result
With this configuration in place, Podman Desktop returns:
{
"proxy.http": "http://corp-proxy.example.com:8080",
"telemetry.enabled": false
}
Key observations:
proxy.http- Returns managed value, user's local proxy is ignoredtelemetry.enabled- Returns managed value, user cannot enable telemetry (set to false)
As an administrator, you can implement several use cases to customize user settings based on your enterprise needs and apply those changes globally across your enterprise. For a comprehensive list of common use cases and examples, see Managed configuration use cases.
Deploying a managed configuration
Procedure
- Linux
- macOS
- Windows
Step 1: Create configuration files
Save the following files at /usr/share/podman-desktop/:
Managed defaults file:
{
"proxy.http": "http://proxy.corp.example.com:8080",
"telemetry.enabled": false
}
Locked configuration file:
{
"locked": ["proxy.http", "telemetry.enabled"]
}
Step 2: Deploy using a deployment tool
Choose a deployment tool: Ansible, Puppet, Chef, Salt, RPM/DEB packages, or shell scripts.
Step 3: Verify the deployment
-
Restart Podman Desktop.
-
Go to Help > Troubleshooting, and select the Logs tab to check for messages such as:
[Managed-by]: Loaded managed ... -
Verify that locked settings cannot be changed through the UI.
Step 1: Create configuration files
For a deployment through macOS managed preferences, follow Manage macOS settings with MDM. The procedure below deploys the JSON files.
Save the following files at /Library/Application Support/io.podman_desktop.PodmanDesktop/:
Managed defaults file:
{
"proxy.http": "http://proxy.corp.example.com:8080",
"telemetry.enabled": false
}
Locked configuration file:
{
"locked": ["proxy.http", "telemetry.enabled"]
}
Step 2: Deploy using a deployment tool
Choose a deployment tool: Jamf Pro, Microsoft Intune, Kandji, SimpleMDM, Ansible, or PKG installers.
Step 3: Verify the deployment
-
Restart Podman Desktop.
-
Go to Help > Troubleshooting, and select the Logs tab to check for messages such as:
[Managed-by]: Loaded managed ... -
Verify that locked settings cannot be changed through the UI.
Step 1: Create configuration files
Save the following files at %PROGRAMDATA%\Podman Desktop\:
Managed defaults file:
{
"proxy.http": "http://proxy.corp.example.com:8080",
"telemetry.enabled": false
}
Locked configuration file:
{
"locked": ["proxy.http", "telemetry.enabled"]
}
Step 2: Deploy using a deployment tool
Choose a deployment tool: Group Policy, Microsoft Intune, SCCM, Ansible, or PowerShell scripts.
Step 3: Verify the deployment
-
Restart Podman Desktop.
-
Go to Help > Troubleshooting, and select the Logs tab to check for messages such as:
[Managed-by]: Loaded managed ... -
Verify that locked settings cannot be changed through the UI.
Locked configuration impact on users
When a setting is locked:
- In the UI: The setting appears grayed out or displays a lock icon
- Editing settings.json: Changes to locked keys in the user's file are ignored
- Console output: Log messages indicate when locked values are being used
Users are notified when settings are managed by administrators, ensuring transparency about which settings they can and cannot control.