Organization settings

Organization settings are the org-wide configuration of your Watcher deployment. You manage them on the Analyzer's Organization page. They are server-side and apply to everyone in the organization. Client behavior resolves on each developer's machine instead. This includes blocking review thresholds and enforcement mode. You set these in the Watcher client's settings. Admins can distribute and lock those centrally too. Use managed client settings below.

The Organization page is visible only to users allowed to read organization settings. Editing requires org:settings:write, which admins have through their role. WorkOS can also assign this permission to custom roles.

Roles

Role	Access
admin	Organization metrics, all sessions, and organization settings.
org-viewer	Organization metrics and all session findings. Session content, including summaries, is limited to their own sessions. No organization-settings access.
member	Their own sessions. No organization metrics or settings access.

In proxy mode, the trusted role header selects the role. In WorkOS-backed SSO, environment setup creates org-viewer with its default grants; assign it to the intended users. Watcher supplies built-in role defaults even if their grants are removed in WorkOS. WorkOS can add permissions to these roles or define custom roles with different grants. API keys use their own explicit grants.

Settings

• Display name. The organization name shown across the dashboard and in notifications.
• Flag threshold. Sessions scored at or above this number are flagged for review. The default is 7. A session is flagged when any numeric score in one of its grades reaches the threshold. Blocking-review decisions whose score reaches it are alerted on as well.
• Restrict admin session content access. Off by default. When enabled, it overrides blanket content grants, including admins' and API keys'. Users keep access to their own content and sessions with active approvals. Aggregates and findings are unchanged; findings can still contain transcript excerpts. Admins can approve their own requests, revoke approvals, or turn this setting off. Slack alerts are unaffected.
• Slack notifications. An on/off toggle plus an incoming-webhook URL. This is for the channel that receives flag alerts. When a session is flagged, Watcher sends at most one notification for it. The notification carries the grader's summary, the flagged scores, and a link back to your Analyzer. It does not include the session transcript. Flagged blocking-review decisions are alerted individually as they happen. Each alert also includes the permission request that was under review. This is the tool name, its arguments, and the working directory. Before sending, Watcher replaces credentials it recognizes in the summary, its title, and the permission request with [REDACTED]. It recognizes common formats, such as provider API keys, bearer tokens, passwords in URLs, private keys, and values assigned to secret-named variables. A secret in another format can still appear. Redaction applies only to the message sent to Slack. Stored grades and transcripts keep the original text, and so does the copy of the notification title and summary that Watcher stores with the session. The webhook URL is write-only. After saving, the page shows only that a webhook is configured and the URL's last four characters. The URL must use https://. It must not include a username or a port. Notifications are sent only when the toggle is on and a webhook is configured.
• Slack alert details (under Data Privacy). Full details (default) sends the alerts described above. Findings and aggregates only uses the same access rules as Watcher: scores, decision explanations, action items, counts, attribution, and links remain available; session summaries and raw tool content are omitted. Findings can still contain transcript excerpts. This setting also applies to deployment-managed webhooks.

Full-detail Slack alerts can expose session content to channel members who lack Watcher content permissions. Restrict channel membership accordingly or choose Findings and aggregates only. This choice is independent of the admin content restriction; Analyzer links still require the viewer's usual permissions or approval.

Deployment-managed Slack webhook

A self-hosted deployment can supply the Slack webhook URL itself by setting the SLACK_WEBHOOK_URL environment variable on the Watcher API, instead of an admin saving one in organization settings. Where to set it depends on how the deployment runs: it is the WATCHER_SLACK_WEBHOOK_URL entry in .env for the Docker Compose bundle (applied with docker compose up -d xylon-api, since a plain restart keeps the old value) and the SLACK_WEBHOOK_URL key of the Kubernetes Secret the chart reads. It is a self-hosting setting: Watcher Cloud never sets it.

When it is set:

