> ## Documentation Index
> Fetch the complete documentation index at: https://silmaril.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Managed settings

> Configure optional policy and look up the 17 supported MDM keys.

<a id="managed-settings" />

Add optional settings only inside the completed universal profile from [required configuration](/docs/macos/managed-deployment#managed-template). Silmaril checks forced organization policy first, then a saved local value, then the application default. If a managed key is later removed, the setting falls back to any saved local value.

Use these statuses to check policy application. Confirm active protection separately with [endpoint verification](/docs/macos/verify).

| Status | Meaning |
| - | - |
| Managed | Your organization owns the value, so the control is locked. |
| Applying | Silmaril is still applying the latest managed value. |
| Restart required | Restart the affected agent session before the new policy can protect new work. |
| Needs attention | The managed value is malformed, unavailable, or could not be applied. Correct it instead of expecting local fallback. |

<a id="optional-settings" />

## Optional settings

Add the settings required for your deployment inside the existing `mcx_preference_settings` dictionary, and add each key only once. Use the Dashboard URL or Firewall ID supplied by Silmaril when provided. To remove an optional setting, delete its complete key element and the following value element. To force Launch at Login Off, remove the complete `com.apple.loginitems.managed` payload before adding `silmaril.launchAtLoginEnabled` set to false.

Duplicate keys, a display name used where an ID is required, or Launch at Login forced off while the template login-items payload remains, leave the profile invalid or still forcing launch. Fix the XML, validate again, and replace the profile while preserving its identity. See [troubleshooting](/docs/macos/troubleshooting).

### Dashboard URL

Sets the supplied dashboard origin used by Fleet and Playground links.

```xml theme={"theme":"github-light-default"}
<key>silmaril.dashboardURL</key>
<string>REPLACE_WITH_SILMARIL_DASHBOARD_URL</string>
```

### Firewall ID

Routes audit records to the supplied Firewall.

```xml theme={"theme":"github-light-default"}
<key>silmaril.firewallID</key>
<string>REPLACE_WITH_SILMARIL_FIREWALL_ID</string>
```

### Protection mode

Makes Shadow the required mode for all protected agents.

```xml theme={"theme":"github-light-default"}
<key>silmaril.preferredFirewallMode</key>
<string>shadow</string>
```

### Request timeout

Wait up to 2500 milliseconds for a Firewall response.

```xml theme={"theme":"github-light-default"}
<key>silmaril.timeoutMS</key>
<integer>2500</integer>
```

### Audit Off

Stops new audit collection and uploads. Existing records remain.

```xml theme={"theme":"github-light-default"}
<key>silmaril.auditEnabled</key>
<false/>
```

### Agent exclusions

Excludes Codex and Cursor from endpoint protection.

```xml theme={"theme":"github-light-default"}
<key>silmaril.agentProtectionOptOuts</key>
<array>
  <string>codex</string>
  <string>cursor</string>
</array>
```

## Connection

| Key | Type | Default | Accepted values | Behavior and dependencies |
| - | - | - | - | - |
| `silmaril.apiURL` | String | App default | Valid HTTPS URL with a host | Connection URL for this deployment. Use the full URL supplied by Silmaril. Required as a forced, valid value when `silmaril.apiKey` is forced. |
| `silmaril.dashboardURL` | String | App default | HTTPS origin only. No path, query, or fragment | Dashboard root for Fleet and Playground links. It is never inferred from the API URL. |
| `silmaril.apiKey` | String | None | Non-empty string | Organization-managed API credential. Profile contents are readable by MDM administrators. Requires a forced, valid `silmaril.apiURL` in the same profile. Restrict profile access and rotate URL and key together. |
| `silmaril.timeoutMS` | Integer | 2500 | 250–10000 milliseconds | Maximum Firewall request wait. |
| `silmaril.firewallID` | String | Empty | 1–128 ASCII letters, digits, underscores, or hyphens | Routes audit records to the supplied Firewall. Use only when Silmaril supplies a Firewall ID. |

## Protection and audit

| Key | Type | Default | Accepted values | Behavior and dependencies |
| - | - | - | - | - |
| `silmaril.firewallEnabled` | Boolean | true | true or false | Endpoint protection master switch. |
| `silmaril.preferredFirewallMode` | String | shadow | shadow, warn, or block | Local value is the default for agents. A managed value is mandatory across agents. Legacy aliases Shadow, Enforce, and backend-controlled remain compatible. Use current values. |
| `silmaril.agentProtectionOptOuts` | Array of strings | Empty array | codex, copilot, claudeCode, openClaw, hermes, openCode, cursor, pi, vscode | Excludes named hosts from endpoint protection. Unknown managed identifiers are invalid. |
| `silmaril.protectionNotificationsEnabled` | Boolean | true | true or false | Controls the app notification preference. macOS notification permission is separate. |
| `silmaril.auditEnabled` | Boolean | true | true or false | Off stops new audit collection and uploads while preserving existing records. |

## Discovery and startup

| Key | Type | Default | Accepted values | Behavior and dependencies |
| - | - | - | - | - |
| `silmaril.mcpAutomaticDiscoveryEnabled` | Boolean | true | true or false | Controls automatic MCP discovery. |
| `silmaril.pausedMCPConfigurationIDs` | Array of strings | Empty array | MCP configuration ID strings | Pauses discovery for the listed configurations. Use the exact IDs shown under Paused MCP configurations in Settings on a pilot Mac. Do not use display names. |
| `silmaril.launchAtLoginEnabled` | Boolean | Current macOS registration | true or false | Controls the app-owned Launch at Login registration. To force Off, first remove the template's native login-items payload that forces launch On. |

## Updates

| Key | Type | Default | Accepted values | Behavior and dependencies |
| - | - | - | - | - |
| `SilmarilUpdateAuthority` | String | app | app or mdm | `mdm` disables the in-app updater. MDM installs PKG updates. A bare PKG or installed profile does not infer ownership. |
| `SilmarilUpdateChannel` | String | stable | stable or nightly | Selects the app feed when app-owned. Under MDM authority it does not install the chosen PKG. Restricted while `SilmarilUpdateAuthority` is `mdm`. |
| `SUEnableAutomaticChecks` | Boolean | true | true or false | Controls automatic app update checks. Relevant when update authority is app. |
| `SUAutomaticallyUpdate` | Boolean | false | true or false | Controls automatic installation of app-owned updates. Relevant when update authority is app. |

For current release and Nightly availability, see [Install](/docs/macos/install#nightly).