Skip to main content
By default every device on an AI Watch deployment receives the settings you pick under Manage settings on the deployment card. Policy rules let you narrow those settings to a team, group, user or single machine without creating another deployment: pilot Enforce with one team, turn Sessions off for a user, or lock down a specific laptop. After the switch-over, devices take these settings from policy rules instead. Policy rules are managed through the /api/v1/ai-watch/policy-rules API. Calls require the Manage MDM configuration capability (manage_mdm_config) — the same one that manages deployments.
Turning on policy rules takes two steps. First, Runlayer enables the Endpoint configuration page for your organization (contact Runlayer). Until your organization switches over, every device keeps receiving the settings of its own deployment, and the organization default and rules you edit through the API are stored but not yet applied to devices; their audit entries carry applied: false. After the switch-over, every device without a narrower rule receives the organization default instead of its deployment’s settings, so configure the default and your rules first: the rule list names every deployment whose settings still differ from the default (diverging_deployment_ids). That list covers the default only: rules you have already created are meant to change what their devices receive after the switch-over, so review them in the same response, and preview a single user or machine with GET /ai-watch/policy-rules/check. Then, once the list is empty or you have accepted the default, and your rules say what you intend, an admin with Manage MDM configuration selects Switch over on Settings → Endpoint configuration, reviews Deployments whose settings change, and confirms. Devices move on their next config sync. The switch is one way: you cannot undo it; reverting requires Runlayer support.

Scopes and precedence

Each rule has a scope, a subject_id, and a full settings object. One set of rules covers every device: AI Watch devices act on every setting, Runlayer CLI devices only on remove_uv_tool. Resolution runs top-down and stops at the first tier that has a match: device > user > team/group > organization. A user rule fully replaces the team/group tier — it is not merged with it. A device whose user cannot be resolved, or whose user is deactivated, receives the organization default. Team membership is owner-managed: members cannot leave a team themselves, so a team rule cannot be escaped by leaving the team. Group membership follows your identity provider.

Shared machines

Policy is resolved per user on each machine, and the machine receives the strictest merge across everyone who has used it in the last 30 days: if one of two recent users is on an Enforce rule, the machine runs Enforce for both. A user who has not touched the machine for 30 days stops contributing. A device rule skips this merge entirely and applies to the machine regardless of who is signed in. GET /ai-watch/policy-rules/check?device_id=… shows exactly what a machine receives; ?user_id=… shows what a user’s own tier resolves to. The settings page’s Check policy drawer is the same lookup: pick a user or a device and it shows the effective settings, which tier decided them, every policy that contributed, and every policy that matched but was overridden by a narrower one, each linked back to the policy. The same lookup runs inline when you pick a user or device target in the create-policy and add-target dialogs, so you see what that target gets today and whether the save will take precedence or be refused.
The organization default (scope: "organization") is the fallback for every device no narrower rule matches. It starts as Monitor with Sessions off: it observes and collects nothing, and it is never derived from your deployments. Edit its settings and description with PATCH like any rule; it cannot be renamed or deleted (409), and POST with scope: "organization" returns 422 because it exists once per organization, created the first time anything reads or writes rules.Policy groups (/api/v1/ai-watch/policy-groups) are how the settings page works with rules: one named policy applied to several subjects at once. A group is one rule per subject sharing a policy_group_id, name and settings; POST creates them together, PATCH on the group fans an edit out to every rule, POST .../subjects adds a subject by copying the group’s policy and DELETE .../subjects/{rule_id} removes one. A policy takes up to 20 subjects. A rule that belongs to a multi-subject policy cannot be edited through PATCH /ai-watch/policy-rules/{rule_id} (409); edit the policy instead, so its subjects never drift apart. Devices still resolve against the individual rules, so a group changes nothing about how the strictest-wins merge behaves.

Strictest merge

When several team or group rules apply to one user, each setting resolves to its strictest value:
  • mode: enforce > protect > monitor.
  • Booleans (sessions, browser_extension_enabled, detect_*, remove_uv_tool): on if any rule turns it on.
  • browser_extension_chrome_extension_settings: on only if every rule that installs the browser extension turns it on. AI Watch’s machine-level Chrome ExtensionSettings entry hides every user’s Google Admin or per-user ExtensionSettings on that Mac.
  • browser_extension_chrome_customer_managed: on only if every rule that installs the browser extension turns it on. It removes AI Watch’s Chrome force-install for the whole Mac, so on a shared Mac one user whose rule leaves Chrome to AI Watch keeps the force-install for everyone.
sessions and browser_sessions are enforced by the device: /config delivers the resolved value and the agent stops collecting. The server-side ingest gate is per organization, not per device, so while any rule has Sessions on, the backend still accepts session content from a device whose own rule turns it off. Treat a per-user or per-device Sessions off as a client control, not a server boundary (tracked in ENG-7000).
  • project_depth, project_timeout: the largest value.
  • browser_mode / browser_sessions: null means “follow mode / sessions”, so each rule contributes the browser value it actually delivers before the strictest is taken.

Settings payload

settings carries the full policy; on PATCH, sending settings replaces the whole object so an explicit "browser_mode": null is distinguishable from an untouched field.
mode is required. Every other field defaults to the value shown: sessions: true, browser_mode / browser_sessions null (follow mode / sessions), browser_extension_enabled, browser_extension_chrome_customer_managed, browser_extension_chrome_extension_settings and every detect_* flag false, project_depth: 7, project_timeout: 60, remove_uv_tool: false. project_depth is clamped to 1–20 and project_timeout to 1–300, matching the scan tuning bounds.

Endpoints

After the switch-over, deployments no longer carry policy. Creating or updating a deployment (POST /mdm/configurations, PATCH /mdm/configurations/{config_id}) with mode, sessions, or any other policy setting returns 422; set it on a policy rule instead. Create a rule that puts one team in Enforce with Sessions on:
Fields not sent in settings take the defaults listed above, so this rule also turns every detection phase off for that team; send the full object when you mean to keep the deployment’s values.

How devices pick up a rule

Devices resolve their policy on check-in and apply it on their next settings sync, which runs every 15 minutes. Editing a rule’s settings lands on the next sync of every device already on that rule; creating or deleting a rule re-resolves the devices it can reach. Each device on the Devices list shows its effective_policy: the rule it resolved to (source_rule) and every rule that contributed (merged_rule_ids). Filter the list by policy_rule_ids to see which devices a rule reaches; like device_count, it covers devices seen in the last 30 days. The list has one row per user on a device, so a machine shared by several users appears once for each of them and the filtered count can be higher than device_count. Every rule change and every device that moves between rules is written to the audit log (ai_watch_policy_rule_created / _updated / _deleted, ai_watch_effective_policy_changed). A device move carries applied: true when the device receives the new rule, false until your organization has switched over. The switch-over itself is recorded once as ai_watch_policy_rules_cutover, with the organization default and the deployments whose settings differed.

Deploy AI Watch

Create deployments and manage the organization-wide settings

Endpoint modes

What Monitor, Protect and Enforce do on the device

Enforce policy

Allowlists and built-in tool blocks applied in Enforce

Browser extension

Browser mode and Sessions behavior delivered by these settings