• It takes precedence over the URL saved in organization settings, which is not consulted at all (it stays stored, and applies again if the variable is removed).
• The destination is fixed by the deployment. While the variable is set, it cannot be changed from the Analyzer, so use it when the deployment, rather than an admin, should own where alerts land.
• The webhook URL becomes read only. Organization settings report that the webhook is managed by the deployment and show the last four characters of the deployment's URL, and requests that try to change or clear the URL are rejected.
• The on/off toggle, alert details, and flag threshold stay in organization settings, so turning notifications off there still sends nothing.
• The destination may be an internal address, such as a relay in your network that forwards to Slack. A URL saved in organization settings must resolve to a public address; this variable is set by whoever deploys Watcher, so it is not held to that. It must use https:// or http://, with no username and no port (an explicit :443 counts as a port). An https:// destination has its certificate verified on every send against the public roots the API image ships, so the relay needs a publicly trusted certificate. If the API runs behind an egress proxy (HTTPS_PROXY), list the relay in NO_PROXY or the POST goes through the proxy. A failed handshake or connection is logged on the API as Slack webhook request failed and nothing is delivered.
• http:// is accepted for a relay on a trusted network that does not terminate TLS, and it is the weaker choice. It sends the notification, and the webhook URL itself, in cleartext with no certificate verification. The URL's path is the credential that lets anyone holding it post to the channel, so anything that can observe the traffic can take the destination over. Use http:// only on a network you trust to carry both, and prefer https:// everywhere else. The API logs a warning at startup naming the scheme and host, never the path. This applies to this variable only: a URL saved in organization settings must still use https://.
• The API refuses to start on a value that breaks those rules, so the mistake surfaces at deploy time rather than as alerts that never arrive. Watcher never falls back to the URL saved in organization settings, because that would send your alerts to a destination the deployment did not choose.
• The last four characters of the URL are visible to every admin, so that they can tell which destination is in effect.

Data retention

The Data Retention tab controls how long Watcher stores session content. By default, automatic retention is disabled. Session content is retained indefinitely.

Turn on Scrub inactive sessions and set a retention period between 7 and 365 days. Watcher then removes content from any session whose latest recorded activity is older than that period. Turning the policy off retains future session content indefinitely. It does not restore content that has already been scrubbed.

Scrub one session removes the stored messages and tool-call content for a specific session. This requires confirmation. The session record, historical activity, message count, and trajectory grades remain available. See Retention and deletion for the complete data lifecycle.

The same controls are available through the HTTP API. Set or disable automatic retention with PATCH /api/v1/organization/settings:

{
  "session_content_retention_days": 30
}

Set session_content_retention_days to null to disable the policy. Scrub one session with DELETE /api/v1/sessions/{session_id}/content.

Managed client settings

The Managed Settings page lets admins author the organization's Watcher client configuration once. They can distribute it to every developer machine. The document is a YAML overlay on the client's built-in defaults. It can carry client review settings. For example, which graders run at each stage of blocking review. It can also include tool thresholds, command rules, and the enforcement mode. Trailing review runs on the server. It is not configured by this document. Gateway hooks also resolve this saved document on the server. This includes its enforcement mode. Distribution to developer machines does not affect this.

Every save is kept as a new version. How a save reaches machines is the page's "Distribute via Watcher" toggle. This is inside its "Advanced settings" section.

Two options:

• Toggle on (the default for new organizations). Each running client pulls the saved document every few minutes. It installs it as the machine's admin settings baseline. Saving is what rolls a change out. Review the document before you save it.
• Toggle off. Watcher distributes nothing. Ship the saved YAML to ~/.apollo_monitor/settings.yaml on each machine with your MDM tooling instead. The document works identically however it is delivered. Ship exactly the saved version: Watcher grades calls on the server against the saved document, so a machine running a different file is judged by settings it does not have.

Organizations that predate this default keep the setting they already have. An organization that has been distributing through an MDM stays that way. Turning the toggle on hands the whole fleet the document currently saved. Read it first. Until an organization saves its first document the toggle changes nothing. With nothing to pull, clients keep the settings file they already have.

Individual values can be marked locked. This prevents the developer's local settings from overriding them. Unlocked values remain local defaults the developer can change. Reading the document requires permission to read organization settings. Saving it requires write permission.

