Managed settings (organization policy)¶

Managed settings allow IT administrators to enforce Cortex Code CLI behavior across an organization. Settings are deployed to a system-owned file that users can’t modify. These settings take precedence over all user-level configuration.

When managed settings are present, the CLI displays a banner at startup indicating that it’s running in managed mode.

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¶

Controls which tools, skills, MCP servers, and Snowflake accounts the CLI may use. For the full pattern syntax, see Permission patterns.

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

settings¶

Forces specific runtime behaviors that can’t be overridden by users.

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

The sandbox limits which directories the CLI can read and write during a session. It adds a confirmation step before tools access paths outside the pre-approved set. "regular" mode requires user confirmation for each new directory; "autoAllow" mode trusts all directories within the working tree without prompting. Sandbox is an experimental feature. For details, see Sandbox.

required¶

Enforces a minimum CLI version. The CLI exits with an error if the installed version doesn’t meet the requirement.

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

Use this field to ensure all users are on a version that supports any security fix or feature your policy depends on.

defaults¶

Sets organization-recommended defaults that users can override in their own settings.json. Unlike the settings section, these are suggestions, not enforcement.

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

files¶

Points the CLI to admin-provided configuration files. These are loaded in addition to, or instead of, the user’s own equivalents.

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

ui¶

Customizes UI elements to indicate managed state.

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

Pattern reference¶

bash(command:*) filtering¶

When using bash filtering patterns, the filter matches the first token of the shell command. For example, "bash(git:*)" permits git status, git commit, and any other git subcommand, but blocks curl, python, and any other command.

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¶

Basic corporate setup¶

Allow all default tools but block bypass mode and display a managed banner.

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

Restrict to approved Snowflake accounts¶

Only allow connections to specific accounts. Users who try to connect to any other account see an error.

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

Lock down to approved tools only¶

Only allow file reading, SQL execution, and bundled skills. Block all bash, MCP, and user-installed skills.

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

Allow bash but block dangerous commands¶

Permit bash access but explicitly deny rm, curl, and wget.

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

High-security deployment¶

Force no history, force sandbox, block bypass mode, restrict to specific accounts and MCP servers, and block remote skill installation.

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