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

​
Scopes and precedence

Each rule has a scope, a subject_id, and a full settings object. Rules exist per deployment kind (deployment_kind: ai_watch, the default, or cli). 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 root.

​
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 organization root is read-only through this API. It is derived from the deployment settings of your organization keys (the strictest across your deployments for that kind); edit it with Manage settings on the deployment card. PATCH or DELETE on the root returns 409, and POST with scope: "organization" returns 422. POST before any deployment exists for the kind returns 409 missing_org_root.

​
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.
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 deployment kind, not per device, so while any rule of the kind 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.
The same merge produces the organization root from your deployments.

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

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

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