The document also covers profiles. An entry in its profiles map carries that profile's configuration. Per-profile overrides roll out through the same single document. For example, stricter thresholds under a focus profile. active_profile picks the machine default. It can be locked to pin every machine to one profile. The example below does this with the profile it defines. Add content_permission: locked to an entry to lock everything that profile sets in one line. The "Active profile" control is above "Advanced settings". It sets active_profile directly, without editing YAML. It offers three of the four built-in profiles: Default, Human in the Loop, and Auto. The fourth, Skip Permissions, turns blocking review off, so the control leaves it out. To pin it for the organization, set active_profile: skip-permissions in the YAML. When the YAML pins a profile the control does not list, the page shows that profile's name instead of a choice.

version: 1
active_profile:
  value: focus
  permission: locked
profiles:
  focus:
    name: Focus
    tool_thresholds:
      Bash:
        flag_threshold: 2
        deny_threshold: 5

Honoring .watcher-ignore files

watcher_ignore_files.enabled decides whether clients honor .watcher-ignore files. These files keep the sessions started in one directory from being uploaded or LLM-graded. It is off by default. No directory is excluded until you turn it on. Turning it on gives every developer on the fleet that option in the directories they work in. Sessions a marker covers are not ingested. They never appear in the Analyzer. Deterministic blocking review still applies to them.

Like the enforcement mode, the switch is machine-wide and admin-only. It resolves from the machine's admin settings baseline alone. A developer cannot enable it from their own settings file or from a profile. It takes the same value and permission form as any other managed value:

watcher_ignore_files:
  enabled:
    value: true
    permission: locked

Red-team drill

The page also offers a downloadable red-team drill. This is a prompt written for an AI assistant running on a developer's machine. It carries the document above, how it is distributed, and the settings reference. Send it to a developer who has the client installed. Their assistant checks the install. It then works out the smallest change to that one machine. This change gets an ordinary command held for review. The assistant turns enforcement on if it is not already on. It lowers a tool's flag threshold if the organization's own is too high to hold anything ordinary. It then asks which threats the team cares about. It probes each one against the organization's real thresholds. Finally, it restores the machine.

What the drill can change on a machine is bounded by the document. A setting the document locks cannot be overridden from the machine at all. The drill is written to report that rather than route around it. It names the locked key. It asks an administrator to unlock it here. Unlocking allows local overrides on every machine receiving the document. Review the fleet impact before changing the lock. If nothing can be unlocked in time, the drill runs its threat probes without the demonstration.

In observe mode nothing is ever blocked. A team running one cannot see what blocking review does without turning enforcement on somewhere. The drill does that on one machine instead of the fleet. Its configuration changes are local. They are reverted at the end. The session itself is ingested. This includes the probes. It is visible in the Analyzer like any other. The assistant reads each probe's result there, or asks the developer to open the session and read it back. Containment is instruction, not sandboxing. The prompt tells the assistant to keep every probe inside a scratch directory and to use dummy credentials. An assistant that departs from it is not prevented by Watcher.

Members

The Members tab lists the organization's users. In WorkOS-backed SSO mode, admins manage members and their roles here. In proxy mode the roster is read-only. Membership and roles are managed by your identity provider and reverse proxy. Users appear after their first sign-in.

API keys

In WorkOS-backed SSO mode, the API Keys tab is where you create and revoke the organization's API keys. These are for the HTTP API and the Python SDK. In proxy mode there is no API Keys tab. API access is governed by your reverse proxy.

Choose session permissions by what the key may access:

• sessions:ingest uploads sessions that belong to no developer. It can also add turns to an existing conversation's session, whoever owns it, when it sends that conversation's Claude Code session ID or Codex thread ID. It cannot read any session. Treat such a key as able to append to any member's conversation whose ID it knows, and revoke it if it leaks.
• sessions:write:any writes any session, and can attribute uploads to a developer. A sessions:write:any key that names no developer can append to any session.
• sessions:findings:read:any reads session metadata, grades, and problem explanations across the organization, excluding session summaries.
• sessions:content:read:any reads transcripts, messages, and session summaries. See content access rules.
• sessions:grade:any triggers standard grading on other users' stored sessions. Caller-selected graders also require content access. See grading access rules.
• sessions:aggregates:read:any reads organization-wide session counts, trends, and risk metrics. See aggregate access rules.

See Two recorders for how a conversation's session gets its owner.