Managed settings (organization policy)¶

How managed settings work¶

Managed settings are read from a JSON file placed in a platform-specific system directory, a location that requires administrator or root privileges to write to. Because users can’t modify files in these locations, managed settings can’t be overridden by user configuration files, environment variables, or command-line arguments (except where explicitly noted).

Administrators typically deploy the managed settings file using MDM tools (Jamf, Intune, SCCM), configuration management systems (Ansible, Chef, Puppet), or manual deployment during device provisioning.

File locations¶

Place the managed-settings.json file in the following system directory for your operating system:

If the file doesn’t exist, the CLI runs in unmanaged mode and all user-level defaults apply.

Configuration schema¶

The managed-settings.json file must contain a version field. All top-level sections are optional.

{
  "version": "1.0",
  "permissions": { },
  "settings":    { },
  "required":    { },
  "defaults":    { },
  "files":       { },
  "ui":          { }
}

The version field must be "1.0".

{
  "permissions": {
    "onlyAllow": ["read", "write", "bash(git:*)", "skill(bundled:*)"],
    "deny": ["bash(rm:*)", "skill(remote:*)"],
    "defaultMode": "allow",
    "dangerouslyAllowAll": false
  }
}

{
  "settings": {
    "forceNoHistoryMode": true,
    "forceSandboxEnabled": true,
    "forceSandboxMode": "regular"
  }
}

{
  "required": {
    "minimumVersion": "0.26.0"
  }
}

{
  "defaults": {
    "connectionName": "prod",
    "profileName": "data-analyst",
    "theme": "dark"
  }
}

{
  "files": {
    "connectionsFile": "/etc/cortex/connections.toml",
    "mcpFile": "/etc/cortex/mcp.json"
  }
}

{
  "ui": {
    "showManagedBanner": true,
    "bannerText": "Managed by Acme IT - support: helpdesk@acme.com",
    "hideDangerousOptions": true
  }
}

Permission patterns¶

The onlyAllow and deny arrays in the permissions section accept patterns in two forms:

• Simple name: matches a named tool or feature category exactly. For example, "bash" or "read".

• Filtered name: type(filter). This matches a specific tool invocation or resource within a category. For example, "bash(git:*)" or "account(myorg-prod)".

Both forms support * (any characters) and ? (single character) glob wildcards. Matching is case-insensitive.

Permission evaluation¶

When the CLI decides whether a tool, skill, MCP server, or Snowflake account is permitted, it evaluates the following rules in order:

1. Managed ``deny`` matches: block. If any pattern in the managed settings deny array matches, access is denied. This can’t be overridden by profiles or user settings.

2. Profile ``deny`` matches: block. If any pattern in the active profile’s deny list matches, access is denied.

3. Managed ``onlyAllow`` is set and no pattern matches: block. If onlyAllow is configured in managed settings and the item doesn’t match any listed pattern, access is denied.

4. Profile ``onlyAllow`` is set for this type and no pattern matches: block. Profile onlyAllow is type-scoped: it only restricts types that are explicitly listed. If the profile lists skill(bundled:*) but says nothing about bash, bash access isn’t affected by the profile.

5. ``defaultMode`` determines the outcome. If defaultMode is "deny", access is blocked. If "allow" (the default), access is permitted.

Key guarantees:

• A profile can’t grant access that managed settings have explicitly denied.

• A profile can’t expand the managed settings allowlist.

• Profiles can only further restrict: they operate within the boundary that managed settings define.

Common policy examples¶

{
  "version": "1.0",
  "permissions": {
    "dangerouslyAllowAll": false,
    "defaultMode": "allow"
  },
  "required": {
    "minimumVersion": "0.26.0"
  },
  "ui": {
    "showManagedBanner": true,
    "bannerText": "Managed by Corporate IT - helpdesk@example.com"
  }
}

{
  "version": "1.0",
  "permissions": {
    "onlyAllow": [
      "account(mycompany-prod)",
      "account(mycompany-staging)"
    ],
    "defaultMode": "allow"
  }
}

{
  "version": "1.0",
  "permissions": {
    "onlyAllow": [
      "read",
      "write",
      "edit",
      "snowflake_sql_execute",
      "skill(bundled:*)",
      "skill(profile:*)"
    ],
    "defaultMode": "deny"
  }
}

{
  "version": "1.0",
  "permissions": {
    "deny": [
      "bash(rm:*)",
      "bash(curl:*)",
      "bash(wget:*)"
    ],
    "dangerouslyAllowAll": false,
    "defaultMode": "allow"
  }
}

{
  "version": "1.0",
  "permissions": {
    "onlyAllow": [
      "read", "write", "edit", "bash", "snowflake_sql_execute",
      "skill(bundled:*)", "skill(profile:*)",
      "mcp(https://*.mycompany.com/*)",
      "account(mycompany-*)"
    ],
    "deny": [
      "bash(rm:*)",
      "bash(curl:*)",
      "skill(remote:*)"
    ],
    "defaultMode": "allow",
    "dangerouslyAllowAll": false
  },
  "settings": {
    "forceNoHistoryMode": true,
    "forceSandboxEnabled": true,
    "forceSandboxMode": "regular"
  },
  "required": {
    "minimumVersion": "0.26.0"
  },
  "files": {
    "connectionsFile": "/etc/cortex/connections.toml",
    "mcpFile": "/etc/cortex/mcp.json"
  },
  "ui": {
    "showManagedBanner": true,
    "bannerText": "Managed by IT Security - policy questions: security@mycompany.com",
    "hideDangerousOptions": true
  }
}

Verification¶

To confirm that managed settings are active and review what restrictions are applied, inspect the welcome banner on startup. When managed settings are present and showManagedBanner is true, a banner is shown at the top of the session output.

To check the enforcement config path for your platform, verify whether the file exists at the OS-specific path listed in File locations.