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

# Managed settings

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

Add optional settings only inside the completed universal profile from [required configuration](https://silmaril.security/docs/macos/managed-deployment.md#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](https://silmaril.security/docs/macos/verify.md).

| 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. |

## 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](https://silmaril.security/docs/macos/troubleshooting.md).

### 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

Requires Shadow mode for all protected agents. Shadow records decisions while work continues.

```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. Enable this only when your policy requires audit collection to stop.

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

### Agent exclusions

Excludes Codex and Cursor from endpoint protection. Use the exact agent identifiers you intend to exclude.

```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. The native classifier caps the effective wait at 8000 milliseconds. Values above 8000 remain accepted for compatibility but do not add waiting time. |
| `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. |

## Agent maintenance

Nightly 0.3.31 (1110) supports these settings as the minimum documented Nightly build. Confirm support for your selected channel before enabling maintenance. The complete profile keeps maintenance
off and the inference override empty. These keys do not add maintenance
capability to an older release.

| Key | Type | Default | Accepted values | Behavior and dependencies |
| - | - | - | - | - |
| `silmaril.agentMaintenanceEnabled` | Boolean | false | true or false | Enables automatic agent updates, Silmaril setup repair, and supported-session restart checks. Keep the template's forced false value to leave this under organization policy. Set true only when automatic maintenance is intended. |
| `silmaril.inferenceURL` | String | Empty | Empty, or a valid HTTPS URL on the trusted Dashboard origin using `/api/firewalls/<firewallID>/setup/endpoints/<endpointID>/inference` | Empty derives that maintenance endpoint from the Dashboard URL. Requires a valid Dashboard URL. User information, queries, fragments, and percent-encoded paths are rejected. An invalid forced override blocks maintenance without falling back to a saved local URL. |

## 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](https://silmaril.security/docs/macos/install.md#nightly).

See [updates and channels](https://silmaril.security/docs/macos/updates.md) to choose update ownership and verify a new build.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.